feat: surface startup and preflight failures (#454)

* fix: surface pre-workflow worker failures instead of dying silently

* feat: clearer, aggregated config rule validation errors

* fix: preserve blank lines when printing startup errors

* feat: hold start until preflight passes and surface its failure

* fix: cleaner formatting for scan-start failure messages

apps/worker/src/config-parser.ts

@@ -462,8 +462,19 @@ const performSecurityValidation = (config: Config): void => {
   }
 
   if (config.rules) {
-    validateRulesSecurity(config.rules.avoid, 'avoid');
-    validateRulesSecurity(config.rules.focus, 'focus');
+    // Report every bad rule at once, so a config is fixed in one pass rather than one per re-run.
+    const ruleErrors: string[] = [];
+    collectRuleErrors(config.rules.avoid, 'avoid', ruleErrors);
+    collectRuleErrors(config.rules.focus, 'focus', ruleErrors);
+    if (ruleErrors.length > 0) {
+      throw new PentestError(
+        `Configuration validation failed:\n\n${ruleErrors.join('\n\n')}`,
+        'config',
+        false,
+        { validationErrors: ruleErrors },
+        ErrorCode.CONFIG_VALIDATION_FAILED,
+      );
+    }
 
     checkForDuplicates(config.rules.avoid || [], 'avoid');
     checkForDuplicates(config.rules.focus || [], 'focus');
@@ -513,126 +524,108 @@ const performSecurityValidation = (config: Config): void => {
   }
 };
 
-const validateRulesSecurity = (rules: Rule[] | undefined, ruleType: string): void => {
-  if (!rules) return;
+/** Human-readable rule label, e.g. "Focus rule 1" — 1-based to match how an operator counts them. */
+function ruleLabel(ruleType: string, index: number): string {
+  const capitalized = `${ruleType.charAt(0).toUpperCase()}${ruleType.slice(1)}`;
+  return `${capitalized} rule ${index + 1}`;
+}
 
-  rules.forEach((rule, index) => {
-    for (const pattern of DANGEROUS_PATTERNS) {
-      if (pattern.test(rule.value)) {
-        throw new PentestError(
-          `rules.${ruleType}[${index}].value contains potentially dangerous pattern: ${pattern.source}`,
-          'config',
-          false,
-          { field: `rules.${ruleType}[${index}].value`, pattern: pattern.source },
-          ErrorCode.CONFIG_VALIDATION_FAILED,
-        );
-      }
-      if (rule.description !== undefined && pattern.test(rule.description)) {
-        throw new PentestError(
-          `rules.${ruleType}[${index}].description contains potentially dangerous pattern: ${pattern.source}`,
-          'config',
-          false,
-          { field: `rules.${ruleType}[${index}].description`, pattern: pattern.source },
-          ErrorCode.CONFIG_VALIDATION_FAILED,
-        );
-      }
-    }
-
-    validateRuleTypeSpecific(rule, ruleType, index);
-  });
-};
-
-const validateRuleTypeSpecific = (rule: Rule, ruleType: string, index: number): void => {
-  const field = `rules.${ruleType}[${index}].value`;
+/** A rule error as an aligned label/Value/Problem block, so the offending value is easy to spot. */
+function ruleValueMessage(label: string, value: string, problem: string): string {
+  return [`${label}:`, `  Value:   ${value}`, `  Problem: ${problem}`].join('\n');
+}
 
+/**
+ * The type-specific constraint a rule value breaks, or undefined when valid. Returns rather than
+ * throws so every bad rule can be collected and reported together.
+ */
+function ruleTypeProblem(rule: Rule): string | undefined {
   switch (rule.type) {
     case 'url_path':
       if (!rule.value.startsWith('/')) {
-        throw new PentestError(
-          `${field} for type 'url_path' must start with '/'`,
-          'config',
-          false,
-          { field, ruleType: rule.type },
-          ErrorCode.CONFIG_VALIDATION_FAILED,
-        );
+        return "a 'url_path' rule matches the request path only, so it must begin with '/' (e.g. '/api/users')";
       }
-      break;
+      return undefined;
 
     case 'code_path':
       if (rule.value.includes('://')) {
-        throw new PentestError(
-          `${field} for type 'code_path' must not contain a URL protocol (got '${rule.value}')`,
-          'config',
-          false,
-          { field, ruleType: rule.type },
-          ErrorCode.CONFIG_VALIDATION_FAILED,
-        );
+        return "a 'code_path' rule points at source files, so it must not contain a URL protocol like 'http://' (e.g. 'src/api/users.ts' or 'src/**/*.ts')";
       }
-      break;
+      return undefined;
 
     case 'subdomain':
     case 'domain':
       // Basic domain validation - no slashes allowed
       if (rule.value.includes('/')) {
-        throw new PentestError(
-          `${field} for type '${rule.type}' cannot contain '/' characters`,
-          'config',
-          false,
-          { field, ruleType: rule.type },
-          ErrorCode.CONFIG_VALIDATION_FAILED,
-        );
+        return `a '${rule.type}' rule is a host name, so it cannot contain '/' (e.g. 'api.example.com')`;
       }
       // Must contain at least one dot for domains
       if (rule.type === 'domain' && !rule.value.includes('.')) {
-        throw new PentestError(
-          `${field} for type 'domain' must be a valid domain name`,
-          'config',
-          false,
-          { field, ruleType: rule.type },
-          ErrorCode.CONFIG_VALIDATION_FAILED,
-        );
+        return "a 'domain' rule must be a full domain name, including the top-level domain (e.g. 'example.com')";
       }
-      break;
+      return undefined;
 
     case 'method': {
       const allowedMethods = ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS'];
       if (!allowedMethods.includes(rule.value.toUpperCase())) {
-        throw new PentestError(
-          `${field} for type 'method' must be one of: ${allowedMethods.join(', ')}`,
-          'config',
-          false,
-          { field, ruleType: rule.type, allowedMethods },
-          ErrorCode.CONFIG_VALIDATION_FAILED,
-        );
+        return `'${rule.value}' is not a recognized HTTP method — use one of: ${allowedMethods.join(', ')}`;
       }
-      break;
+      return undefined;
     }
 
     case 'header':
       if (!rule.value.match(/^[a-zA-Z0-9\-_]+$/)) {
-        throw new PentestError(
-          `${field} for type 'header' must be a valid header name (alphanumeric, hyphens, underscores only)`,
-          'config',
-          false,
-          { field, ruleType: rule.type },
-          ErrorCode.CONFIG_VALIDATION_FAILED,
-        );
+        return "a header name may contain only letters, digits, hyphens, and underscores (e.g. 'Authorization' or 'X-Api-Key')";
       }
-      break;
+      return undefined;
 
     case 'parameter':
       if (!rule.value.match(/^[a-zA-Z0-9\-_]+$/)) {
-        throw new PentestError(
-          `${field} for type 'parameter' must be a valid parameter name (alphanumeric, hyphens, underscores only)`,
-          'config',
-          false,
-          { field, ruleType: rule.type },
-          ErrorCode.CONFIG_VALIDATION_FAILED,
+        return "a parameter name may contain only letters, digits, hyphens, and underscores (e.g. 'user_id' or 'redirect-url')";
+      }
+      return undefined;
+
+    default:
+      return undefined;
+  }
+}
+
+/**
+ * Append a block to `blocks` for every invalid rule — a dangerous pattern in the value or
+ * description, or a broken type-specific constraint — so all bad rules can be reported together.
+ */
+function collectRuleErrors(rules: Rule[] | undefined, ruleType: string, blocks: string[]): void {
+  if (!rules) return;
+
+  rules.forEach((rule, index) => {
+    const label = ruleLabel(ruleType, index);
+    const dangerousInValue = DANGEROUS_PATTERNS.find((pattern) => pattern.test(rule.value));
+    if (dangerousInValue) {
+      blocks.push(
+        ruleValueMessage(label, rule.value, `contains a potentially dangerous pattern (${dangerousInValue.source})`),
+      );
+    } else {
+      const problem = ruleTypeProblem(rule);
+      if (problem) {
+        blocks.push(ruleValueMessage(label, rule.value, problem));
+      }
+    }
+
+    const description = rule.description;
+    if (description !== undefined) {
+      const dangerousInDescription = DANGEROUS_PATTERNS.find((pattern) => pattern.test(description));
+      if (dangerousInDescription) {
+        blocks.push(
+          ruleValueMessage(
+            `${label} (description)`,
+            description,
+            `contains a potentially dangerous pattern (${dangerousInDescription.source})`,
+          ),
         );
       }
-      break;
-  }
-};
+    }
+  });
+}
 
 const checkForDuplicates = (rules: Rule[], ruleType: string): void => {
   const seen = new Set<string>();

apps/worker/src/paths.ts

@@ -55,6 +55,13 @@ export const SARIF_FILENAME = 'report.sarif';
 /** Deterministic receipt for the canonical report finalization commit. */
 export const REPORT_FINALIZATION_MANIFEST_FILENAME = 'report_finalization_manifest.json';
 
+/**
+ * Reason for a pre-workflow failure (bad config, resume mismatch, worker setup), written under
+ * INTERNAL_DIR for the CLI to surface — at that point Temporal has no record of the run. Must
+ * match STARTUP_ERROR_FILENAME in the CLI package.
+ */
+export const STARTUP_ERROR_FILENAME = 'startup-error.json';
+
 /**
  * Resolve the session.json path for a run directory, preferring the current
  * `.shannon/` location and falling back to the legacy run-root location so

apps/worker/src/temporal/worker.ts

@@ -28,6 +28,7 @@
  *   TEMPORAL_ADDRESS - Temporal server address (default: localhost:7233)
  */
 
+import { mkdirSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { Client, Connection, type WorkflowHandle, WorkflowNotFoundError } from '@temporalio/client';
@@ -40,7 +41,8 @@ import { CAPELLA_FORMAT_VERSION, CAPELLA_PROMPT_SET_VERSION } from '../ai/sast/c
 import { summarizeOperationalMetrics } from '../audit/operational-summary.js';
 import { sanitizeHostname } from '../audit/utils.js';
 import { distributeConfig, parseConfig } from '../config-parser.js';
-import { deliverablesDir, resolveSessionJsonPath } from '../paths.js';
+import { deliverablesDir, INTERNAL_DIR, resolveSessionJsonPath, STARTUP_ERROR_FILENAME } from '../paths.js';
+import { PentestError } from '../services/error-handling.js';
 import { isProviderFailureCategory } from '../types/errors.js';
 import {
   ACCEPTED_CAPELLA_FAILURE_STAGES,
@@ -511,31 +513,61 @@ interface OrchestrationConfig {
   exploit?: boolean;
 }
 
+/**
+ * Parse the scan config into orchestration values, or throw on a broken config. Failing (rather
+ * than falling back to defaults that quietly change scope) lets the caller persist parseConfig's
+ * error for the CLI instead of running a misconfigured scan.
+ */
 async function loadOrchestrationConfig(configPath: string | undefined): Promise<OrchestrationConfig> {
   if (!configPath) return {};
-  try {
-    const config = await parseConfig(configPath);
-    const distributed = distributeConfig(config);
-    const codePathAvoids = distributed.avoid.filter((rule) => rule.type === 'code_path').map((rule) => rule.value);
-    const codePathFocus = distributed.focus.filter((rule) => rule.type === 'code_path').map((rule) => rule.value);
+  const config = await parseConfig(configPath);
+  const distributed = distributeConfig(config);
+  const codePathAvoids = distributed.avoid.filter((rule) => rule.type === 'code_path').map((rule) => rule.value);
+  const codePathFocus = distributed.focus.filter((rule) => rule.type === 'code_path').map((rule) => rule.value);
 
-    return {
-      ...(distributed.agenticSast && {
-        agenticSast: {
-          codePathAvoids,
-          codePathFocus,
-          modelSpec: process.env.SHANNON_AI_MODEL?.trim() || DEFAULT_MODEL_SPEC,
-          capellaFormatVersion: CAPELLA_FORMAT_VERSION,
-          promptSetVersion: CAPELLA_PROMPT_SET_VERSION,
-        },
-      }),
-      exploit: distributed.exploit,
-    };
-  } catch (error) {
-    // A broken config must fail the run, not silently fall back to empty
-    // defaults that quietly change scope (vuln classes, exploit, retries).
-    console.error('Worker configuration could not be loaded. Reference code: CONFIG_VALIDATION_FAILED');
-    process.exit(1);
+  return {
+    ...(distributed.agenticSast && {
+      agenticSast: {
+        codePathAvoids,
+        codePathFocus,
+        modelSpec: process.env.SHANNON_AI_MODEL?.trim() || DEFAULT_MODEL_SPEC,
+        capellaFormatVersion: CAPELLA_FORMAT_VERSION,
+        promptSetVersion: CAPELLA_PROMPT_SET_VERSION,
+      },
+    }),
+    exploit: distributed.exploit,
+  };
+}
+
+// === Startup Failure Persistence ===
+
+/** Reason for a failure that happens before the workflow is created. */
+interface StartupErrorRecord {
+  phase: string;
+  code?: string;
+  message: string;
+}
+
+/**
+ * Persist a pre-workflow failure to the bind-mounted workspace so the CLI can surface it. The
+ * worker exits before the workflow exists, so Temporal has no record and `--rm` removes the
+ * container; the file under INTERNAL_DIR outlives it on the host mount. `workspace` is the CLI's
+ * `--workspace` name (the run directory); absent only when the worker is run off the CLI path.
+ * Best-effort — a persist failure must not mask the original error.
+ */
+function persistStartupError(workspace: string | undefined, error: unknown, phase: string): void {
+  if (!workspace) return;
+  const record: StartupErrorRecord = {
+    phase,
+    ...(error instanceof PentestError && error.code !== undefined && { code: error.code }),
+    message: error instanceof Error ? error.message : String(error),
+  };
+  try {
+    const dir = path.join('./workspaces', workspace, INTERNAL_DIR);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(path.join(dir, STARTUP_ERROR_FILENAME), JSON.stringify(record, null, 2), 'utf8');
+  } catch {
+    // A broken bind mount must not compound the failure; the caller's console.error still fires.
   }
 }
 
@@ -655,24 +687,26 @@ async function waitForWorkflowResult(
 
 // === Main Entry Point ===
 
-async function run(): Promise<void> {
-  // 1. Parse CLI args
-  const args = parseCliArgs(process.argv.slice(2));
-
-  // 2. Connect to Temporal server
-  const address = process.env.TEMPORAL_ADDRESS || 'localhost:7233';
-  console.log(`Connecting to Temporal at ${address}...`);
-
-  const connection = await NativeConnection.connect({ address });
-  const clientConnection = await Connection.connect({ address });
-  const client = new Client({ connection: clientConnection });
+/** A scan whose workflow is durably submitted, with the handles run() needs to await it. */
+interface StartedScan {
+  handle: WorkflowHandle<(input: PipelineInput) => Promise<PipelineState>>;
+  workspace: WorkspaceResolution;
+  worker: Worker;
+  workerDone: Promise<void>;
+}
 
+/**
+ * Run every step that precedes the durable creation of the workflow: config parsing, workspace
+ * resolution, worker setup, and workflow submission. A failure anywhere here is a startup failure
+ * — Temporal holds no record yet — so the reason is persisted for the CLI before it propagates.
+ */
+async function startScan(client: Client, connection: NativeConnection, args: CliArgs): Promise<StartedScan> {
   try {
-    // 3. Validate orchestration and resume state before terminating any workflow.
+    // 1. Validate orchestration and resume state before terminating any workflow.
     const orchestration = await loadOrchestrationConfig(args.configPath);
     const workspace = await resolveWorkspace(client, args, orchestration.exploit ?? true);
 
-    // 4. Bundle workflows and create the worker with the collision-checked activity registry.
+    // 2. Bundle workflows and create the worker with the collision-checked activity registry.
     console.log('Preparing scan...');
     const workflowBundle = await bundleWorkflowCode({
       workflowsPath: path.join(__dirname, 'workflows.js'),
@@ -695,13 +729,11 @@ async function run(): Promise<void> {
       maxConcurrentActivityTaskExecutions: 25,
     });
 
-    // 5. Build the fixed-scope pipeline input.
+    // 3. Build the fixed-scope pipeline input and start worker polling in the background.
     const input = buildPipelineInput(args, workspace, orchestration);
-
-    // 6. Start worker polling in the background.
     const workerDone = worker.run();
 
-    // 7. Submit workflow to the same task queue.
+    // 4. Submit workflow to the same task queue. Past this point the run exists in Temporal.
     const handle = await client.workflow.start<(input: PipelineInput) => Promise<PipelineState>>(
       'pentestPipelineWorkflow',
       {
@@ -711,10 +743,33 @@ async function run(): Promise<void> {
       },
     );
 
-    // 8. Wait for workflow result.
+    return { handle, workspace, worker, workerDone };
+  } catch (startupError) {
+    persistStartupError(args.resumeFromWorkspace, startupError, 'startup');
+    throw startupError;
+  }
+}
+
+async function run(): Promise<void> {
+  // 1. Parse CLI args
+  const args = parseCliArgs(process.argv.slice(2));
+
+  // 2. Connect to Temporal server
+  const address = process.env.TEMPORAL_ADDRESS || 'localhost:7233';
+  console.log(`Connecting to Temporal at ${address}...`);
+
+  const connection = await NativeConnection.connect({ address });
+  const clientConnection = await Connection.connect({ address });
+  const client = new Client({ connection: clientConnection });
+
+  try {
+    // 3. Start the scan: parse config, resolve the workspace, and submit the workflow.
+    const { handle, workspace, worker, workerDone } = await startScan(client, connection, args);
+
+    // 4. Wait for workflow result.
     await waitForWorkflowResult(handle, workspace);
 
-    // 9. Shut down worker gracefully. Final customer copies are workflow-owned.
+    // 5. Shut down worker gracefully. Final customer copies are workflow-owned.
     worker.shutdown();
     await workerDone;
   } finally {
@@ -725,8 +780,10 @@ async function run(): Promise<void> {
 
 const invokedPath = process.argv[1] ? path.resolve(process.argv[1]) : undefined;
 if (invokedPath === fileURLToPath(import.meta.url)) {
-  run().catch(() => {
-    console.error('Worker failed. Reference code: WORKER_FAILED');
+  run().catch((error) => {
+    // startScan persists pre-workflow failures for the CLI; this also logs them in the container.
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`Worker failed: ${message}`);
     process.exit(1);
   });
 }

apps/worker/src/temporal/workflow-errors.ts

@@ -131,10 +131,6 @@ export function formatWorkflowError(error: unknown, currentPhase: string | null,
 
   const segments: string[] = [phaseContext];
 
-  if (unwrapped.type) {
-    segments.push(unwrapped.type);
-  }
-
   segments.push(
     unwrapped.type === null
       ? 'The scan could not be completed.'
@@ -146,6 +142,7 @@ export function formatWorkflowError(error: unknown, currentPhase: string | null,
     if (hint) {
       segments.push(`Hint: ${hint}`);
     }
+    segments.push(`Reference code: ${unwrapped.type}`);
   }
 
   return segments.join('|');