Feat/temporal (#46)

* refactor: modularize claude-executor and extract shared utilities - Extract message handling into src/ai/message-handlers.ts with pure functions - Extract output formatting into src/ai/output-formatters.ts - Extract progress management into src/ai/progress-manager.ts - Add audit-logger.ts with Null Object pattern for optional logging - Add shared utilities: formatting.ts, file-io.ts, functional.ts - Consolidate getPromptNameForAgent into src/types/agents.ts * feat: add Claude Code custom commands for debug and review * feat: add Temporal integration foundation (phase 1-2) - Add Temporal SDK dependencies (@temporalio/client, worker, workflow, activity) - Add shared types for pipeline state, metrics, and progress queries - Add classifyErrorForTemporal() for retry behavior classification - Add docker-compose for Temporal server with SQLite persistence * feat: add Temporal activities for agent execution (phase 3) - Add activities.ts with heartbeat loop, git checkpoint/rollback, and error classification - Export runClaudePrompt, validateAgentOutput, ClaudePromptResult for Temporal use - Track attempt number via Temporal Context for accurate audit logging - Rollback git workspace before retry to ensure clean state * feat: add Temporal workflow for 5-phase pipeline orchestration (phase 4) * feat: add Temporal worker, client, and query tools (phase 5) - Add worker.ts with workflow bundling and graceful shutdown - Add client.ts CLI to start pipelines with progress polling - Add query.ts CLI to inspect running workflow state - Fix buffer overflow by truncating error messages and stack traces - Skip git operations gracefully on non-git repositories - Add kill.sh/start.sh dev scripts and Dockerfile.worker * feat: fix Docker worker container setup - Install uv instead of deprecated uvx package - Add mcp-server and configs directories to container - Mount target repo dynamically via TARGET_REPO env variable * fix: add report assembly step to Temporal workflow - Add assembleReportActivity to concatenate exploitation evidence files before report agent runs - Call assembleFinalReport in workflow Phase 5 before runReportAgent - Ensure deliverables directory exists before writing final report - Simplify pipeline-testing report prompt to just prepend header * refactor: consolidate Docker setup to root docker-compose.yml * feat: improve Temporal client UX and env handling - Change default to fire-and-forget (--wait flag to opt-in) - Add splash screen and improve console output formatting - Add .env to gitignore, remove from dockerignore for container access - Add Taskfile for common development commands * refactor: simplify session ID handling and improve Taskfile options - Include hostname in workflow ID for better audit log organization - Extract sanitizeHostname utility to audit/utils.ts for reuse - Remove unused generateSessionLogPath and buildLogFilePath functions - Simplify Taskfile with CONFIG/OUTPUT/CLEAN named parameters * chore: add .env.example and simplify .gitignore * docs: update README and CLAUDE.md for Temporal workflow usage - Replace Docker CLI instructions with Task-based commands - Add monitoring/stopping sections and workflow examples - Document Temporal orchestration layer and troubleshooting - Simplify file structure to key files overview * refactor: replace Taskfile with bash CLI script - Add shannon bash script with start/logs/query/stop/help commands - Remove Taskfile.yml dependency (no longer requires Task installation) - Update README.md and CLAUDE.md to use ./shannon commands - Update client.ts output to show ./shannon commands * docs: fix deliverable filename in README * refactor: remove direct CLI and .shannon-store.json in favor of Temporal - Delete src/shannon.ts direct CLI entry point (Temporal is now the only mode) - Remove .shannon-store.json session lock (Temporal handles workflow deduplication) - Remove broken scripts/export-metrics.js (imported non-existent function) - Update package.json to remove main, start script, and bin entry - Clean up CLAUDE.md and debug.md to remove obsolete references * chore: remove licensing comments from prompt files to prevent leaking into actual prompts * fix: resolve parallel workflow race conditions and retry logic bugs - Fix save_deliverable race condition using closure pattern instead of global variable - Fix error classification order so OutputValidationError matches before generic validation - Fix ApplicationFailure re-classification bug by checking instanceof before re-throwing - Add per-error-type retry limits (3 for output validation, 50 for billing) - Add fast retry intervals for pipeline testing mode (10s vs 5min) - Increase worker concurrent activities to 25 for parallel workflows * refactor: pipeline vuln→exploit workflow for parallel execution - Replace sync barrier between vuln/exploit phases with independent pipelines - Each vuln type runs: vuln agent → queue check → conditional exploit - Add checkExploitationQueue activity to skip exploits when no vulns found - Use Promise.allSettled for graceful failure handling across pipelines - Add PipelineSummary type for aggregated cost/duration/turns metrics * fix: re-throw retryable errors in checkExploitationQueue * fix: detect and retry on Claude Code spending cap errors - Add spending cap pattern detection in detectApiError() with retryable error - Add matching patterns to classifyErrorForTemporal() for proper Temporal retry - Add defense-in-depth safeguard in runClaudePrompt() for $0 cost / low turn detection - Add final sanity check in activities before declaring success * fix: increase heartbeat timeout to prevent false worker-dead detection Original 30s timeout was from POC spec assuming <5min activities. With hour-long activities and multiple concurrent workflows sharing one worker, resource contention causes event loop stalls exceeding 30s, triggering false heartbeat timeouts. Increased to 10min (prod) and 5min (testing). * fix: temporal db init * fix: persist home dir * feat: add per-workflow unified logging with ./shannon logs ID=<workflow-id> - Add WorkflowLogger class for human-readable, per-workflow log files - Create workflow.log in audit-logs/{workflowId}/ with phase, agent, tool, and LLM events - Update ./shannon logs to require ID param and tail specific workflow log - Add phase transition logging at workflow boundaries - Include workflow completion summary with agent breakdown (duration, cost) - Mount audit-logs volume in docker-compose for host access --------- Co-authored-by: ezl-keygraph <ezhil@keygraph.io>
2026-01-15 10:36:11 -08:00
parent 45acb16711
commit 51e621d0d5
77 changed files with 6117 additions and 2417 deletions
@@ -0,0 +1,469 @@
+// Copyright (C) 2025 Keygraph, Inc.
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License version 3
+// as published by the Free Software Foundation.
+
+/**
+ * Temporal activities for Shannon agent execution.
+ *
+ * Each activity wraps a single agent execution with:
+ * - Heartbeat loop (2s interval) to signal worker liveness
+ * - Git checkpoint/rollback/commit per attempt
+ * - Error classification for Temporal retry behavior
+ * - Audit session logging
+ *
+ * Temporal handles retries based on error classification:
+ * - Retryable: BillingError, TransientError (429, 5xx, network)
+ * - Non-retryable: AuthenticationError, PermissionError, ConfigurationError, etc.
+ */
+
+import { heartbeat, ApplicationFailure, Context } from '@temporalio/activity';
+import chalk from 'chalk';
+
+// Max lengths to prevent Temporal protobuf buffer overflow
+const MAX_ERROR_MESSAGE_LENGTH = 2000;
+const MAX_STACK_TRACE_LENGTH = 1000;
+
+// Max retries for output validation errors (agent didn't save deliverables)
+// Lower than default 50 since this is unlikely to self-heal
+const MAX_OUTPUT_VALIDATION_RETRIES = 3;
+
+/**
+ * Truncate error message to prevent buffer overflow in Temporal serialization.
+ */
+function truncateErrorMessage(message: string): string {
+  if (message.length <= MAX_ERROR_MESSAGE_LENGTH) {
+    return message;
+  }
+  return message.slice(0, MAX_ERROR_MESSAGE_LENGTH - 20) + '\n[truncated]';
+}
+
+/**
+ * Truncate stack trace on an ApplicationFailure to prevent buffer overflow.
+ */
+function truncateStackTrace(failure: ApplicationFailure): void {
+  if (failure.stack && failure.stack.length > MAX_STACK_TRACE_LENGTH) {
+    failure.stack = failure.stack.slice(0, MAX_STACK_TRACE_LENGTH) + '\n[stack truncated]';
+  }
+}
+
+import {
+  runClaudePrompt,
+  validateAgentOutput,
+  type ClaudePromptResult,
+} from '../ai/claude-executor.js';
+import { loadPrompt } from '../prompts/prompt-manager.js';
+import { parseConfig, distributeConfig } from '../config-parser.js';
+import { classifyErrorForTemporal } from '../error-handling.js';
+import {
+  safeValidateQueueAndDeliverable,
+  type VulnType,
+  type ExploitationDecision,
+} from '../queue-validation.js';
+import {
+  createGitCheckpoint,
+  commitGitSuccess,
+  rollbackGitWorkspace,
+  getGitCommitHash,
+} from '../utils/git-manager.js';
+import { assembleFinalReport } from '../phases/reporting.js';
+import { getPromptNameForAgent } from '../types/agents.js';
+import { AuditSession } from '../audit/index.js';
+import type { WorkflowSummary } from '../audit/workflow-logger.js';
+import type { AgentName } from '../types/agents.js';
+import type { AgentMetrics } from './shared.js';
+import type { DistributedConfig } from '../types/config.js';
+import type { SessionMetadata } from '../audit/utils.js';
+
+const HEARTBEAT_INTERVAL_MS = 2000; // Must be < heartbeatTimeout (10min production, 5min testing)
+
+/**
+ * Input for all agent activities.
+ * Matches PipelineInput but with required workflowId for audit correlation.
+ */
+export interface ActivityInput {
+  webUrl: string;
+  repoPath: string;
+  configPath?: string;
+  outputPath?: string;
+  pipelineTestingMode?: boolean;
+  workflowId: string;
+}
+
+/**
+ * Core activity implementation.
+ *
+ * Executes a single agent with:
+ * 1. Heartbeat loop for worker liveness
+ * 2. Config loading (if configPath provided)
+ * 3. Audit session initialization
+ * 4. Prompt loading
+ * 5. Git checkpoint before execution
+ * 6. Agent execution (single attempt)
+ * 7. Output validation
+ * 8. Git commit on success, rollback on failure
+ * 9. Error classification for Temporal retry
+ */
+async function runAgentActivity(
+  agentName: AgentName,
+  input: ActivityInput
+): Promise<AgentMetrics> {
+  const {
+    webUrl,
+    repoPath,
+    configPath,
+    outputPath,
+    pipelineTestingMode = false,
+    workflowId,
+  } = input;
+
+  const startTime = Date.now();
+
+  // Get attempt number from Temporal context (tracks retries automatically)
+  const attemptNumber = Context.current().info.attempt;
+
+  // Heartbeat loop - signals worker is alive to Temporal server
+  const heartbeatInterval = setInterval(() => {
+    const elapsed = Math.floor((Date.now() - startTime) / 1000);
+    heartbeat({ agent: agentName, elapsedSeconds: elapsed, attempt: attemptNumber });
+  }, HEARTBEAT_INTERVAL_MS);
+
+  try {
+    // 1. Load config (if provided)
+    let distributedConfig: DistributedConfig | null = null;
+    if (configPath) {
+      try {
+        const config = await parseConfig(configPath);
+        distributedConfig = distributeConfig(config);
+      } catch (err) {
+        throw new Error(`Failed to load config ${configPath}: ${err instanceof Error ? err.message : String(err)}`);
+      }
+    }
+
+    // 2. Build session metadata for audit
+    const sessionMetadata: SessionMetadata = {
+      id: workflowId,
+      webUrl,
+      repoPath,
+      ...(outputPath && { outputPath }),
+    };
+
+    // 3. Initialize audit session (idempotent, safe across retries)
+    const auditSession = new AuditSession(sessionMetadata);
+    await auditSession.initialize();
+
+    // 4. Load prompt
+    const promptName = getPromptNameForAgent(agentName);
+    const prompt = await loadPrompt(
+      promptName,
+      { webUrl, repoPath },
+      distributedConfig,
+      pipelineTestingMode
+    );
+
+    // 5. Create git checkpoint before execution
+    await createGitCheckpoint(repoPath, agentName, attemptNumber);
+    await auditSession.startAgent(agentName, prompt, attemptNumber);
+
+    // 6. Execute agent (single attempt - Temporal handles retries)
+    const result: ClaudePromptResult = await runClaudePrompt(
+      prompt,
+      repoPath,
+      '', // context
+      agentName, // description
+      agentName,
+      chalk.cyan,
+      sessionMetadata,
+      auditSession,
+      attemptNumber
+    );
+
+    // 6.5. Sanity check: Detect spending cap that slipped through all detection layers
+    // Defense-in-depth: A successful agent execution should never have ≤2 turns with $0 cost
+    if (result.success && (result.turns ?? 0) <= 2 && (result.cost || 0) === 0) {
+      const resultText = result.result || '';
+      const looksLikeBillingError = /spending|cap|limit|budget|resets/i.test(resultText);
+
+      if (looksLikeBillingError) {
+        await rollbackGitWorkspace(repoPath, 'spending cap detected');
+        await auditSession.endAgent(agentName, {
+          attemptNumber,
+          duration_ms: result.duration,
+          cost_usd: 0,
+          success: false,
+          error: `Spending cap likely reached: ${resultText.slice(0, 100)}`,
+        });
+        // Throw as billing error so Temporal retries with long backoff
+        throw new Error(`Spending cap likely reached: ${resultText.slice(0, 100)}`);
+      }
+    }
+
+    // 7. Handle execution failure
+    if (!result.success) {
+      await rollbackGitWorkspace(repoPath, 'execution failure');
+      await auditSession.endAgent(agentName, {
+        attemptNumber,
+        duration_ms: result.duration,
+        cost_usd: result.cost || 0,
+        success: false,
+        error: result.error || 'Execution failed',
+      });
+      throw new Error(result.error || 'Agent execution failed');
+    }
+
+    // 8. Validate output
+    const validationPassed = await validateAgentOutput(result, agentName, repoPath);
+    if (!validationPassed) {
+      await rollbackGitWorkspace(repoPath, 'validation failure');
+      await auditSession.endAgent(agentName, {
+        attemptNumber,
+        duration_ms: result.duration,
+        cost_usd: result.cost || 0,
+        success: false,
+        error: 'Output validation failed',
+      });
+
+      // Limit output validation retries (unlikely to self-heal)
+      if (attemptNumber >= MAX_OUTPUT_VALIDATION_RETRIES) {
+        throw ApplicationFailure.nonRetryable(
+          `Agent ${agentName} failed output validation after ${attemptNumber} attempts`,
+          'OutputValidationError',
+          [{ agentName, attemptNumber, elapsed: Date.now() - startTime }]
+        );
+      }
+      // Let Temporal retry (will be classified as OutputValidationError)
+      throw new Error(`Agent ${agentName} failed output validation`);
+    }
+
+    // 9. Success - commit and log
+    const commitHash = await getGitCommitHash(repoPath);
+    await auditSession.endAgent(agentName, {
+      attemptNumber,
+      duration_ms: result.duration,
+      cost_usd: result.cost || 0,
+      success: true,
+      ...(commitHash && { checkpoint: commitHash }),
+    });
+    await commitGitSuccess(repoPath, agentName);
+
+    // 10. Return metrics
+    return {
+      durationMs: Date.now() - startTime,
+      inputTokens: null, // Not currently exposed by SDK wrapper
+      outputTokens: null,
+      costUsd: result.cost ?? null,
+      numTurns: result.turns ?? null,
+    };
+  } catch (error) {
+    // Rollback git workspace before Temporal retry to ensure clean state
+    try {
+      await rollbackGitWorkspace(repoPath, 'error recovery');
+    } catch (rollbackErr) {
+      // Log but don't fail - rollback is best-effort
+      console.error(`Failed to rollback git workspace for ${agentName}:`, rollbackErr);
+    }
+
+    // If error is already an ApplicationFailure (e.g., from our retry limit logic),
+    // re-throw it directly without re-classifying
+    if (error instanceof ApplicationFailure) {
+      throw error;
+    }
+
+    // Classify error for Temporal retry behavior
+    const classified = classifyErrorForTemporal(error);
+    // Truncate message to prevent protobuf buffer overflow
+    const rawMessage = error instanceof Error ? error.message : String(error);
+    const message = truncateErrorMessage(rawMessage);
+
+    if (classified.retryable) {
+      // Temporal will retry with configured backoff
+      const failure = ApplicationFailure.create({
+        message,
+        type: classified.type,
+        details: [{ agentName, attemptNumber, elapsed: Date.now() - startTime }],
+      });
+      truncateStackTrace(failure);
+      throw failure;
+    } else {
+      // Fail immediately - no retry
+      const failure = ApplicationFailure.nonRetryable(message, classified.type, [
+        { agentName, attemptNumber, elapsed: Date.now() - startTime },
+      ]);
+      truncateStackTrace(failure);
+      throw failure;
+    }
+  } finally {
+    clearInterval(heartbeatInterval);
+  }
+}
+
+// === Individual Agent Activity Exports ===
+// Each function is a thin wrapper around runAgentActivity with the agent name.
+
+export async function runPreReconAgent(input: ActivityInput): Promise<AgentMetrics> {
+  return runAgentActivity('pre-recon', input);
+}
+
+export async function runReconAgent(input: ActivityInput): Promise<AgentMetrics> {
+  return runAgentActivity('recon', input);
+}
+
+export async function runInjectionVulnAgent(input: ActivityInput): Promise<AgentMetrics> {
+  return runAgentActivity('injection-vuln', input);
+}
+
+export async function runXssVulnAgent(input: ActivityInput): Promise<AgentMetrics> {
+  return runAgentActivity('xss-vuln', input);
+}
+
+export async function runAuthVulnAgent(input: ActivityInput): Promise<AgentMetrics> {
+  return runAgentActivity('auth-vuln', input);
+}
+
+export async function runSsrfVulnAgent(input: ActivityInput): Promise<AgentMetrics> {
+  return runAgentActivity('ssrf-vuln', input);
+}
+
+export async function runAuthzVulnAgent(input: ActivityInput): Promise<AgentMetrics> {
+  return runAgentActivity('authz-vuln', input);
+}
+
+export async function runInjectionExploitAgent(input: ActivityInput): Promise<AgentMetrics> {
+  return runAgentActivity('injection-exploit', input);
+}
+
+export async function runXssExploitAgent(input: ActivityInput): Promise<AgentMetrics> {
+  return runAgentActivity('xss-exploit', input);
+}
+
+export async function runAuthExploitAgent(input: ActivityInput): Promise<AgentMetrics> {
+  return runAgentActivity('auth-exploit', input);
+}
+
+export async function runSsrfExploitAgent(input: ActivityInput): Promise<AgentMetrics> {
+  return runAgentActivity('ssrf-exploit', input);
+}
+
+export async function runAuthzExploitAgent(input: ActivityInput): Promise<AgentMetrics> {
+  return runAgentActivity('authz-exploit', input);
+}
+
+export async function runReportAgent(input: ActivityInput): Promise<AgentMetrics> {
+  return runAgentActivity('report', input);
+}
+
+/**
+ * Assemble the final report by concatenating exploitation evidence files.
+ * This must be called BEFORE runReportAgent to create the file that the report agent will modify.
+ */
+export async function assembleReportActivity(input: ActivityInput): Promise<void> {
+  const { repoPath } = input;
+  console.log(chalk.blue('📝 Assembling deliverables from specialist agents...'));
+  try {
+    await assembleFinalReport(repoPath);
+  } catch (error) {
+    const err = error as Error;
+    console.log(chalk.yellow(`⚠️ Error assembling final report: ${err.message}`));
+    // Don't throw - the report agent can still create content even if no exploitation files exist
+  }
+}
+
+/**
+ * Check if exploitation should run for a given vulnerability type.
+ * Reads the vulnerability queue file and returns the decision.
+ *
+ * This activity allows the workflow to skip exploit agents entirely
+ * when no vulnerabilities were found, saving API calls and time.
+ *
+ * Error handling:
+ * - Retryable errors (missing files, invalid JSON): re-throw for Temporal retry
+ * - Non-retryable errors: skip exploitation gracefully
+ */
+export async function checkExploitationQueue(
+  input: ActivityInput,
+  vulnType: VulnType
+): Promise<ExploitationDecision> {
+  const { repoPath } = input;
+
+  const result = await safeValidateQueueAndDeliverable(vulnType, repoPath);
+
+  if (result.success && result.data) {
+    const { shouldExploit, vulnerabilityCount } = result.data;
+    console.log(
+      chalk.blue(
+        `🔍 ${vulnType}: ${shouldExploit ? `${vulnerabilityCount} vulnerabilities found` : 'no vulnerabilities, skipping exploitation'}`
+      )
+    );
+    return result.data;
+  }
+
+  // Validation failed - check if we should retry or skip
+  const error = result.error;
+  if (error?.retryable) {
+    // Re-throw retryable errors so Temporal can retry the vuln agent
+    console.log(chalk.yellow(`⚠️ ${vulnType}: ${error.message} (retrying)`));
+    throw error;
+  }
+
+  // Non-retryable error - skip exploitation gracefully
+  console.log(
+    chalk.yellow(`⚠️ ${vulnType}: ${error?.message ?? 'Unknown error'}, skipping exploitation`)
+  );
+  return {
+    shouldExploit: false,
+    shouldRetry: false,
+    vulnerabilityCount: 0,
+    vulnType,
+  };
+}
+
+/**
+ * Log phase transition to the unified workflow log.
+ * Called at phase boundaries for per-workflow logging.
+ */
+export async function logPhaseTransition(
+  input: ActivityInput,
+  phase: string,
+  event: 'start' | 'complete'
+): Promise<void> {
+  const { webUrl, repoPath, outputPath, workflowId } = input;
+
+  const sessionMetadata: SessionMetadata = {
+    id: workflowId,
+    webUrl,
+    repoPath,
+    ...(outputPath && { outputPath }),
+  };
+
+  const auditSession = new AuditSession(sessionMetadata);
+  await auditSession.initialize();
+
+  if (event === 'start') {
+    await auditSession.logPhaseStart(phase);
+  } else {
+    await auditSession.logPhaseComplete(phase);
+  }
+}
+
+/**
+ * Log workflow completion with full summary to the unified workflow log.
+ * Called at the end of the workflow to write a summary breakdown.
+ */
+export async function logWorkflowComplete(
+  input: ActivityInput,
+  summary: WorkflowSummary
+): Promise<void> {
+  const { webUrl, repoPath, outputPath, workflowId } = input;
+
+  const sessionMetadata: SessionMetadata = {
+    id: workflowId,
+    webUrl,
+    repoPath,
+    ...(outputPath && { outputPath }),
+  };
+
+  const auditSession = new AuditSession(sessionMetadata);
+  await auditSession.initialize();
+  await auditSession.logWorkflowComplete(summary);
+}
@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+// Copyright (C) 2025 Keygraph, Inc.
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License version 3
+// as published by the Free Software Foundation.
+
+/**
+ * Temporal client for starting Shannon pentest pipeline workflows.
+ *
+ * Starts a workflow and optionally waits for completion with progress polling.
+ *
+ * Usage:
+ *   npm run temporal:start -- <webUrl> <repoPath> [options]
+ *   # or
+ *   node dist/temporal/client.js <webUrl> <repoPath> [options]
+ *
+ * Options:
+ *   --config <path>       Configuration file path
+ *   --output <path>       Output directory for audit logs
+ *   --pipeline-testing    Use minimal prompts for fast testing
+ *   --workflow-id <id>    Custom workflow ID (default: shannon-<timestamp>)
+ *   --wait                Wait for workflow completion with progress polling
+ *
+ * Environment:
+ *   TEMPORAL_ADDRESS - Temporal server address (default: localhost:7233)
+ */
+
+import { Connection, Client } from '@temporalio/client';
+import dotenv from 'dotenv';
+import chalk from 'chalk';
+import { displaySplashScreen } from '../splash-screen.js';
+import { sanitizeHostname } from '../audit/utils.js';
+// Import types only - these don't pull in workflow runtime code
+import type { PipelineInput, PipelineState, PipelineProgress } from './shared.js';
+
+dotenv.config();
+
+// Query name must match the one defined in workflows.ts
+const PROGRESS_QUERY = 'getProgress';
+
+function showUsage(): void {
+  console.log(chalk.cyan.bold('\nShannon Temporal Client'));
+  console.log(chalk.gray('Start a pentest pipeline workflow\n'));
+  console.log(chalk.yellow('Usage:'));
+  console.log(
+    '  node dist/temporal/client.js <webUrl> <repoPath> [options]\n'
+  );
+  console.log(chalk.yellow('Options:'));
+  console.log('  --config <path>       Configuration file path');
+  console.log('  --output <path>       Output directory for audit logs');
+  console.log('  --pipeline-testing    Use minimal prompts for fast testing');
+  console.log(
+    '  --workflow-id <id>    Custom workflow ID (default: shannon-<timestamp>)'
+  );
+  console.log('  --wait                Wait for workflow completion with progress polling\n');
+  console.log(chalk.yellow('Examples:'));
+  console.log('  node dist/temporal/client.js https://example.com /path/to/repo');
+  console.log(
+    '  node dist/temporal/client.js https://example.com /path/to/repo --config config.yaml\n'
+  );
+}
+
+async function startPipeline(): Promise<void> {
+  const args = process.argv.slice(2);
+
+  if (args.includes('--help') || args.includes('-h') || args.length === 0) {
+    showUsage();
+    process.exit(0);
+  }
+
+  // Parse arguments
+  let webUrl: string | undefined;
+  let repoPath: string | undefined;
+  let configPath: string | undefined;
+  let outputPath: string | undefined;
+  let pipelineTestingMode = false;
+  let customWorkflowId: string | undefined;
+  let waitForCompletion = false;
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--config') {
+      const nextArg = args[i + 1];
+      if (nextArg && !nextArg.startsWith('-')) {
+        configPath = nextArg;
+        i++;
+      }
+    } else if (arg === '--output') {
+      const nextArg = args[i + 1];
+      if (nextArg && !nextArg.startsWith('-')) {
+        outputPath = nextArg;
+        i++;
+      }
+    } else if (arg === '--workflow-id') {
+      const nextArg = args[i + 1];
+      if (nextArg && !nextArg.startsWith('-')) {
+        customWorkflowId = nextArg;
+        i++;
+      }
+    } else if (arg === '--pipeline-testing') {
+      pipelineTestingMode = true;
+    } else if (arg === '--wait') {
+      waitForCompletion = true;
+    } else if (arg && !arg.startsWith('-')) {
+      if (!webUrl) {
+        webUrl = arg;
+      } else if (!repoPath) {
+        repoPath = arg;
+      }
+    }
+  }
+
+  if (!webUrl || !repoPath) {
+    console.log(chalk.red('Error: webUrl and repoPath are required'));
+    showUsage();
+    process.exit(1);
+  }
+
+  // Display splash screen
+  await displaySplashScreen();
+
+  const address = process.env.TEMPORAL_ADDRESS || 'localhost:7233';
+  console.log(chalk.gray(`Connecting to Temporal at ${address}...`));
+
+  const connection = await Connection.connect({ address });
+  const client = new Client({ connection });
+
+  try {
+    const hostname = sanitizeHostname(webUrl);
+    const workflowId = customWorkflowId || `${hostname}_shannon-${Date.now()}`;
+
+    const input: PipelineInput = {
+      webUrl,
+      repoPath,
+      ...(configPath && { configPath }),
+      ...(outputPath && { outputPath }),
+      ...(pipelineTestingMode && { pipelineTestingMode }),
+    };
+
+    console.log(chalk.green.bold(`✓ Workflow started: ${workflowId}`));
+    console.log();
+    console.log(chalk.white('  Target:     ') + chalk.cyan(webUrl));
+    console.log(chalk.white('  Repository: ') + chalk.cyan(repoPath));
+    if (configPath) {
+      console.log(chalk.white('  Config:     ') + chalk.cyan(configPath));
+    }
+    if (pipelineTestingMode) {
+      console.log(chalk.white('  Mode:       ') + chalk.yellow('Pipeline Testing'));
+    }
+    console.log();
+
+    // Start workflow by name (not by importing the function)
+    const handle = await client.workflow.start<(input: PipelineInput) => Promise<PipelineState>>(
+      'pentestPipelineWorkflow',
+      {
+        taskQueue: 'shannon-pipeline',
+        workflowId,
+        args: [input],
+      }
+    );
+
+    if (!waitForCompletion) {
+      console.log(chalk.bold('Monitor progress:'));
+      console.log(chalk.white('  Web UI:  ') + chalk.blue(`http://localhost:8233/namespaces/default/workflows/${workflowId}`));
+      console.log(chalk.white('  Logs:    ') + chalk.gray(`./shannon logs ID=${workflowId}`));
+      console.log(chalk.white('  Query:   ') + chalk.gray(`./shannon query ID=${workflowId}`));
+      console.log();
+      return;
+    }
+
+    // Poll for progress every 30 seconds
+    const progressInterval = setInterval(async () => {
+      try {
+        const progress = await handle.query<PipelineProgress>(PROGRESS_QUERY);
+        const elapsed = Math.floor(progress.elapsedMs / 1000);
+        console.log(
+          chalk.gray(`[${elapsed}s]`),
+          chalk.cyan(`Phase: ${progress.currentPhase || 'unknown'}`),
+          chalk.gray(`| Agent: ${progress.currentAgent || 'none'}`),
+          chalk.gray(`| Completed: ${progress.completedAgents.length}/13`)
+        );
+      } catch {
+        // Workflow may have completed
+      }
+    }, 30000);
+
+    try {
+      const result = await handle.result();
+      clearInterval(progressInterval);
+
+      console.log(chalk.green.bold('\nPipeline completed successfully!'));
+      if (result.summary) {
+        console.log(chalk.gray(`Duration: ${Math.floor(result.summary.totalDurationMs / 1000)}s`));
+        console.log(chalk.gray(`Agents completed: ${result.summary.agentCount}`));
+        console.log(chalk.gray(`Total turns: ${result.summary.totalTurns}`));
+        console.log(chalk.gray(`Total cost: $${result.summary.totalCostUsd.toFixed(4)}`));
+      }
+    } catch (error) {
+      clearInterval(progressInterval);
+      console.error(chalk.red.bold('\nPipeline failed:'), error);
+      process.exit(1);
+    }
+  } finally {
+    await connection.close();
+  }
+}
+
+startPipeline().catch((err) => {
+  console.error(chalk.red('Client error:'), err);
+  process.exit(1);
+});
@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+// Copyright (C) 2025 Keygraph, Inc.
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License version 3
+// as published by the Free Software Foundation.
+
+/**
+ * Temporal query tool for inspecting Shannon workflow progress.
+ *
+ * Queries a running or completed workflow and displays its state.
+ *
+ * Usage:
+ *   npm run temporal:query -- <workflowId>
+ *   # or
+ *   node dist/temporal/query.js <workflowId>
+ *
+ * Environment:
+ *   TEMPORAL_ADDRESS - Temporal server address (default: localhost:7233)
+ */
+
+import { Connection, Client } from '@temporalio/client';
+import dotenv from 'dotenv';
+import chalk from 'chalk';
+
+dotenv.config();
+
+// Query name must match the one defined in workflows.ts
+const PROGRESS_QUERY = 'getProgress';
+
+// Types duplicated from shared.ts to avoid importing workflow APIs
+interface AgentMetrics {
+  durationMs: number;
+  inputTokens: number | null;
+  outputTokens: number | null;
+  costUsd: number | null;
+  numTurns: number | null;
+}
+
+interface PipelineProgress {
+  status: 'running' | 'completed' | 'failed';
+  currentPhase: string | null;
+  currentAgent: string | null;
+  completedAgents: string[];
+  failedAgent: string | null;
+  error: string | null;
+  startTime: number;
+  agentMetrics: Record<string, AgentMetrics>;
+  workflowId: string;
+  elapsedMs: number;
+}
+
+function showUsage(): void {
+  console.log(chalk.cyan.bold('\nShannon Temporal Query Tool'));
+  console.log(chalk.gray('Query progress of a running workflow\n'));
+  console.log(chalk.yellow('Usage:'));
+  console.log('  node dist/temporal/query.js <workflowId>\n');
+  console.log(chalk.yellow('Examples:'));
+  console.log('  node dist/temporal/query.js shannon-1704672000000\n');
+}
+
+function getStatusColor(status: string): string {
+  switch (status) {
+    case 'running':
+      return chalk.yellow(status);
+    case 'completed':
+      return chalk.green(status);
+    case 'failed':
+      return chalk.red(status);
+    default:
+      return status;
+  }
+}
+
+function formatDuration(ms: number): string {
+  const seconds = Math.floor(ms / 1000);
+  const minutes = Math.floor(seconds / 60);
+  const hours = Math.floor(minutes / 60);
+
+  if (hours > 0) {
+    return `${hours}h ${minutes % 60}m`;
+  } else if (minutes > 0) {
+    return `${minutes}m ${seconds % 60}s`;
+  }
+  return `${seconds}s`;
+}
+
+async function queryWorkflow(): Promise<void> {
+  const workflowId = process.argv[2];
+
+  if (!workflowId || workflowId === '--help' || workflowId === '-h') {
+    showUsage();
+    process.exit(workflowId ? 0 : 1);
+  }
+
+  const address = process.env.TEMPORAL_ADDRESS || 'localhost:7233';
+
+  const connection = await Connection.connect({ address });
+  const client = new Client({ connection });
+
+  try {
+    const handle = client.workflow.getHandle(workflowId);
+    const progress = await handle.query<PipelineProgress>(PROGRESS_QUERY);
+
+    console.log(chalk.cyan.bold('\nWorkflow Progress'));
+    console.log(chalk.gray('\u2500'.repeat(40)));
+    console.log(`${chalk.white('Workflow ID:')} ${progress.workflowId}`);
+    console.log(`${chalk.white('Status:')} ${getStatusColor(progress.status)}`);
+    console.log(
+      `${chalk.white('Current Phase:')} ${progress.currentPhase || 'none'}`
+    );
+    console.log(
+      `${chalk.white('Current Agent:')} ${progress.currentAgent || 'none'}`
+    );
+    console.log(`${chalk.white('Elapsed:')} ${formatDuration(progress.elapsedMs)}`);
+    console.log(
+      `${chalk.white('Completed:')} ${progress.completedAgents.length}/13 agents`
+    );
+
+    if (progress.completedAgents.length > 0) {
+      console.log(chalk.gray('\nCompleted agents:'));
+      for (const agent of progress.completedAgents) {
+        const metrics = progress.agentMetrics[agent];
+        const duration = metrics ? formatDuration(metrics.durationMs) : 'unknown';
+        const cost = metrics?.costUsd ? `$${metrics.costUsd.toFixed(4)}` : '';
+        console.log(
+          chalk.green(`  - ${agent}`) +
+            chalk.gray(` (${duration}${cost ? ', ' + cost : ''})`)
+        );
+      }
+    }
+
+    if (progress.error) {
+      console.log(chalk.red(`\nError: ${progress.error}`));
+      console.log(chalk.red(`Failed agent: ${progress.failedAgent}`));
+    }
+
+    console.log();
+  } catch (error) {
+    const err = error as Error;
+    if (err.message?.includes('not found')) {
+      console.log(chalk.red(`Workflow not found: ${workflowId}`));
+    } else {
+      console.error(chalk.red('Query failed:'), err.message);
+    }
+    process.exit(1);
+  } finally {
+    await connection.close();
+  }
+}
+
+queryWorkflow().catch((err) => {
+  console.error(chalk.red('Query error:'), err);
+  process.exit(1);
+});
@@ -0,0 +1,61 @@
+import { defineQuery } from '@temporalio/workflow';
+
+// === Types ===
+
+export interface PipelineInput {
+  webUrl: string;
+  repoPath: string;
+  configPath?: string;
+  outputPath?: string;
+  pipelineTestingMode?: boolean;
+  workflowId?: string; // Added by client, used for audit correlation
+}
+
+export interface AgentMetrics {
+  durationMs: number;
+  inputTokens: number | null;
+  outputTokens: number | null;
+  costUsd: number | null;
+  numTurns: number | null;
+}
+
+export interface PipelineSummary {
+  totalCostUsd: number;
+  totalDurationMs: number; // Wall-clock time (end - start)
+  totalTurns: number;
+  agentCount: number;
+}
+
+export interface PipelineState {
+  status: 'running' | 'completed' | 'failed';
+  currentPhase: string | null;
+  currentAgent: string | null;
+  completedAgents: string[];
+  failedAgent: string | null;
+  error: string | null;
+  startTime: number;
+  agentMetrics: Record<string, AgentMetrics>;
+  summary: PipelineSummary | null;
+}
+
+// Extended state returned by getProgress query (includes computed fields)
+export interface PipelineProgress extends PipelineState {
+  workflowId: string;
+  elapsedMs: number;
+}
+
+// Result from a single vuln→exploit pipeline
+export interface VulnExploitPipelineResult {
+  vulnType: string;
+  vulnMetrics: AgentMetrics | null;
+  exploitMetrics: AgentMetrics | null;
+  exploitDecision: {
+    shouldExploit: boolean;
+    vulnerabilityCount: number;
+  } | null;
+  error: string | null;
+}
+
+// === Queries ===
+
+export const getProgress = defineQuery<PipelineProgress>('getProgress');
@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+// Copyright (C) 2025 Keygraph, Inc.
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License version 3
+// as published by the Free Software Foundation.
+
+/**
+ * Temporal worker for Shannon pentest pipeline.
+ *
+ * Polls the 'shannon-pipeline' task queue and executes activities.
+ * Handles up to 25 concurrent activities to support multiple parallel workflows.
+ *
+ * Usage:
+ *   npm run temporal:worker
+ *   # or
+ *   node dist/temporal/worker.js
+ *
+ * Environment:
+ *   TEMPORAL_ADDRESS - Temporal server address (default: localhost:7233)
+ */
+
+import { NativeConnection, Worker, bundleWorkflowCode } from '@temporalio/worker';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import dotenv from 'dotenv';
+import chalk from 'chalk';
+import * as activities from './activities.js';
+
+dotenv.config();
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+async function runWorker(): Promise<void> {
+  const address = process.env.TEMPORAL_ADDRESS || 'localhost:7233';
+  console.log(chalk.cyan(`Connecting to Temporal at ${address}...`));
+
+  const connection = await NativeConnection.connect({ address });
+
+  // Bundle workflows for Temporal's V8 isolate
+  console.log(chalk.gray('Bundling workflows...'));
+  const workflowBundle = await bundleWorkflowCode({
+    workflowsPath: path.join(__dirname, 'workflows.js'),
+  });
+
+  const worker = await Worker.create({
+    connection,
+    namespace: 'default',
+    workflowBundle,
+    activities,
+    taskQueue: 'shannon-pipeline',
+    maxConcurrentActivityTaskExecutions: 25, // Support multiple parallel workflows (5 agents × ~5 workflows)
+  });
+
+  // Graceful shutdown handling
+  const shutdown = async (): Promise<void> => {
+    console.log(chalk.yellow('\nShutting down worker...'));
+    worker.shutdown();
+  };
+
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+
+  console.log(chalk.green('Shannon worker started'));
+  console.log(chalk.gray('Task queue: shannon-pipeline'));
+  console.log(chalk.gray('Press Ctrl+C to stop\n'));
+
+  try {
+    await worker.run();
+  } finally {
+    await connection.close();
+    console.log(chalk.gray('Worker stopped'));
+  }
+}
+
+runWorker().catch((err) => {
+  console.error(chalk.red('Worker failed:'), err);
+  process.exit(1);
+});
@@ -0,0 +1,325 @@
+// Copyright (C) 2025 Keygraph, Inc.
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License version 3
+// as published by the Free Software Foundation.
+
+/**
+ * Temporal workflow for Shannon pentest pipeline.
+ *
+ * Orchestrates the penetration testing workflow:
+ * 1. Pre-Reconnaissance (sequential)
+ * 2. Reconnaissance (sequential)
+ * 3-4. Vulnerability + Exploitation (5 pipelined pairs in parallel)
+ *      Each pair: vuln agent → queue check → conditional exploit
+ *      No synchronization barrier - exploits start when their vuln finishes
+ * 5. Reporting (sequential)
+ *
+ * Features:
+ * - Queryable state via getProgress
+ * - Automatic retry with backoff for transient/billing errors
+ * - Non-retryable classification for permanent errors
+ * - Audit correlation via workflowId
+ * - Graceful failure handling: pipelines continue if one fails
+ */
+
+import {
+  proxyActivities,
+  setHandler,
+  workflowInfo,
+} from '@temporalio/workflow';
+import type * as activities from './activities.js';
+import type { ActivityInput } from './activities.js';
+import {
+  getProgress,
+  type PipelineInput,
+  type PipelineState,
+  type PipelineProgress,
+  type PipelineSummary,
+  type VulnExploitPipelineResult,
+  type AgentMetrics,
+} from './shared.js';
+import type { VulnType } from '../queue-validation.js';
+
+// Retry configuration for production (long intervals for billing recovery)
+const PRODUCTION_RETRY = {
+  initialInterval: '5 minutes',
+  maximumInterval: '30 minutes',
+  backoffCoefficient: 2,
+  maximumAttempts: 50,
+  nonRetryableErrorTypes: [
+    'AuthenticationError',
+    'PermissionError',
+    'InvalidRequestError',
+    'RequestTooLargeError',
+    'ConfigurationError',
+    'InvalidTargetError',
+    'ExecutionLimitError',
+  ],
+};
+
+// Retry configuration for pipeline testing (fast iteration)
+const TESTING_RETRY = {
+  initialInterval: '10 seconds',
+  maximumInterval: '30 seconds',
+  backoffCoefficient: 2,
+  maximumAttempts: 5,
+  nonRetryableErrorTypes: PRODUCTION_RETRY.nonRetryableErrorTypes,
+};
+
+// Activity proxy with production retry configuration (default)
+const acts = proxyActivities<typeof activities>({
+  startToCloseTimeout: '2 hours',
+  heartbeatTimeout: '10 minutes', // Long timeout for resource-constrained workers with many concurrent activities
+  retry: PRODUCTION_RETRY,
+});
+
+// Activity proxy with testing retry configuration (fast)
+const testActs = proxyActivities<typeof activities>({
+  startToCloseTimeout: '10 minutes',
+  heartbeatTimeout: '5 minutes', // Shorter for testing but still tolerant of resource contention
+  retry: TESTING_RETRY,
+});
+
+/**
+ * Compute aggregated metrics from the current pipeline state.
+ * Called on both success and failure to provide partial metrics.
+ */
+function computeSummary(state: PipelineState): PipelineSummary {
+  const metrics = Object.values(state.agentMetrics);
+  return {
+    totalCostUsd: metrics.reduce((sum, m) => sum + (m.costUsd ?? 0), 0),
+    totalDurationMs: Date.now() - state.startTime,
+    totalTurns: metrics.reduce((sum, m) => sum + (m.numTurns ?? 0), 0),
+    agentCount: state.completedAgents.length,
+  };
+}
+
+export async function pentestPipelineWorkflow(
+  input: PipelineInput
+): Promise<PipelineState> {
+  const { workflowId } = workflowInfo();
+
+  // Select activity proxy based on testing mode
+  // Pipeline testing uses fast retry intervals (10s) for quick iteration
+  const a = input.pipelineTestingMode ? testActs : acts;
+
+  // Workflow state (queryable)
+  const state: PipelineState = {
+    status: 'running',
+    currentPhase: null,
+    currentAgent: null,
+    completedAgents: [],
+    failedAgent: null,
+    error: null,
+    startTime: Date.now(),
+    agentMetrics: {},
+    summary: null,
+  };
+
+  // Register query handler for real-time progress inspection
+  setHandler(getProgress, (): PipelineProgress => ({
+    ...state,
+    workflowId,
+    elapsedMs: Date.now() - state.startTime,
+  }));
+
+  // Build ActivityInput with required workflowId for audit correlation
+  // Activities require workflowId (non-optional), PipelineInput has it optional
+  // Use spread to conditionally include optional properties (exactOptionalPropertyTypes)
+  const activityInput: ActivityInput = {
+    webUrl: input.webUrl,
+    repoPath: input.repoPath,
+    workflowId,
+    ...(input.configPath !== undefined && { configPath: input.configPath }),
+    ...(input.outputPath !== undefined && { outputPath: input.outputPath }),
+    ...(input.pipelineTestingMode !== undefined && {
+      pipelineTestingMode: input.pipelineTestingMode,
+    }),
+  };
+
+  try {
+    // === Phase 1: Pre-Reconnaissance ===
+    state.currentPhase = 'pre-recon';
+    state.currentAgent = 'pre-recon';
+    await a.logPhaseTransition(activityInput, 'pre-recon', 'start');
+    state.agentMetrics['pre-recon'] =
+      await a.runPreReconAgent(activityInput);
+    state.completedAgents.push('pre-recon');
+    await a.logPhaseTransition(activityInput, 'pre-recon', 'complete');
+
+    // === Phase 2: Reconnaissance ===
+    state.currentPhase = 'recon';
+    state.currentAgent = 'recon';
+    await a.logPhaseTransition(activityInput, 'recon', 'start');
+    state.agentMetrics['recon'] = await a.runReconAgent(activityInput);
+    state.completedAgents.push('recon');
+    await a.logPhaseTransition(activityInput, 'recon', 'complete');
+
+    // === Phases 3-4: Vulnerability Analysis + Exploitation (Pipelined) ===
+    // Each vuln type runs as an independent pipeline:
+    // vuln agent → queue check → conditional exploit agent
+    // This eliminates the synchronization barrier between phases - each exploit
+    // starts immediately when its vuln agent finishes, not waiting for all.
+    state.currentPhase = 'vulnerability-exploitation';
+    state.currentAgent = 'pipelines';
+    await a.logPhaseTransition(activityInput, 'vulnerability-exploitation', 'start');
+
+    // Helper: Run a single vuln→exploit pipeline
+    async function runVulnExploitPipeline(
+      vulnType: VulnType,
+      runVulnAgent: () => Promise<AgentMetrics>,
+      runExploitAgent: () => Promise<AgentMetrics>
+    ): Promise<VulnExploitPipelineResult> {
+      // Step 1: Run vulnerability agent
+      const vulnMetrics = await runVulnAgent();
+
+      // Step 2: Check exploitation queue (starts immediately after vuln)
+      const decision = await a.checkExploitationQueue(activityInput, vulnType);
+
+      // Step 3: Conditionally run exploit agent
+      let exploitMetrics: AgentMetrics | null = null;
+      if (decision.shouldExploit) {
+        exploitMetrics = await runExploitAgent();
+      }
+
+      return {
+        vulnType,
+        vulnMetrics,
+        exploitMetrics,
+        exploitDecision: {
+          shouldExploit: decision.shouldExploit,
+          vulnerabilityCount: decision.vulnerabilityCount,
+        },
+        error: null,
+      };
+    }
+
+    // Run all 5 pipelines in parallel with graceful failure handling
+    // Promise.allSettled ensures other pipelines continue if one fails
+    const pipelineResults = await Promise.allSettled([
+      runVulnExploitPipeline(
+        'injection',
+        () => a.runInjectionVulnAgent(activityInput),
+        () => a.runInjectionExploitAgent(activityInput)
+      ),
+      runVulnExploitPipeline(
+        'xss',
+        () => a.runXssVulnAgent(activityInput),
+        () => a.runXssExploitAgent(activityInput)
+      ),
+      runVulnExploitPipeline(
+        'auth',
+        () => a.runAuthVulnAgent(activityInput),
+        () => a.runAuthExploitAgent(activityInput)
+      ),
+      runVulnExploitPipeline(
+        'ssrf',
+        () => a.runSsrfVulnAgent(activityInput),
+        () => a.runSsrfExploitAgent(activityInput)
+      ),
+      runVulnExploitPipeline(
+        'authz',
+        () => a.runAuthzVulnAgent(activityInput),
+        () => a.runAuthzExploitAgent(activityInput)
+      ),
+    ]);
+
+    // Aggregate results from all pipelines
+    const failedPipelines: string[] = [];
+    for (const result of pipelineResults) {
+      if (result.status === 'fulfilled') {
+        const { vulnType, vulnMetrics, exploitMetrics } = result.value;
+
+        // Record vuln agent metrics
+        if (vulnMetrics) {
+          state.agentMetrics[`${vulnType}-vuln`] = vulnMetrics;
+          state.completedAgents.push(`${vulnType}-vuln`);
+        }
+
+        // Record exploit agent metrics (if it ran)
+        if (exploitMetrics) {
+          state.agentMetrics[`${vulnType}-exploit`] = exploitMetrics;
+          state.completedAgents.push(`${vulnType}-exploit`);
+        }
+      } else {
+        // Pipeline failed - log error but continue with others
+        const errorMsg =
+          result.reason instanceof Error
+            ? result.reason.message
+            : String(result.reason);
+        failedPipelines.push(errorMsg);
+      }
+    }
+
+    // Log any pipeline failures (workflow continues despite failures)
+    if (failedPipelines.length > 0) {
+      console.log(
+        `⚠️ ${failedPipelines.length} pipeline(s) failed:`,
+        failedPipelines
+      );
+    }
+
+    // Update phase markers
+    state.currentPhase = 'exploitation';
+    state.currentAgent = null;
+    await a.logPhaseTransition(activityInput, 'vulnerability-exploitation', 'complete');
+
+    // === Phase 5: Reporting ===
+    state.currentPhase = 'reporting';
+    state.currentAgent = 'report';
+    await a.logPhaseTransition(activityInput, 'reporting', 'start');
+
+    // First, assemble the concatenated report from exploitation evidence files
+    await a.assembleReportActivity(activityInput);
+
+    // Then run the report agent to add executive summary and clean up
+    state.agentMetrics['report'] = await a.runReportAgent(activityInput);
+    state.completedAgents.push('report');
+    await a.logPhaseTransition(activityInput, 'reporting', 'complete');
+
+    // === Complete ===
+    state.status = 'completed';
+    state.currentPhase = null;
+    state.currentAgent = null;
+    state.summary = computeSummary(state);
+
+    // Log workflow completion summary
+    await a.logWorkflowComplete(activityInput, {
+      status: 'completed',
+      totalDurationMs: state.summary.totalDurationMs,
+      totalCostUsd: state.summary.totalCostUsd,
+      completedAgents: state.completedAgents,
+      agentMetrics: Object.fromEntries(
+        Object.entries(state.agentMetrics).map(([name, m]) => [
+          name,
+          { durationMs: m.durationMs, costUsd: m.costUsd },
+        ])
+      ),
+    });
+
+    return state;
+  } catch (error) {
+    state.status = 'failed';
+    state.failedAgent = state.currentAgent;
+    state.error = error instanceof Error ? error.message : String(error);
+    state.summary = computeSummary(state);
+
+    // Log workflow failure summary
+    await a.logWorkflowComplete(activityInput, {
+      status: 'failed',
+      totalDurationMs: state.summary.totalDurationMs,
+      totalCostUsd: state.summary.totalCostUsd,
+      completedAgents: state.completedAgents,
+      agentMetrics: Object.fromEntries(
+        Object.entries(state.agentMetrics).map(([name, m]) => [
+          name,
+          { durationMs: m.durationMs, costUsd: m.costUsd },
+        ])
+      ),
+      error: state.error ?? undefined,
+    });
+
+    throw error;
+  }
+}