@shepai/cli 1.122.1 → 1.122.2-pr367.fdba557

package/dist/packages/core/src/application/ports/output/services/index.d.ts

@@ -17,4 +17,6 @@ export { GitPrError, GitPrErrorCode } from './git-pr-service.interface.js';
 export type { IIdeLauncherService, LaunchIdeInput, LaunchIdeResult, LaunchIdeSuccess, LaunchIdeFailed, } from './ide-launcher-service.interface.js';
 export type { IDaemonService, DaemonState } from './daemon-service.interface.js';
 export type { IDeploymentService, DeploymentStatus } from './deployment-service.interface.js';
+export type { ITunnelService, TunnelUrlChangeHandler } from './tunnel-service.interface.js';
+export type { IWebhookService, WebhookEvent, WebhookValidationResult, } from './webhook-service.interface.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/packages/core/src/application/ports/output/services/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../../../packages/core/src/application/ports/output/services/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,YAAY,EAAE,qBAAqB,EAAE,aAAa,EAAE,MAAM,uCAAuC,CAAC;AAClG,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,wBAAwB,EACxB,4BAA4B,GAC7B,MAAM,uCAAuC,CAAC;AAC/C,YAAY,EACV,uBAAuB,EACvB,qBAAqB,GACtB,MAAM,iCAAiC,CAAC;AACzC,YAAY,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AACtE,YAAY,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AAC3E,YAAY,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AACtF,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AACnF,YAAY,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AACzE,YAAY,EAAE,oBAAoB,EAAE,MAAM,qCAAqC,CAAC;AAChF,YAAY,EACV,aAAa,EACb,QAAQ,EACR,cAAc,EACd,WAAW,EACX,aAAa,EACb,cAAc,GACf,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC3E,YAAY,EACV,mBAAmB,EACnB,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,eAAe,GAChB,MAAM,qCAAqC,CAAC;AAC7C,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AACjF,YAAY,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../../../packages/core/src/application/ports/output/services/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,YAAY,EAAE,qBAAqB,EAAE,aAAa,EAAE,MAAM,uCAAuC,CAAC;AAClG,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,wBAAwB,EACxB,4BAA4B,GAC7B,MAAM,uCAAuC,CAAC;AAC/C,YAAY,EACV,uBAAuB,EACvB,qBAAqB,GACtB,MAAM,iCAAiC,CAAC;AACzC,YAAY,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AACtE,YAAY,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AAC3E,YAAY,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AACtF,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AACnF,YAAY,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AACzE,YAAY,EAAE,oBAAoB,EAAE,MAAM,qCAAqC,CAAC;AAChF,YAAY,EACV,aAAa,EACb,QAAQ,EACR,cAAc,EACd,WAAW,EACX,aAAa,EACb,cAAc,GACf,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC3E,YAAY,EACV,mBAAmB,EACnB,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,eAAe,GAChB,MAAM,qCAAqC,CAAC;AAC7C,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AACjF,YAAY,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAC9F,YAAY,EAAE,cAAc,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AAC5F,YAAY,EACV,eAAe,EACf,YAAY,EACZ,uBAAuB,GACxB,MAAM,gCAAgC,CAAC"}

package/dist/packages/core/src/application/ports/output/services/tunnel-service.interface.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Tunnel Service Interface
+ *
+ * Output port for managing a reverse tunnel that exposes local endpoints
+ * to the public internet. Used to receive webhooks from external services
+ * (e.g., GitHub) when running locally.
+ *
+ * Implementations must:
+ * - Start a tunnel process pointing at a local port
+ * - Expose only a specific URL path (e.g., /api/webhooks)
+ * - Detect when the public URL changes (tunnel reconnection)
+ * - Support graceful shutdown
+ */
+export type TunnelUrlChangeHandler = (newUrl: string) => void | Promise<void>;
+export interface ITunnelService {
+    /**
+     * Start the tunnel, exposing a local port to the internet.
+     *
+     * @param localPort - Local port to tunnel traffic to
+     * @returns The public URL assigned by the tunnel provider
+     */
+    start(localPort: number): Promise<string>;
+    /**
+     * Stop the tunnel and clean up the child process.
+     */
+    stop(): Promise<void>;
+    /**
+     * Get the current public URL, or null if the tunnel is not running.
+     */
+    getPublicUrl(): string | null;
+    /**
+     * Register a callback that fires when the tunnel URL changes
+     * (e.g., after a reconnection assigns a new random subdomain).
+     */
+    onUrlChange(handler: TunnelUrlChangeHandler): void;
+    /**
+     * Whether the tunnel process is currently running.
+     */
+    isRunning(): boolean;
+}
+//# sourceMappingURL=tunnel-service.interface.d.ts.map

package/dist/packages/core/src/application/ports/output/services/tunnel-service.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tunnel-service.interface.d.ts","sourceRoot":"","sources":["../../../../../../../../packages/core/src/application/ports/output/services/tunnel-service.interface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,MAAM,sBAAsB,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE9E,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;IACH,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAE1C;;OAEG;IACH,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEtB;;OAEG;IACH,YAAY,IAAI,MAAM,GAAG,IAAI,CAAC;IAE9B;;;OAGG;IACH,WAAW,CAAC,OAAO,EAAE,sBAAsB,GAAG,IAAI,CAAC;IAEnD;;OAEG;IACH,SAAS,IAAI,OAAO,CAAC;CACtB"}

package/dist/packages/core/src/application/ports/output/services/tunnel-service.interface.js

@@ -0,0 +1,14 @@
+/**
+ * Tunnel Service Interface
+ *
+ * Output port for managing a reverse tunnel that exposes local endpoints
+ * to the public internet. Used to receive webhooks from external services
+ * (e.g., GitHub) when running locally.
+ *
+ * Implementations must:
+ * - Start a tunnel process pointing at a local port
+ * - Expose only a specific URL path (e.g., /api/webhooks)
+ * - Detect when the public URL changes (tunnel reconnection)
+ * - Support graceful shutdown
+ */
+export {};

package/dist/packages/core/src/application/ports/output/services/webhook-service.interface.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Webhook Service Interface
+ *
+ * Output port for managing webhook registrations with external services
+ * (e.g., GitHub) and processing incoming webhook events.
+ *
+ * Works alongside the polling-based PrSyncWatcher to provide near-instant
+ * event delivery when a tunnel is available, with polling as fallback.
+ */
+/**
+ * Parsed webhook event from an external service.
+ */
+export interface WebhookEvent {
+    /** Source service (e.g., 'github') */
+    source: string;
+    /** Event type (e.g., 'pull_request', 'check_suite') */
+    eventType: string;
+    /** Delivery ID for deduplication */
+    deliveryId: string;
+    /** Full event payload */
+    payload: Record<string, unknown>;
+}
+/**
+ * Result of webhook signature validation.
+ */
+export interface WebhookValidationResult {
+    valid: boolean;
+    error?: string;
+}
+export interface IWebhookService {
+    /**
+     * Register webhooks for all tracked repositories.
+     *
+     * @param publicUrl - The public tunnel URL where webhooks will be received
+     */
+    registerWebhooks(publicUrl: string): Promise<void>;
+    /**
+     * Update the webhook URL for all registered webhooks.
+     * Called when the tunnel reconnects with a new URL.
+     *
+     * @param newUrl - The new public tunnel URL
+     */
+    updateWebhookUrl(newUrl: string): Promise<void>;
+    /**
+     * Remove all registered webhooks (cleanup on shutdown).
+     */
+    removeWebhooks(): Promise<void>;
+    /**
+     * Validate an incoming webhook request signature.
+     *
+     * @param payload - Raw request body
+     * @param signature - Signature header value
+     * @param secret - The webhook secret used for HMAC
+     * @returns Validation result
+     */
+    validateSignature(payload: string, signature: string, secret: string): WebhookValidationResult;
+    /**
+     * Process an incoming webhook event.
+     * Routes the event to the appropriate handler (e.g., PR status update).
+     *
+     * @param event - The parsed webhook event
+     */
+    handleEvent(event: WebhookEvent): Promise<void>;
+}
+//# sourceMappingURL=webhook-service.interface.d.ts.map

package/dist/packages/core/src/application/ports/output/services/webhook-service.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-service.interface.d.ts","sourceRoot":"","sources":["../../../../../../../../packages/core/src/application/ports/output/services/webhook-service.interface.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,uDAAuD;IACvD,SAAS,EAAE,MAAM,CAAC;IAClB,oCAAoC;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,yBAAyB;IACzB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnD;;;;;OAKG;IACH,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEhD;;OAEG;IACH,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEhC;;;;;;;OAOG;IACH,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,uBAAuB,CAAC;IAE/F;;;;;OAKG;IACH,WAAW,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACjD"}

package/dist/packages/core/src/application/ports/output/services/webhook-service.interface.js

@@ -0,0 +1,10 @@
+/**
+ * Webhook Service Interface
+ *
+ * Output port for managing webhook registrations with external services
+ * (e.g., GitHub) and processing incoming webhook events.
+ *
+ * Works alongside the polling-based PrSyncWatcher to provide near-instant
+ * event delivery when a tunnel is available, with polling as fallback.
+ */
+export {};

package/dist/packages/core/src/infrastructure/di/container.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"container.d.ts","sourceRoot":"","sources":["../../../../../../packages/core/src/infrastructure/di/container.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,kBAAkB,CAAC;AAC1B,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAoHrC;;;;;;GAMG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,OAAO,SAAS,CAAC,CAiUrE;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,IAAI,OAAO,CAEhD;AAED;;;GAGG;AACH,OAAO,EAAE,SAAS,EAAE,CAAC"}
+{"version":3,"file":"container.d.ts","sourceRoot":"","sources":["../../../../../../packages/core/src/infrastructure/di/container.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,kBAAkB,CAAC;AAC1B,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAwHrC;;;;;;GAMG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,OAAO,SAAS,CAAC,CA+UrE;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,IAAI,OAAO,CAEhD;AAED;;;GAGG;AACH,OAAO,EAAE,SAAS,EAAE,CAAC"}

package/dist/packages/core/src/infrastructure/di/container.js

@@ -27,6 +27,8 @@ import { JsonDrivenIdeLauncherService } from '../services/ide-launchers/json-dri
 import { DaemonPidService } from '../services/daemon/daemon-pid.service.js';
 import { DeploymentService } from '../services/deployment/deployment.service.js';
 import { AttachmentStorageService } from '../services/attachment-storage.service.js';
+import { CloudflareTunnelService } from '../services/tunnel/cloudflare-tunnel.service.js';
+import { GitHubWebhookService } from '../services/webhook/github-webhook.service.js';
 import { AgentExecutorFactory } from '../services/agents/common/agent-executor-factory.service.js';
 import { AgentExecutorProvider } from '../services/agents/common/agent-executor-provider.service.js';
 import { StructuredAgentCallerService } from '../services/agents/common/structured-agent-caller.service.js';
@@ -170,6 +172,18 @@ export async function initializeContainer() {
     container.register('AttachmentStorageService', { useToken: AttachmentStorageService });
     const deploymentService = new DeploymentService();
     container.registerInstance('IDeploymentService', deploymentService);
+    // Register tunnel and webhook services
+    container.register('ITunnelService', {
+        useFactory: () => new CloudflareTunnelService(),
+    });
+    container.register('IWebhookService', {
+        useFactory: (c) => {
+            const featureRepo = c.resolve('IFeatureRepository');
+            const gitPrService = c.resolve('IGitPrService');
+            const notifService = c.resolve('INotificationService');
+            return new GitHubWebhookService(featureRepo, gitPrService, notifService, execFn);
+        },
+    });
     // Register agent infrastructure
     container.register('IAgentRunRepository', {
         useFactory: (c) => {

package/dist/packages/core/src/infrastructure/services/agents/feature-agent/feature-agent-graph.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"feature-agent-graph.d.ts","sourceRoot":"","sources":["../../../../../../../../packages/core/src/infrastructure/services/agents/feature-agent/feature-agent-graph.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0B,KAAK,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AACxF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+DAA+D,CAAC;AAOpG,OAAO,EAAmB,KAAK,aAAa,EAAE,MAAM,6BAA6B,CAAC;AASlF,OAAO,EAAE,sBAAsB,EAAE,KAAK,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAE5E;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,cAAc,CAAC;IACzB,aAAa,CAAC,EAAE,IAAI,CAAC,aAAa,EAAE,UAAU,CAAC,CAAC;CACjD;AA0HD;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CACrC,cAAc,EAAE,qBAAqB,GAAG,cAAc,EACtD,YAAY,CAAC,EAAE,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAwEnC"}
+{"version":3,"file":"feature-agent-graph.d.ts","sourceRoot":"","sources":["../../../../../../../../packages/core/src/infrastructure/services/agents/feature-agent/feature-agent-graph.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0B,KAAK,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AACxF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+DAA+D,CAAC;AAOpG,OAAO,EAAmB,KAAK,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAclF,OAAO,EAAE,sBAAsB,EAAE,KAAK,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAE5E;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,cAAc,CAAC;IACzB,aAAa,CAAC,EAAE,IAAI,CAAC,aAAa,EAAE,UAAU,CAAC,CAAC;CACjD;AAwID;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CACrC,cAAc,EAAE,qBAAqB,GAAG,cAAc,EACtD,YAAY,CAAC,EAAE,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAgFnC"}

package/dist/packages/core/src/infrastructure/services/agents/feature-agent/feature-agent-graph.js

@@ -11,7 +11,7 @@ import { createRepairNode } from './nodes/repair.node.js';
 import { validateSpecAnalyze, validateSpecRequirements } from './nodes/schemas/spec.schema.js';
 import { validateResearch } from './nodes/schemas/research.schema.js';
 import { validatePlan, validateTasks } from './nodes/schemas/plan.schema.js';
-import { readSpecFile, safeYamlLoad, createNodeLogger } from './nodes/node-helpers.js';
+import { readSpecFile, safeYamlLoad, createNodeLogger, getCompletedPhases, } from './nodes/node-helpers.js';
 // Re-export state types for consumers
 export { FeatureAgentAnnotation } from './state.js';
 /**
@@ -54,6 +54,18 @@ function createPlanTasksValidator() {
     const log = createNodeLogger('validate:plan+tasks');
     return async (state) => {
         log.activate();
+        // Skip validation when the successor phase (implement) is already completed.
+        // This proves validation already passed and the pipeline progressed beyond it.
+        // Same logic as createValidateNode's successorPhase guard.
+        if (getCompletedPhases(state.specDir).includes('implement')) {
+            log.info("Successor phase 'implement' already completed, skipping validation");
+            return {
+                lastValidationTarget: 'plan.yaml+tasks.yaml',
+                lastValidationErrors: [],
+                validationRetries: 0,
+                messages: ["[validate:plan+tasks] SKIP (successor 'implement' already completed)"],
+            };
+        }
         log.info('Validating plan.yaml and tasks.yaml');
         const allErrors = [];
         // Validate plan.yaml
@@ -145,9 +157,14 @@ export function createFeatureAgentGraph(depsOrExecutor, checkpointer) {
         .addNode('plan', createPlanNode(executor))
         .addNode('implement', createImplementNode(executor))
         // --- Validate nodes ---
-        .addNode('validate_spec_analyze', createValidateNode('spec.yaml', validateSpecAnalyze))
-        .addNode('validate_spec_requirements', createValidateNode('spec.yaml', validateSpecRequirements))
-        .addNode('validate_research', createValidateNode('research.yaml', validateResearch))
+        // Each validate node receives its SUCCESSOR phase name (the phase that runs
+        // after validation passes). On resume, validation is skipped only when the
+        // successor is already completed — proving this validation already passed.
+        // Using the successor (not the producer) avoids skipping validation when the
+        // producer ran successfully but validation itself failed.
+        .addNode('validate_spec_analyze', createValidateNode('spec.yaml', validateSpecAnalyze, 'requirements'))
+        .addNode('validate_spec_requirements', createValidateNode('spec.yaml', validateSpecRequirements, 'research'))
+        .addNode('validate_research', createValidateNode('research.yaml', validateResearch, 'plan'))
         .addNode('validate_plan_tasks', createPlanTasksValidator())
         // --- Repair nodes ---
         .addNode('repair_spec_analyze', createRepairNode('spec.yaml', executor))

package/dist/packages/core/src/infrastructure/services/agents/feature-agent/nodes/validate.node.d.ts

@@ -6,7 +6,13 @@ type SchemaValidator = (data: unknown) => ValidationResult;
  *
  * On success: resets validationRetries to 0, clears errors.
  * On failure: increments validationRetries, sets errors for repair node.
+ *
+ * @param successorPhase - The phase that runs AFTER this validation passes.
+ *   If provided, skip validation when the successor is already completed — this
+ *   proves the validation already passed in a prior run and the pipeline progressed
+ *   beyond it. Checking the successor (not the producer) avoids skipping validation
+ *   when the producer ran but validation itself failed.
  */
-export declare function createValidateNode(filename: string, schema: SchemaValidator): (state: FeatureAgentState) => Promise<Partial<FeatureAgentState>>;
+export declare function createValidateNode(filename: string, schema: SchemaValidator, successorPhase?: string): (state: FeatureAgentState) => Promise<Partial<FeatureAgentState>>;
 export {};
 //# sourceMappingURL=validate.node.d.ts.map

package/dist/packages/core/src/infrastructure/services/agents/feature-agent/nodes/validate.node.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate.node.d.ts","sourceRoot":"","sources":["../../../../../../../../../packages/core/src/infrastructure/services/agents/feature-agent/nodes/validate.node.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAGhE,KAAK,eAAe,GAAG,CAAC,IAAI,EAAE,OAAO,KAAK,gBAAgB,CAAC;AAE3D;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,eAAe,GACtB,CAAC,KAAK,EAAE,iBAAiB,KAAK,OAAO,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAuDnE"}
+{"version":3,"file":"validate.node.d.ts","sourceRoot":"","sources":["../../../../../../../../../packages/core/src/infrastructure/services/agents/feature-agent/nodes/validate.node.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAQhE,KAAK,eAAe,GAAG,CAAC,IAAI,EAAE,OAAO,KAAK,gBAAgB,CAAC;AAE3D;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,eAAe,EACvB,cAAc,CAAC,EAAE,MAAM,GACtB,CAAC,KAAK,EAAE,iBAAiB,KAAK,OAAO,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAyEnE"}

package/dist/packages/core/src/infrastructure/services/agents/feature-agent/nodes/validate.node.js

@@ -1,14 +1,36 @@
-import { readSpecFile, safeYamlLoad, createNodeLogger } from './node-helpers.js';
+import { readSpecFile, safeYamlLoad, createNodeLogger, getCompletedPhases, } from './node-helpers.js';
 /**
  * Factory that creates a validate node for a specific YAML file.
  *
  * On success: resets validationRetries to 0, clears errors.
  * On failure: increments validationRetries, sets errors for repair node.
+ *
+ * @param successorPhase - The phase that runs AFTER this validation passes.
+ *   If provided, skip validation when the successor is already completed — this
+ *   proves the validation already passed in a prior run and the pipeline progressed
+ *   beyond it. Checking the successor (not the producer) avoids skipping validation
+ *   when the producer ran but validation itself failed.
  */
-export function createValidateNode(filename, schema) {
+export function createValidateNode(filename, schema, successorPhase) {
     const log = createNodeLogger(`validate:${filename}`);
     return async (state) => {
         log.activate();
+        // Skip validation when the successor phase is already completed.
+        // This means: the validation already passed in a prior run AND the next phase
+        // ran successfully. On resume, LangGraph replays nodes from the last checkpoint.
+        // The producer node skips (via getCompletedPhases), but if we only checked the
+        // producer we'd also skip validation when it previously FAILED (since
+        // markPhaseComplete runs before validation). Checking the successor is safe:
+        // if the successor completed, this validation must have passed to get there.
+        if (successorPhase && getCompletedPhases(state.specDir).includes(successorPhase)) {
+            log.info(`Successor phase '${successorPhase}' already completed, skipping validation`);
+            return {
+                lastValidationTarget: filename,
+                lastValidationErrors: [],
+                validationRetries: 0,
+                messages: [`[validate:${filename}] SKIP (successor '${successorPhase}' already completed)`],
+            };
+        }
         log.info(`Validating ${filename}`);
         const content = readSpecFile(state.specDir, filename);
         if (!content) {

package/dist/packages/core/src/infrastructure/services/tunnel/cloudflare-tunnel.service.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Cloudflare Tunnel Service
+ *
+ * Manages a `cloudflared` quick-tunnel that exposes ONLY the webhook
+ * API routes to the public internet via a random *.trycloudflare.com
+ * subdomain.
+ *
+ * Uses the `cloudflared` npm package which handles binary installation
+ * and provides a typed Tunnel API — no need for the user to install
+ * cloudflared separately.
+ *
+ * Security: A lightweight proxy HTTP server is started on a random port
+ * that only forwards requests matching the allowed path prefix
+ * (/api/webhooks) to the main app. The tunnel connects to this proxy,
+ * not the main app server. All other paths return 404.
+ */
+import type { ITunnelService, TunnelUrlChangeHandler } from '../../../application/ports/output/services/tunnel-service.interface.js';
+export interface CloudflareTunnelDeps {
+    createTunnel: (origin: string) => TunnelLike | Promise<TunnelLike>;
+}
+export interface TunnelLike {
+    on(event: 'url', handler: (url: string) => void): void;
+    on(event: 'connected', handler: (connection: {
+        id: string;
+        ip: string;
+        location: string;
+    }) => void): void;
+    on(event: 'error', handler: (error: Error) => void): void;
+    on(event: 'exit', handler: (code: number | null, signal: string | null) => void): void;
+    once(event: string, handler: (...args: unknown[]) => void): void;
+    stop(): void;
+}
+export declare class CloudflareTunnelService implements ITunnelService {
+    private tunnel;
+    private proxyServer;
+    private publicUrl;
+    private readonly urlChangeHandlers;
+    private readonly deps;
+    constructor(deps?: Partial<CloudflareTunnelDeps>);
+    start(localPort: number): Promise<string>;
+    stop(): Promise<void>;
+    getPublicUrl(): string | null;
+    onUrlChange(handler: TunnelUrlChangeHandler): void;
+    isRunning(): boolean;
+    /**
+     * Start a lightweight HTTP proxy on a random port that only forwards
+     * requests with paths starting with ALLOWED_PATH_PREFIX to the main app.
+     * Everything else gets a 404.
+     */
+    private startProxyServer;
+    private stopProxyServer;
+    private stopTunnel;
+    private notifyUrlChange;
+}
+//# sourceMappingURL=cloudflare-tunnel.service.d.ts.map

package/dist/packages/core/src/infrastructure/services/tunnel/cloudflare-tunnel.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloudflare-tunnel.service.d.ts","sourceRoot":"","sources":["../../../../../../../packages/core/src/infrastructure/services/tunnel/cloudflare-tunnel.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,KAAK,EACV,cAAc,EACd,sBAAsB,EACvB,MAAM,wEAAwE,CAAC;AAMhF,MAAM,WAAW,oBAAoB;IACnC,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CACpE;AAED,MAAM,WAAW,UAAU;IACzB,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI,CAAC;IACvD,EAAE,CACA,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,CAAC,UAAU,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,GAC1E,IAAI,CAAC;IACR,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAAG,IAAI,CAAC;IAC1D,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,GAAG,IAAI,CAAC;IACvF,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,GAAG,IAAI,CAAC;IACjE,IAAI,IAAI,IAAI,CAAC;CACd;AAWD,qBAAa,uBAAwB,YAAW,cAAc;IAC5D,OAAO,CAAC,MAAM,CAA2B;IACzC,OAAO,CAAC,WAAW,CAAuB;IAC1C,OAAO,CAAC,SAAS,CAAuB;IACxC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAgC;IAClE,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAuB;gBAEhC,IAAI,GAAE,OAAO,CAAC,oBAAoB,CAAM;IAI9C,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAuEzC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAK3B,YAAY,IAAI,MAAM,GAAG,IAAI;IAI7B,WAAW,CAAC,OAAO,EAAE,sBAAsB,GAAG,IAAI;IAIlD,SAAS,IAAI,OAAO;IAIpB;;;;OAIG;IACH,OAAO,CAAC,gBAAgB;IA0DxB,OAAO,CAAC,eAAe;IAOvB,OAAO,CAAC,UAAU;IAelB,OAAO,CAAC,eAAe;CAgBxB"}

package/dist/packages/core/src/infrastructure/services/tunnel/cloudflare-tunnel.service.js

@@ -0,0 +1,203 @@
+/**
+ * Cloudflare Tunnel Service
+ *
+ * Manages a `cloudflared` quick-tunnel that exposes ONLY the webhook
+ * API routes to the public internet via a random *.trycloudflare.com
+ * subdomain.
+ *
+ * Uses the `cloudflared` npm package which handles binary installation
+ * and provides a typed Tunnel API — no need for the user to install
+ * cloudflared separately.
+ *
+ * Security: A lightweight proxy HTTP server is started on a random port
+ * that only forwards requests matching the allowed path prefix
+ * (/api/webhooks) to the main app. The tunnel connects to this proxy,
+ * not the main app server. All other paths return 404.
+ */
+import { createServer, request as httpRequest } from 'node:http';
+const TAG = '[CloudflareTunnel]';
+const STARTUP_TIMEOUT_MS = 30_000;
+const ALLOWED_PATH_PREFIX = '/api/webhooks';
+async function defaultCreateTunnel(origin) {
+    const { Tunnel } = await import('cloudflared');
+    return Tunnel.quick(origin);
+}
+const defaultDeps = {
+    createTunnel: defaultCreateTunnel,
+};
+export class CloudflareTunnelService {
+    tunnel = null;
+    proxyServer = null;
+    publicUrl = null;
+    urlChangeHandlers = [];
+    deps;
+    constructor(deps = {}) {
+        this.deps = { ...defaultDeps, ...deps };
+    }
+    async start(localPort) {
+        if (this.tunnel) {
+            throw new Error(`${TAG} Tunnel already running at ${this.publicUrl}`);
+        }
+        // Start a proxy server that only forwards webhook routes
+        const proxyPort = await this.startProxyServer(localPort);
+        let tunnel;
+        try {
+            tunnel = await Promise.resolve(this.deps.createTunnel(`http://localhost:${proxyPort}`));
+        }
+        catch (err) {
+            this.stopProxyServer();
+            throw new Error(`${TAG} Failed to create tunnel: ${err.message}`);
+        }
+        this.tunnel = tunnel;
+        return new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => {
+                this.stopTunnel();
+                reject(new Error(`${TAG} Timed out waiting for tunnel URL (${STARTUP_TIMEOUT_MS}ms)`));
+            }, STARTUP_TIMEOUT_MS);
+            tunnel.on('url', (url) => {
+                if (!this.publicUrl) {
+                    // First URL — startup complete
+                    this.publicUrl = url;
+                    clearTimeout(timeout);
+                    // eslint-disable-next-line no-console
+                    console.log(`${TAG} Tunnel ready: ${url} (proxying ${ALLOWED_PATH_PREFIX}/* to port ${localPort})`);
+                    resolve(url);
+                }
+                else if (url !== this.publicUrl) {
+                    // URL changed — reconnection with new subdomain
+                    const oldUrl = this.publicUrl;
+                    this.publicUrl = url;
+                    // eslint-disable-next-line no-console
+                    console.log(`${TAG} Tunnel URL changed: ${oldUrl} -> ${url}`);
+                    this.notifyUrlChange(url);
+                }
+            });
+            tunnel.on('error', (err) => {
+                clearTimeout(timeout);
+                this.tunnel = null;
+                this.publicUrl = null;
+                this.stopProxyServer();
+                reject(new Error(`${TAG} Failed to start tunnel: ${err.message}`));
+            });
+            tunnel.on('exit', (code) => {
+                clearTimeout(timeout);
+                if (this.tunnel === tunnel) {
+                    this.tunnel = null;
+                    const wasRunning = this.publicUrl !== null;
+                    this.publicUrl = null;
+                    this.stopProxyServer();
+                    if (wasRunning) {
+                        // eslint-disable-next-line no-console
+                        console.log(`${TAG} Tunnel process exited (code ${code})`);
+                    }
+                    else {
+                        reject(new Error(`${TAG} cloudflared exited with code ${code} before producing a URL`));
+                    }
+                }
+            });
+        });
+    }
+    async stop() {
+        this.stopTunnel();
+        this.publicUrl = null;
+    }
+    getPublicUrl() {
+        return this.publicUrl;
+    }
+    onUrlChange(handler) {
+        this.urlChangeHandlers.push(handler);
+    }
+    isRunning() {
+        return this.tunnel !== null && this.publicUrl !== null;
+    }
+    /**
+     * Start a lightweight HTTP proxy on a random port that only forwards
+     * requests with paths starting with ALLOWED_PATH_PREFIX to the main app.
+     * Everything else gets a 404.
+     */
+    startProxyServer(targetPort) {
+        return new Promise((resolve, reject) => {
+            const server = createServer((req, res) => {
+                const url = req.url ?? '';
+                if (!url.startsWith(ALLOWED_PATH_PREFIX)) {
+                    res.writeHead(404, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: 'Not found' }));
+                    return;
+                }
+                // Proxy the request to the main app
+                const proxyReq = httpRequest({
+                    hostname: 'localhost',
+                    port: targetPort,
+                    path: url,
+                    method: req.method,
+                    headers: req.headers,
+                }, (proxyRes) => {
+                    res.writeHead(proxyRes.statusCode ?? 502, proxyRes.headers);
+                    proxyRes.pipe(res);
+                });
+                proxyReq.on('error', (err) => {
+                    // eslint-disable-next-line no-console
+                    console.warn(`${TAG} Proxy error: ${err.message}`);
+                    if (!res.headersSent) {
+                        res.writeHead(502, { 'Content-Type': 'application/json' });
+                    }
+                    res.end(JSON.stringify({ error: 'Bad gateway' }));
+                });
+                req.pipe(proxyReq);
+            });
+            // Listen on port 0 = OS assigns a random available port
+            server.listen(0, '127.0.0.1', () => {
+                const addr = server.address();
+                if (addr && typeof addr === 'object') {
+                    this.proxyServer = server;
+                    // eslint-disable-next-line no-console
+                    console.log(`${TAG} Webhook proxy listening on port ${addr.port}`);
+                    resolve(addr.port);
+                }
+                else {
+                    server.close();
+                    reject(new Error(`${TAG} Failed to start proxy server`));
+                }
+            });
+            server.on('error', (err) => {
+                reject(new Error(`${TAG} Proxy server error: ${err.message}`));
+            });
+        });
+    }
+    stopProxyServer() {
+        if (this.proxyServer) {
+            this.proxyServer.close();
+            this.proxyServer = null;
+        }
+    }
+    stopTunnel() {
+        if (this.tunnel) {
+            const tunnel = this.tunnel;
+            this.tunnel = null;
+            try {
+                tunnel.stop();
+            }
+            catch {
+                // Tunnel already stopped
+            }
+        }
+        this.stopProxyServer();
+    }
+    notifyUrlChange(newUrl) {
+        for (const handler of this.urlChangeHandlers) {
+            try {
+                const result = handler(newUrl);
+                if (result instanceof Promise) {
+                    result.catch((err) => {
+                        // eslint-disable-next-line no-console
+                        console.warn(`${TAG} URL change handler failed:`, err);
+                    });
+                }
+            }
+            catch (err) {
+                // eslint-disable-next-line no-console
+                console.warn(`${TAG} URL change handler threw:`, err);
+            }
+        }
+    }
+}

package/dist/packages/core/src/infrastructure/services/webhook/github-webhook.service.d.ts

@@ -0,0 +1,75 @@
+/**
+ * GitHub Webhook Service
+ *
+ * Manages GitHub webhook registration and incoming event processing.
+ * Uses the GitHub CLI (`gh api`) for webhook CRUD operations.
+ *
+ * Webhook events supplement the existing PR sync polling:
+ * - Webhooks provide near-instant event delivery
+ * - Polling remains as a fallback for missed events
+ *
+ * Registered events: pull_request, check_suite, check_run
+ */
+import type { IWebhookService, WebhookEvent, WebhookValidationResult } from '../../../application/ports/output/services/webhook-service.interface.js';
+import type { IFeatureRepository } from '../../../application/ports/output/repositories/feature-repository.interface.js';
+import type { IGitPrService } from '../../../application/ports/output/services/git-pr-service.interface.js';
+import type { INotificationService } from '../../../application/ports/output/services/notification-service.interface.js';
+export type ExecFunction = (file: string, args: string[], options?: object) => Promise<{
+    stdout: string;
+    stderr: string;
+}>;
+export interface RegisteredWebhook {
+    repoFullName: string;
+    webhookId: number;
+    repositoryPath: string;
+}
+export type WebhookDeliveryStatus = 'success' | 'ignored' | 'error';
+export interface WebhookDeliveryRecord {
+    deliveryId: string;
+    eventType: string;
+    source: string;
+    receivedAt: string;
+    status: WebhookDeliveryStatus;
+    statusMessage: string;
+    durationMs: number;
+    payload: Record<string, unknown>;
+}
+export declare class GitHubWebhookService implements IWebhookService {
+    private readonly featureRepo;
+    private readonly gitPrService;
+    private readonly notificationService;
+    private readonly execFn;
+    private readonly registeredWebhooks;
+    private readonly deliveryHistory;
+    private webhookSecret;
+    constructor(featureRepo: IFeatureRepository, gitPrService: IGitPrService, notificationService: INotificationService, execFn: ExecFunction);
+    /**
+     * Get the webhook secret for signature validation.
+     * Exposed so the API route can validate incoming requests.
+     */
+    getSecret(): string;
+    /**
+     * Get the list of registered webhooks (for dashboard display).
+     */
+    getRegisteredWebhooks(): readonly RegisteredWebhook[];
+    /**
+     * Get recent delivery history (newest first).
+     */
+    getDeliveryHistory(): readonly WebhookDeliveryRecord[];
+    registerWebhooks(publicUrl: string): Promise<void>;
+    updateWebhookUrl(newUrl: string): Promise<void>;
+    removeWebhooks(): Promise<void>;
+    validateSignature(payload: string, signature: string, secret: string): WebhookValidationResult;
+    handleEvent(event: WebhookEvent): Promise<void>;
+    private recordDelivery;
+    private handlePullRequestEvent;
+    private handleCheckSuiteEvent;
+    private handleCheckRunEvent;
+    private findFeatureByPrOrBranch;
+    private findFeatureByBranch;
+    private updateFeaturePrStatus;
+    private updateFeatureCiStatus;
+    private registerWebhookForRepo;
+    private getRepoFullName;
+}
+//# sourceMappingURL=github-webhook.service.d.ts.map