@pensar/apex 2.5.0 → 2.6.1-canary.0cc77dcc

package/src/core/workflows/pentest.ts

@@ -0,0 +1,1022 @@
+import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type {
+  LanguageModelMiddleware,
+  ModelMessage,
+  StreamTextOnStepFinishCallback,
+  ToolSet,
+} from "ai";
+import { hasToolCall } from "ai";
+import type { AgentHooks, Finding } from "../agents/offSecAgent";
+import {
+  OffensiveSecurityAgent,
+  PLAN_MODE_TOOL_NAMES,
+} from "../agents/offSecAgent";
+import {
+  inProcessSubagentSpawner,
+  type SubagentSpawner,
+} from "../agents/offSecAgent/subagentSpawner";
+import type { StreamIdFactory } from "../agents/offSecAgent/types";
+import {
+  type AttackSurfaceAgentInput,
+  BlackboxAttackSurfaceAgent,
+} from "../agents/specialized/attackSurface/blackboxAgent";
+import {
+  grpcAuthorityTarget,
+  toGrpcPentestContext,
+} from "../agents/specialized/attackSurface/grpcSchema";
+import type { PentestResult } from "../agents/specialized/pentest/agent";
+import {
+  buildPentestSystemPrompt,
+  TargetedPentestAgent,
+} from "../agents/specialized/pentest/agent";
+import {
+  buildPlanPrompt,
+  PLAN_PHASE_SYSTEM_PROMPT,
+} from "../agents/specialized/pentest/planPrompt";
+import type {
+  AIAuthConfig,
+  AIModel,
+  CacheMetrics,
+  OpenAIReasoningEffort,
+  ThinkingEffort,
+  UsageRecorder,
+} from "../ai";
+import type { AgentEventBus } from "../eventBus";
+import { FindingsRegistry } from "../findings/registry";
+import { createLogger } from "../logger/structured";
+import {
+  buildPentestReport,
+  REPORT_FILENAME_JSON,
+  REPORT_FILENAME_MD,
+  renderJson,
+  renderMarkdown,
+} from "../report";
+import type { SessionInfo } from "../session";
+import {
+  formatDurationHmsFromMs,
+  writeExecutionMetrics,
+} from "../session/execution-metrics";
+import { loadAttackSurfaceResults } from "../session/loader";
+import {
+  type AgentManifestEntry,
+  buildManifestEntries,
+  finalizeManifest,
+  getCompletedAgentIds,
+  loadSubagentMessages,
+  readAgentManifest,
+  reconcileManifestOnResume,
+  type SwarmTarget,
+  saveSubagentData,
+  updateManifestEntryStatus,
+  writeAgentManifest,
+} from "../session/persistence";
+import { scopedLogger } from "../util/lazyLogger";
+import { createThreatModelPrompt } from "../utils/prompt";
+import {
+  assertDepth,
+  inMemoryRegistryProvider,
+  inProcessSeams,
+  resolveItemHooks,
+  type WorkflowSeams,
+  withFindingPersistedHook,
+} from "./seams";
+import {
+  runWhiteboxAttackSurfaceWorkflow,
+  type WhiteboxAttackSurfaceWorkflowInput,
+} from "./whiteboxAttackSurface";
+
+const log = scopedLogger(() => createLogger("pentest-swarm"));
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+export const DEFAULT_CONCURRENCY = 10;
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface PentestWorkflowInput {
+  /** Live target URL — always required */
+  target: string;
+
+  /** Local codebase path — when provided, enables whitebox attack surface */
+  cwd?: string;
+
+  model: AIModel;
+  session: SessionInfo;
+  authConfig?: AIAuthConfig;
+  abortSignal?: AbortSignal;
+  eventBus?: AgentEventBus;
+
+  /** Callback fired after each agent step completes */
+  onStepFinish?: StreamTextOnStepFinishCallback<ToolSet>;
+
+  /** Called when Anthropic cache metrics are present in a step's providerMetadata */
+  onCacheMetrics?: (metrics: CacheMetrics) => void;
+
+  /** Enable extended thinking for supported models */
+  enableThinking?: boolean;
+
+  /** Adaptive-thinking effort hint (Anthropic Opus/Sonnet 4.6+); ignored elsewhere. */
+  thinkingEffort?: ThinkingEffort | null;
+
+  /** OpenAI reasoning effort for GPT/o-series reasoning models. */
+  openAIReasoningEffort?: OpenAIReasoningEffort | null;
+
+  /** Optional guidance prompt injected into discovery agent system prompts */
+  prompt?: string;
+
+  /** Optional raw threat model content — wrapped with standard preamble and
+   *  injected into discovery agent system prompts alongside `prompt` */
+  threatModel?: string;
+
+  /**
+   * Whitebox-only: when false, the attack surface workflow skips the
+   * `@pensar/surface` deterministic-enumeration path and uses the legacy
+   * pages+apiEndpoints discovery agents for every service app. Defaults
+   * to `true`. Has no effect on blackbox runs.
+   */
+  surfaceIntegrationEnabled?: boolean;
+
+  /** Skip attack-surface/swarm; run single fast-strike operator. See {@link ./fastStrike}. */
+  fastStrike?: boolean;
+
+  /** Spawner routed into the swarm fan-out. Defaults to the in-process spawner. */
+  subagentSpawner?: SubagentSpawner;
+
+  /** Durable AI hooks forwarded to swarm workers; unset outside the durable runtime. */
+  languageModelMiddleware?: LanguageModelMiddleware | LanguageModelMiddleware[];
+  usageRecorder?: UsageRecorder;
+  streamIdFactory?: StreamIdFactory;
+
+  /**
+   * The caller's full {@link AgentHooks} (backends, middleware, usage
+   * recorder, stream ids, inbox transports, extra tools, sandbox), forwarded
+   * to every agent this workflow constructs. Takes precedence over the
+   * individual hook fields above when both are set. Unset → those individual
+   * fields (or their in-process defaults) apply, matching today's behavior.
+   */
+  hooks?: AgentHooks;
+
+  /**
+   * Fan-out / registry / id / browser / hook seams (`./seams.ts`). Defaults
+   * to {@link inProcessSeams}, matching today's in-process behavior.
+   */
+  seams?: WorkflowSeams;
+}
+
+export interface PentestWorkflowResult {
+  findings: Finding[];
+  findingsPath: string;
+  pocsPath: string;
+  reportPath: string | null;
+}
+
+export type { SwarmTarget } from "../session/persistence";
+
+export interface PentestSwarmInput {
+  targets: SwarmTarget[];
+  model: AIModel;
+  session: SessionInfo;
+  authConfig?: AIAuthConfig;
+  abortSignal?: AbortSignal;
+  findingsRegistry: FindingsRegistry;
+  eventBus?: AgentEventBus;
+  onError?: (e: unknown) => void;
+  concurrency?: number;
+  onStepFinish?: StreamTextOnStepFinishCallback<ToolSet>;
+  onCacheMetrics?: (metrics: CacheMetrics) => void;
+  enableThinking?: boolean;
+  thinkingEffort?: ThinkingEffort | null;
+  openAIReasoningEffort?: OpenAIReasoningEffort | null;
+  /**
+   * X display (e.g. `":11"`) for every swarm sub-agent's browser, so a swarm
+   * launched by an orchestrator on a per-endpoint virtual desktop keeps its
+   * workers on that same display instead of the process-wide `DISPLAY`.
+   */
+  display?: string;
+  /** Fan-out spawner. Defaults to the in-process spawner. */
+  subagentSpawner?: SubagentSpawner;
+
+  /** Durable AI hooks forwarded to swarm workers; unset outside the durable runtime. */
+  languageModelMiddleware?: LanguageModelMiddleware | LanguageModelMiddleware[];
+  usageRecorder?: UsageRecorder;
+  streamIdFactory?: StreamIdFactory;
+
+  /**
+   * The caller's full {@link AgentHooks}, forwarded to every worker this
+   * swarm constructs (see {@link PentestWorkflowInput.hooks}). A per-target
+   * override can come from `seams.hooksForItem` (`./seams.ts`).
+   */
+  hooks?: AgentHooks;
+
+  /**
+   * Fan-out / id / hook seams (`./seams.ts`). Defaults to {@link inProcessSeams},
+   * matching today's in-process behavior.
+   */
+  seams?: WorkflowSeams;
+}
+
+// ---------------------------------------------------------------------------
+// Pentest swarm orchestration
+// ---------------------------------------------------------------------------
+
+/**
+ * Explicit, serializable-by-the-caller input for {@link runPentestSwarmTarget}
+ * — everything one swarm target's worker reads, with no reads of
+ * `runPentestSwarm`'s own local scope. A durable caller rebuilds `hooks` and
+ * `seams` on its own side (they carry backends/functions, same as
+ * {@link PentestSwarmInput}) and runs the target as a separate child workflow.
+ */
+export interface PentestSwarmTargetInput {
+  model: AIModel;
+  session: SessionInfo;
+  authConfig?: AIAuthConfig;
+  abortSignal?: AbortSignal;
+  findingsRegistry: FindingsRegistry;
+  eventBus?: AgentEventBus;
+  onStepFinish?: StreamTextOnStepFinishCallback<ToolSet>;
+  onCacheMetrics?: (metrics: CacheMetrics) => void;
+  enableThinking?: boolean;
+  thinkingEffort?: ThinkingEffort | null;
+  openAIReasoningEffort?: OpenAIReasoningEffort | null;
+  display?: string;
+  onError?: (e: unknown) => void;
+  /** The swarm's shared {@link AgentHooks}; merged with `seams.hooksForItem` for this target. */
+  hooks: AgentHooks;
+  seams: WorkflowSeams;
+  /** Manifest entries built by the swarm before fan-out — `manifestEntries[index]` is this target's entry. */
+  manifestEntries: AgentManifestEntry[];
+  /** Subagent ids already completed on resume — a completed target is skipped. */
+  completedIds: Set<string>;
+}
+
+/**
+ * One pentest swarm target: the optional plan phase, then the
+ * {@link TargetedPentestAgent}, with message capture, spawn/complete events,
+ * and persistence on success or failure. Closure-free extraction of
+ * `runPentestSwarm`'s worker body so a durable caller can run it as a
+ * separate child workflow.
+ */
+export async function runPentestSwarmTarget(
+  target: SwarmTarget,
+  index: number,
+  input: PentestSwarmTargetInput,
+): Promise<PentestResult | null> {
+  const {
+    model,
+    session,
+    authConfig,
+    abortSignal,
+    findingsRegistry,
+    eventBus,
+    onStepFinish,
+    onCacheMetrics,
+    enableThinking,
+    thinkingEffort,
+    openAIReasoningEffort,
+    display,
+    onError,
+    hooks: sharedHooks,
+    seams,
+    manifestEntries,
+    completedIds,
+  } = input;
+
+  const entry = manifestEntries[index];
+  const subagentId = entry.id;
+  const subagentName = target.name ?? entry.name;
+
+  if (completedIds.has(subagentId)) return null;
+
+  // Per-target AgentHooks: seams.hooksForItem can give this one target
+  // (e.g. its own lease/backends, its own politeness budget) different
+  // hooks than its siblings; otherwise it inherits sharedHooks as-is.
+  const itemHooks = resolveItemHooks(sharedHooks, seams, target, index);
+  const childSignal =
+    abortSignal && itemHooks.abortSignal
+      ? AbortSignal.any([abortSignal, itemHooks.abortSignal])
+      : (abortSignal ?? itemHooks.abortSignal);
+
+  const previousMessages = loadSubagentMessages(session, subagentId);
+  let lastMessages: ModelMessage[] = [];
+
+  const handleStepFinish: StreamTextOnStepFinishCallback<ToolSet> = (e) => {
+    if (e.response.messages) {
+      lastMessages = e.response.messages;
+    }
+    onStepFinish?.(e);
+  };
+
+  await seams.hooks.onEndpointStart?.({
+    subagentId,
+    subagentName,
+    target: target.target,
+  });
+
+  eventBus?.emit("subagent-spawn", {
+    subagentId,
+    // Fallback label so the spawn is never blank (attack-surface targets often omit name).
+    name: subagentName,
+    input: { target: target.target, objectives: target.objectives },
+  });
+
+  // -- Optional plan phase (when requirePlan + taskDriven are enabled) --
+  if (
+    session.config?.requirePlan &&
+    session.config?.taskDriven &&
+    previousMessages.length === 0 // Skip on resume
+  ) {
+    try {
+      eventBus?.emit("subagent-spawn", {
+        subagentId: `${subagentId}-plan`,
+        name: `${subagentName} (plan)`,
+        input: { target: target.target, objectives: target.objectives },
+        parentSubagentId: subagentId,
+      });
+
+      // Plan agent writes tasks to the execution agent's directory
+      // so the execution agent can see them.
+      const executionTasksDir = join(
+        session.rootPath,
+        "subagents",
+        `${subagentId}-tasks`,
+      );
+      const planAgent = new OffensiveSecurityAgent({
+        system: PLAN_PHASE_SYSTEM_PROMPT,
+        prompt: buildPlanPrompt(target.target, target.objectives, target.grpc),
+        model,
+        session,
+        target: target.target,
+        grpc: target.grpc,
+        mode: "plan",
+        activeTools: [...PLAN_MODE_TOOL_NAMES],
+        stopWhen: hasToolCall("submit_plan"),
+        authConfig,
+        findingsRegistry,
+        subagentId: `${subagentId}-plan`,
+        subagentName: `${subagentName} (plan)`,
+        tasksDir: executionTasksDir,
+        planSubagentId: subagentId,
+        eventBus,
+        onStepFinish,
+        onCacheMetrics,
+        enableThinking,
+        thinkingEffort,
+        openAIReasoningEffort,
+        display,
+        ...itemHooks,
+        abortSignal: childSignal,
+      });
+
+      await planAgent.consume();
+
+      eventBus?.emit("subagent-complete", {
+        subagentId: `${subagentId}-plan`,
+        status: "completed",
+        parentSubagentId: subagentId,
+      });
+    } catch (planErr) {
+      eventBus?.emit("subagent-complete", {
+        subagentId: `${subagentId}-plan`,
+        status: "failed",
+        parentSubagentId: subagentId,
+      });
+      // Plan phase failure is non-fatal — execution agent proceeds without plan
+      log.warn(`Plan phase failed for ${subagentId}: ${planErr}`);
+    }
+  }
+
+  const objectiveStr = target.objectives.join("; ");
+
+  let agent: TargetedPentestAgent | undefined;
+  try {
+    agent = new TargetedPentestAgent({
+      target: target.target,
+      grpc: target.grpc,
+      objectives: target.objectives,
+      model,
+      session,
+      authConfig,
+      findingsRegistry,
+      onStepFinish: handleStepFinish,
+      onCacheMetrics,
+      forwardUsageCallbacksToSpawnedAgents: true,
+      messages: previousMessages.length > 0 ? previousMessages : undefined,
+      eventBus,
+      subagentId,
+      subagentName,
+      enableThinking,
+      thinkingEffort,
+      openAIReasoningEffort,
+      display,
+      ...itemHooks,
+      abortSignal: childSignal,
+    });
+
+    const result = await agent.consume();
+
+    saveSubagentData(session, {
+      agentName: subagentId,
+      target: target.target,
+      objective: objectiveStr,
+      status: "completed",
+      findingsCount: result.findings.length,
+      messages: [...previousMessages, ...lastMessages],
+      systemPrompt: buildPentestSystemPrompt(session),
+      userPrompt: agent.userPrompt,
+    });
+    updateManifestEntryStatus(session, subagentId, "completed");
+
+    eventBus?.emit("subagent-complete", {
+      subagentId,
+      status: "completed",
+    });
+
+    await seams.hooks.onEndpointDone?.(
+      { subagentId, subagentName, target: target.target },
+      result,
+    );
+
+    return result;
+  } catch (error) {
+    saveSubagentData(session, {
+      agentName: subagentId,
+      target: target.target,
+      objective: objectiveStr,
+      status: "failed",
+      error: error instanceof Error ? error.message : String(error),
+      messages: [...previousMessages, ...lastMessages],
+      systemPrompt: buildPentestSystemPrompt(session),
+      userPrompt: agent?.userPrompt ?? "",
+    });
+    updateManifestEntryStatus(session, subagentId, "failed");
+
+    eventBus?.emit("subagent-complete", {
+      subagentId,
+      status: "failed",
+    });
+
+    eventBus?.emit("error", { error, subagentId });
+    await seams.hooks.onEndpointFailed?.(
+      { subagentId, subagentName, target: target.target },
+      error,
+    );
+    onError?.(error);
+    throw error;
+  }
+}
+
+/**
+ * Run a pentest swarm: build manifest, run agents with bounded concurrency
+ * and automatic persistence, then finalize the manifest.
+ *
+ * Each agent gets message capture, callback wrapping, spawn/complete events,
+ * and persistence on success or failure — all handled internally.
+ *
+ * Returns `(PentestResult | null)[]` in the same order as targets.
+ */
+export async function runPentestSwarm(
+  input: PentestSwarmInput,
+): Promise<(PentestResult | null)[]> {
+  const {
+    targets,
+    model,
+    session,
+    authConfig,
+    abortSignal,
+    findingsRegistry: rawFindingsRegistry,
+    eventBus,
+    onError,
+    concurrency = DEFAULT_CONCURRENCY,
+    onStepFinish,
+    onCacheMetrics,
+    enableThinking,
+    thinkingEffort,
+    openAIReasoningEffort,
+    display,
+    subagentSpawner,
+    languageModelMiddleware,
+    usageRecorder,
+    streamIdFactory,
+    hooks,
+    seams: inputSeams,
+  } = input;
+
+  const seams =
+    inputSeams ??
+    inProcessSeams({ fanOut: hooks?.subagentSpawner ?? subagentSpawner });
+  assertDepth(1, seams.limits);
+
+  const spawner = subagentSpawner ?? inProcessSubagentSpawner;
+
+  // The shared AgentHooks every worker gets unless `seams.hooksForItem`
+  // overrides it for that target; `hooks` (the caller's canonical object)
+  // wins over the individual legacy fields where both are set.
+  const sharedHooks: AgentHooks = {
+    subagentSpawner: spawner,
+    languageModelMiddleware,
+    usageRecorder,
+    streamIdFactory,
+    ...hooks,
+  };
+
+  // Ops-typed by the seam; TargetedPentestAgent/OffensiveSecurityAgent only
+  // call the FindingsRegistryOps surface, so this cast is safe for any
+  // RegistryProvider implementation.
+  const findingsRegistry = withFindingPersistedHook(
+    rawFindingsRegistry,
+    seams.hooks.onFindingPersisted,
+  ) as FindingsRegistry;
+
+  const completedIds = getCompletedAgentIds(session);
+
+  // Preserve manifest entries on resume so worker session ids stay stable — the
+  // persisted id is where on-disk messages/dir live. See reconcileManifestOnResume.
+  const existingManifest = readAgentManifest(session);
+  const freshEntries = buildManifestEntries(targets, (name, ordinal) =>
+    seams.ids.newSessionId(name, ordinal),
+  );
+  const manifestEntries = reconcileManifestOnResume(
+    existingManifest,
+    freshEntries,
+  );
+  writeAgentManifest(session, manifestEntries);
+
+  const targetInput: PentestSwarmTargetInput = {
+    model,
+    session,
+    authConfig,
+    abortSignal,
+    findingsRegistry,
+    eventBus,
+    onStepFinish,
+    onCacheMetrics,
+    enableThinking,
+    thinkingEffort,
+    openAIReasoningEffort,
+    display,
+    onError,
+    hooks: sharedHooks,
+    seams,
+    manifestEntries,
+    completedIds,
+  };
+
+  const results = await seams.fanOut.spawnMany(
+    targets,
+    (target, index) => runPentestSwarmTarget(target, index, targetInput),
+    { concurrency, abortSignal },
+  );
+
+  finalizeManifest(session, manifestEntries, results);
+
+  return results;
+}
+
+// ---------------------------------------------------------------------------
+// Workflow
+// ---------------------------------------------------------------------------
+
+/**
+ * Deterministic pentest workflow.
+ *
+ * Phase 1: Run attack surface discovery (whitebox workflow or blackbox agent).
+ * Phase 2: Flatten results into pentest targets.
+ * Phase 3: Spawn a swarm of {@link TargetedPentestAgent} instances in parallel.
+ */
+export async function runPentestWorkflow(
+  input: PentestWorkflowInput,
+): Promise<PentestWorkflowResult> {
+  if (input.fastStrike) {
+    const { runFastStrike } = await import("./fastStrike");
+    return runFastStrike(input);
+  }
+
+  const {
+    target,
+    cwd,
+    model,
+    session,
+    authConfig,
+    abortSignal,
+    eventBus,
+    onStepFinish,
+    onCacheMetrics,
+    enableThinking,
+    thinkingEffort,
+    openAIReasoningEffort,
+    prompt,
+    threatModel,
+    surfaceIntegrationEnabled,
+  } = input;
+
+  // Default registries mirror today's `FindingsRegistry.fromDirectory` resume
+  // behavior (dedup against on-disk findings, model-backed semantic dedup).
+  // `attackSurface` is never read here — the whitebox phase gets its own
+  // registry from `attackSurfaceRegistry`, not this seam.
+  const seams =
+    input.seams ??
+    inProcessSeams({
+      fanOut: input.hooks?.subagentSpawner ?? input.subagentSpawner,
+      registries: {
+        findings: () =>
+          FindingsRegistry.fromDirectory(session.findingsPath, {
+            model,
+            authConfig,
+            abortSignal,
+            sessionId: session.id,
+          }),
+        attackSurface: inMemoryRegistryProvider.attackSurface,
+      },
+    });
+
+  // Merge prompt/threatModel into session.config.prompt for discovery agents
+  if (prompt || threatModel) {
+    const parts: string[] = [];
+    if (threatModel) parts.push(createThreatModelPrompt(threatModel));
+    if (prompt) parts.push(prompt);
+    const combined = parts.join("\n\n");
+
+    if (!session.config) {
+      (session as { config: Record<string, unknown> }).config = {};
+    }
+    session.config!.prompt = session.config?.prompt
+      ? `${session.config?.prompt}\n\n${combined}`
+      : combined;
+  }
+
+  const startedAt = Date.now();
+
+  try {
+    const mode: "blackbox" | "whitebox" = cwd ? "whitebox" : "blackbox";
+
+    // =========================================================================
+    // Phase 1: Attack surface discovery
+    // =========================================================================
+
+    let swarmTargets: SwarmTarget[];
+
+    // Resume: reuse existing attack surface results if available (both modes).
+    const existingResults = loadAttackSurfaceResults(session.rootPath);
+    if (existingResults?.targets && existingResults.targets.length > 0) {
+      swarmTargets = existingResults.targets.map((t) => ({
+        target: t.target,
+        objectives: [t.objective],
+      }));
+      eventBus?.emit("workflow-phase-start", {
+        phase: "discovery",
+        label: "Attack Surface Discovery (cached)",
+      });
+      eventBus?.emit("workflow-phase-complete", {
+        phase: "discovery",
+        summary: {
+          targets: swarmTargets,
+          targetCount: swarmTargets.length,
+          cached: true,
+        },
+      });
+    } else {
+      eventBus?.emit("workflow-phase-start", {
+        phase: "discovery",
+        label: `Attack Surface Discovery (${mode})`,
+        metadata: { mode, target },
+      });
+
+      if (mode === "whitebox") {
+        swarmTargets = await runWhiteboxPhase({
+          codebasePath: cwd!,
+          baseTarget: target,
+          model,
+          session,
+          authConfig,
+          abortSignal,
+          eventBus,
+          onStepFinish,
+          onCacheMetrics,
+          openAIReasoningEffort,
+          surfaceIntegrationEnabled,
+          subagentSpawner: input.subagentSpawner,
+          hooks: {
+            subagentSpawner: input.subagentSpawner,
+            languageModelMiddleware: input.languageModelMiddleware,
+            usageRecorder: input.usageRecorder,
+            streamIdFactory: input.streamIdFactory,
+            ...input.hooks,
+          },
+          seams,
+        });
+      } else {
+        swarmTargets = await runBlackboxPhase({
+          target,
+          model,
+          session,
+          authConfig,
+          abortSignal,
+          eventBus,
+          onStepFinish,
+          onCacheMetrics,
+          openAIReasoningEffort,
+          hooks: {
+            subagentSpawner: input.subagentSpawner,
+            languageModelMiddleware: input.languageModelMiddleware,
+            usageRecorder: input.usageRecorder,
+            streamIdFactory: input.streamIdFactory,
+            ...input.hooks,
+          },
+        });
+      }
+
+      eventBus?.emit("workflow-phase-complete", {
+        phase: "discovery",
+        summary: {
+          targets: swarmTargets,
+          targetCount: swarmTargets.length,
+        },
+      });
+    }
+
+    if (abortSignal?.aborted) {
+      throw new DOMException("Pentest aborted by user", "AbortError");
+    }
+
+    if (swarmTargets.length === 0) {
+      const report = buildPentestReport([], {
+        target,
+        model,
+        sessionId: session.id,
+        mode,
+      });
+      const mdPath = join(session.rootPath, REPORT_FILENAME_MD);
+      const jsonPath = join(session.rootPath, REPORT_FILENAME_JSON);
+      writeFileSync(mdPath, renderMarkdown(report));
+      writeFileSync(jsonPath, renderJson(report));
+
+      return {
+        findings: [],
+        findingsPath: session.findingsPath,
+        pocsPath: session.pocsPath,
+        reportPath: mdPath,
+      };
+    }
+
+    // =========================================================================
+    // Phase 2: Spawn pentest swarm
+    // =========================================================================
+
+    eventBus?.emit("workflow-phase-start", {
+      phase: "pentesting",
+      label: `Pentest Swarm (${swarmTargets.length} targets)`,
+    });
+
+    // Ops-typed by the seam; only the FindingsRegistryOps surface is used
+    // below and by runPentestSwarm, so this cast is safe for any
+    // RegistryProvider implementation.
+    const findingsRegistry = seams.registries.findings() as FindingsRegistry;
+
+    const completedCount = getCompletedAgentIds(session).size;
+
+    if (completedCount < swarmTargets.length) {
+      await runPentestSwarm({
+        targets: swarmTargets,
+        model,
+        session,
+        authConfig,
+        abortSignal,
+        findingsRegistry,
+        eventBus,
+        onStepFinish,
+        onCacheMetrics,
+        enableThinking,
+        thinkingEffort,
+        openAIReasoningEffort,
+        subagentSpawner: input.subagentSpawner,
+        languageModelMiddleware: input.languageModelMiddleware,
+        usageRecorder: input.usageRecorder,
+        streamIdFactory: input.streamIdFactory,
+        hooks: input.hooks,
+        seams,
+      });
+    }
+
+    if (abortSignal?.aborted) {
+      throw new DOMException("Pentest aborted by user", "AbortError");
+    }
+
+    // =========================================================================
+    // Phase 3: Aggregate results
+    // =========================================================================
+
+    eventBus?.emit("workflow-phase-start", {
+      phase: "reporting",
+      label: "Report Generation",
+    });
+
+    // Root-cause grouping — annotates findings with rootCauseGroup + relatedFindings
+    await findingsRegistry.groupByRootCause();
+
+    const findings = [...findingsRegistry.getFindings()];
+
+    const report = buildPentestReport(findings, {
+      target,
+      model,
+      sessionId: session.id,
+      mode,
+    });
+
+    const mdPath = join(session.rootPath, REPORT_FILENAME_MD);
+    const jsonPath = join(session.rootPath, REPORT_FILENAME_JSON);
+
+    writeFileSync(mdPath, renderMarkdown(report));
+    writeFileSync(jsonPath, renderJson(report));
+
+    const severityCounts: Record<string, number> = {};
+    for (const f of findings) {
+      const sev = (f.severity ?? "unknown").toLowerCase();
+      severityCounts[sev] = (severityCounts[sev] ?? 0) + 1;
+    }
+
+    eventBus?.emit("workflow-phase-complete", {
+      phase: "reporting",
+      summary: {
+        reportPath: mdPath,
+        findingsCount: findings.length,
+        findingsBySeverity: severityCounts,
+      },
+    });
+
+    return {
+      findings,
+      findingsPath: session.findingsPath,
+      pocsPath: session.pocsPath,
+      reportPath: mdPath,
+    };
+  } finally {
+    // Runtime only — token usage has exactly one accounting path (the
+    // dashboard's session store), which already persists each step. Writing
+    // workflow-local totals here would compete with and clobber it.
+    const runtime = formatDurationHmsFromMs(Date.now() - startedAt);
+    writeExecutionMetrics({
+      sessionRootPath: session.rootPath,
+      runtime,
+    });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Phase implementations
+// ---------------------------------------------------------------------------
+
+async function runWhiteboxPhase(opts: {
+  codebasePath: string;
+  baseTarget: string;
+  model: AIModel;
+  session: SessionInfo;
+  authConfig?: AIAuthConfig;
+  abortSignal?: AbortSignal;
+  eventBus?: AgentEventBus;
+  onStepFinish?: StreamTextOnStepFinishCallback<ToolSet>;
+  onCacheMetrics?: (metrics: CacheMetrics) => void;
+  openAIReasoningEffort?: OpenAIReasoningEffort | null;
+  surfaceIntegrationEnabled?: boolean;
+  subagentSpawner?: SubagentSpawner;
+  hooks?: AgentHooks;
+  seams?: WorkflowSeams;
+}): Promise<SwarmTarget[]> {
+  const workflowInput: WhiteboxAttackSurfaceWorkflowInput = {
+    codebasePath: opts.codebasePath,
+    model: opts.model,
+    session: opts.session,
+    authConfig: opts.authConfig,
+    abortSignal: opts.abortSignal,
+    eventBus: opts.eventBus,
+    onStepFinish: opts.onStepFinish,
+    onCacheMetrics: opts.onCacheMetrics,
+    openAIReasoningEffort: opts.openAIReasoningEffort,
+    surfaceIntegrationEnabled: opts.surfaceIntegrationEnabled,
+    subagentSpawner: opts.subagentSpawner,
+    hooks: opts.hooks,
+    seams: opts.seams,
+  };
+
+  const result = await runWhiteboxAttackSurfaceWorkflow(workflowInput);
+
+  return result.apps.flatMap((app) =>
+    [...app.pages, ...app.apiEndpoints].map((ep) => {
+      const grpc = toGrpcPentestContext(ep.transport, ep.grpc, ep.path);
+      return {
+        target:
+          grpcAuthorityTarget(grpc, ep.path) ??
+          (ep.path.startsWith("http")
+            ? ep.path
+            : `${opts.baseTarget}${ep.path}`),
+        objectives: ep.pentestObjectives,
+        grpc,
+      };
+    }),
+  );
+}
+
+async function runBlackboxPhase(opts: {
+  hooks?: AgentHooks;
+  target: string;
+  model: AIModel;
+  session: SessionInfo;
+  authConfig?: AIAuthConfig;
+  abortSignal?: AbortSignal;
+  eventBus?: AgentEventBus;
+  onStepFinish?: StreamTextOnStepFinishCallback<ToolSet>;
+  onCacheMetrics?: (metrics: CacheMetrics) => void;
+  openAIReasoningEffort?: OpenAIReasoningEffort | null;
+}): Promise<SwarmTarget[]> {
+  let lastMessages: ModelMessage[] = [];
+
+  const agentInput: AttackSurfaceAgentInput = {
+    ...opts.hooks,
+    target: opts.target,
+    model: opts.model,
+    session: opts.session,
+    authConfig: opts.authConfig,
+    abortSignal:
+      opts.abortSignal && opts.hooks?.abortSignal
+        ? AbortSignal.any([opts.abortSignal, opts.hooks.abortSignal])
+        : (opts.abortSignal ?? opts.hooks?.abortSignal),
+    eventBus: opts.eventBus,
+    subagentId: "attack-surface-agent",
+    onStepFinish: (e) => {
+      if (e.response.messages) {
+        lastMessages = e.response.messages;
+      }
+      opts.onStepFinish?.(e);
+    },
+    onCacheMetrics: opts.onCacheMetrics,
+    openAIReasoningEffort: opts.openAIReasoningEffort,
+  };
+
+  const agent = new BlackboxAttackSurfaceAgent(agentInput);
+
+  opts.eventBus?.emit("subagent-spawn", {
+    subagentId: "attack-surface-agent",
+    name: "Attack Surface Discovery",
+    input: { target: opts.target },
+  });
+
+  try {
+    const result = await agent.consume();
+
+    // Persist attack surface agent data
+    saveSubagentData(opts.session, {
+      agentName: "attack-surface-agent",
+      target: opts.target,
+      status: "completed",
+      messages: lastMessages,
+    });
+
+    opts.eventBus?.emit("subagent-complete", {
+      subagentId: "attack-surface-agent",
+      status: "completed",
+    });
+
+    return result.targets.map((t) => ({
+      target: t.target,
+      objectives: [t.objective],
+    }));
+  } catch (e) {
+    // Persist partial data even on failure
+    saveSubagentData(opts.session, {
+      agentName: "attack-surface-agent",
+      target: opts.target,
+      status: "failed",
+      error: e instanceof Error ? e.message : String(e),
+      messages: lastMessages,
+    });
+
+    opts.eventBus?.emit("subagent-complete", {
+      subagentId: "attack-surface-agent",
+      status: "failed",
+    });
+
+    throw e;
+  }
+}
+
+function loadFindings(findingsPath: string): Finding[] {
+  if (!existsSync(findingsPath)) {
+    return [];
+  }
+
+  return readdirSync(findingsPath)
+    .filter((f) => f.endsWith(".json"))
+    .map((f) => {
+      try {
+        const content = readFileSync(join(findingsPath, f), "utf-8");
+        return JSON.parse(content) as Finding;
+      } catch {
+        return null;
+      }
+    })
+    .filter((f): f is Finding => f !== null);
+}