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/temporal/query.ts

@@ -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);
+});