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>

src/queue-validation.ts

@@ -6,6 +6,7 @@
 
 import { fs, path } from 'zx';
 import { PentestError } from './error-handling.js';
+import { asyncPipe } from './utils/functional.js';
 
 export type VulnType = 'injection' | 'xss' | 'auth' | 'ssrf' | 'authz';
 
@@ -16,9 +17,11 @@ interface VulnTypeConfigItem {
 
 type VulnTypeConfig = Record<VulnType, VulnTypeConfigItem>;
 
+type ErrorMessageResolver = string | ((existence: FileExistence) => string);
+
 interface ValidationRule {
   predicate: (existence: FileExistence) => boolean;
-  errorMessage: string;
+  errorMessage: ErrorMessageResolver;
   retryable: boolean;
 }
 
@@ -94,40 +97,36 @@ const VULN_TYPE_CONFIG: VulnTypeConfig = Object.freeze({
   }),
 }) as VulnTypeConfig;
 
-// Functional composition utilities - async pipe for promise chain
-type PipeFunction = (x: any) => any | Promise<any>;
-
-const pipe =
-  (...fns: PipeFunction[]) =>
-  (x: any): Promise<any> =>
-    fns.reduce(async (v, f) => f(await v), Promise.resolve(x));
-
 // Pure function to create validation rule
-const createValidationRule = (
+function createValidationRule(
   predicate: (existence: FileExistence) => boolean,
-  errorMessage: string,
+  errorMessage: ErrorMessageResolver,
   retryable: boolean = true
-): ValidationRule => Object.freeze({ predicate, errorMessage, retryable });
+): ValidationRule {
+  return Object.freeze({ predicate, errorMessage, retryable });
+}
 
-// Validation rules for file existence (following QUEUE_VALIDATION_FLOW.md)
+// Symmetric deliverable rules: queue and deliverable must exist together (prevents partial analysis from triggering exploitation)
 const fileExistenceRules: readonly ValidationRule[] = Object.freeze([
-  // Rule 1: Neither deliverable nor queue exists
   createValidationRule(
-    ({ deliverableExists, queueExists }) => deliverableExists || queueExists,
-    'Analysis failed: Neither deliverable nor queue file exists. Analysis agent must create both files.'
-  ),
-  // Rule 2: Queue doesn't exist but deliverable exists
-  createValidationRule(
-    ({ deliverableExists, queueExists }) => !(!queueExists && deliverableExists),
-    'Analysis incomplete: Deliverable exists but queue file missing. Analysis agent must create both files.'
-  ),
-  // Rule 3: Queue exists but deliverable doesn't exist
-  createValidationRule(
-    ({ deliverableExists, queueExists }) => !(queueExists && !deliverableExists),
-    'Analysis incomplete: Queue exists but deliverable file missing. Analysis agent must create both files.'
+    ({ deliverableExists, queueExists }) => deliverableExists && queueExists,
+    getExistenceErrorMessage
   ),
 ]);
 
+// Generate appropriate error message based on which files are missing
+function getExistenceErrorMessage(existence: FileExistence): string {
+  const { deliverableExists, queueExists } = existence;
+
+  if (!deliverableExists && !queueExists) {
+    return 'Analysis failed: Neither deliverable nor queue file exists. Analysis agent must create both files.';
+  }
+  if (!queueExists) {
+    return 'Analysis incomplete: Deliverable exists but queue file missing. Analysis agent must create both files.';
+  }
+  return 'Analysis incomplete: Queue exists but deliverable file missing. Analysis agent must create both files.';
+}
+
 // Pure function to create file paths
 const createPaths = (
   vulnType: VulnType,
@@ -170,7 +169,7 @@ const checkFileExistence = async (
   });
 };
 
-// Pure function to validate existence rules
+// Validates deliverable/queue symmetry - both must exist or neither
 const validateExistenceRules = (
   pathsWithExistence: PathsWithExistence | PathsWithError
 ): PathsWithExistence | PathsWithError => {
@@ -182,9 +181,14 @@ const validateExistenceRules = (
   const failedRule = fileExistenceRules.find((rule) => !rule.predicate(existence));
 
   if (failedRule) {
+    const message =
+      typeof failedRule.errorMessage === 'function'
+        ? failedRule.errorMessage(existence)
+        : failedRule.errorMessage;
+
     return {
       error: new PentestError(
-        `${failedRule.errorMessage} (${vulnType})`,
+        `${message} (${vulnType})`,
         'validation',
         failedRule.retryable,
         {
@@ -224,7 +228,7 @@ const validateQueueStructure = (content: string): QueueValidationResult => {
   }
 };
 
-// Pure function to read and validate queue content
+// Queue parse failures are retryable - agent can fix malformed JSON on retry
 const validateQueueContent = async (
   pathsWithExistence: PathsWithExistence | PathsWithError
 ): Promise<PathsWithQueue | PathsWithError> => {
@@ -273,7 +277,7 @@ const validateQueueContent = async (
   }
 };
 
-// Pure function to determine exploitation decision
+// Final decision: skip if queue says no vulns, proceed if vulns found, error otherwise
 const determineExploitationDecision = (
   validatedData: PathsWithQueue | PathsWithError
 ): ExploitationDecision => {
@@ -294,17 +298,18 @@ const determineExploitationDecision = (
 };
 
 // Main functional validation pipeline
-export const validateQueueAndDeliverable = async (
+export async function validateQueueAndDeliverable(
   vulnType: VulnType,
   sourceDir: string
-): Promise<ExploitationDecision> =>
-  (await pipe(
-    () => createPaths(vulnType, sourceDir),
+): Promise<ExploitationDecision> {
+  return asyncPipe<ExploitationDecision>(
+    createPaths(vulnType, sourceDir),
     checkFileExistence,
     validateExistenceRules,
     validateQueueContent,
     determineExploitationDecision
-  )(() => createPaths(vulnType, sourceDir))) as ExploitationDecision;
+  );
+}
 
 // Pure function to safely validate (returns result instead of throwing)
 export const safeValidateQueueAndDeliverable = async (