@pensar/apex 2.5.0 → 2.6.1-canary.025b1ecf

package/build/lib/chunk-ws86wx87.js

@@ -0,0 +1,1412 @@
+import {
+  newSessionId2
+} from "./chunk-jdjagvgr.js";
+import {
+  createLogger,
+  scopedLogger
+} from "./chunk-sgd2126b.js";
+import {
+  assertDepth2,
+  inProcessSeams2,
+  resolveItemHooks2
+} from "./chunk-c2b0hxs7.js";
+import {
+  inProcessSubagentSpawner2
+} from "./chunk-ve7m90fb.js";
+import {
+  collectCommand
+} from "./chunk-fy3bbbqy.js";
+import {
+  CodeAgent2
+} from "./chunk-v2q8anzw.js";
+import {
+  WHITEBOX_APPS_DISCOVERY_SYSTEM_PROMPT2,
+  WHITEBOX_ENDPOINT_DOCUMENTATION_SYSTEM_PROMPT,
+  WHITEBOX_DISCOVERY_SYSTEM_PROMPT2
+} from "./chunk-bqrmw2tn.js";
+import {
+  EndpointSchema2,
+  AppInfoSchema2,
+  AppsDiscoveryResultSchema2,
+  DiscoverySummarySchema2
+} from "./chunk-xpfg2fbk.js";
+import {
+  __export
+} from "./chunk-n0ba7khr.js";
+
+// src/core/workflows/whiteboxAttackSurface.ts
+var exports_whiteboxAttackSurface = {};
+__export(exports_whiteboxAttackSurface, {
+  runIncrementalWhiteboxAttackSurfaceWorkflow: () => runIncrementalWhiteboxAttackSurfaceWorkflow2,
+  runWhiteboxAttackSurfaceApp: () => runWhiteboxAttackSurfaceApp2,
+  runWhiteboxAttackSurfaceWorkflow: () => runWhiteboxAttackSurfaceWorkflow2
+});
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import {
+  existsSync as existsSync2,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  statSync,
+  writeFileSync
+} from "node:fs";
+import { join } from "node:path";
+import pLimit from "p-limit";
+import { z } from "zod";
+
+// src/core/agents/specialized/whiteboxAttackSurface/endpointDocumentationAgent.ts
+var log = scopedLogger(() => createLogger("endpoint-documentation-agent"));
+var ENDPOINT_DOCUMENTATION_CONCURRENCY = 10;
+function getDocumentMethod(endpoint) {
+  return endpoint.kind === "page" ? ["PAGE"] : endpoint.method;
+}
+function buildEndpointDocumentationObjective(opts) {
+  const { app, codebasePath, endpoint, frameworks } = opts;
+  const frameworkLabel = frameworks.length > 0 ? frameworks.join(", ") : "unknown";
+  const documentMethod = getDocumentMethod(endpoint);
+  const methodDisplay = documentMethod.join(",");
+  const methodValue = JSON.stringify(documentMethod.length === 1 ? documentMethod[0] : documentMethod);
+  const endpointType = endpoint.kind === "page" ? "web-endpoint" : "api-endpoint";
+  const isGrpc = !!endpoint.transport && endpoint.transport !== "http";
+  const grpcSection = isGrpc ? `
+## gRPC (deterministically extracted by surface)
+
+This endpoint is a **gRPC method**, not a plain HTTP route. \`routePath\` is the wire path \`/package.Service/Method\` — do NOT glue a host onto it.
+
+- **transport**: ${endpoint.transport}
+- **grpc.serviceFqn**: ${endpoint.grpc?.serviceFqn ?? "(derive from routePath)"}
+- **grpc.method**: ${endpoint.grpc?.method ?? "(derive from routePath)"}
+- **grpc.streamingType**: ${endpoint.grpc?.streamingType ?? "unary"}
+` : "";
+  const grpcInstruction = isGrpc ? ` Because this is a gRPC method, ALSO pass \`transport: "${endpoint.transport}"\` and a \`grpc\` object built from the values above (\`serviceFqn\`, \`method\`, \`streamingType\`, plus \`schemaSource: "proto"\`); you MAY add \`reflectionAvailable\` or \`frontingGatewayOperation\` when the source makes them clear.` : "";
+  const auth = endpoint.auth.length > 0 ? endpoint.auth.join(", ") : "none";
+  const authPrefill = endpoint.auth.length > 0;
+  return `# Document Endpoint: ${methodDisplay} ${endpoint.path}
+
+## Codebase
+- **Repository root:** ${codebasePath}
+- **App:** ${app.name}
+- **App location:** ${app.location}
+- **Framework(s):** ${frameworkLabel}
+
+## Endpoint (deterministically extracted by surface)
+
+- **method**: ${methodDisplay}
+- **routePath**: ${endpoint.path}
+- **file**: ${endpoint.file}:${endpoint.line}
+- **handler**: ${endpoint.handler}
+- **endpointType**: ${endpointType}
+- **auth signals**: ${auth}
+- **prefilled authRequired**: ${authPrefill}
+${grpcSection}
+## Task
+
+Document this **single endpoint** by calling \`document_endpoint\` exactly once. Use the deterministic fields above as-is for \`appName\` (\`"${app.name}"\`), \`routePath\`, \`method\` (\`${methodValue}\`), \`endpointType\` (\`"${endpointType}"\`), \`file\`, \`line\`, and \`handler\`.${grpcInstruction} The remaining fields you must produce yourself:
+
+- **authRequired**: start from the prefilled value above. Override only after reading the middleware chain at the indicated file when the signals are genuinely ambiguous.
+- **description**: 1–2 sentences explaining what this endpoint does in plain English. Read the handler at \`${endpoint.file}:${endpoint.line}\` to ground it.
+- **riskLevel**: \`CRITICAL\` for auth/payment/admin or unauthenticated state-changing routes; \`HIGH\` for authenticated user-data mutations; \`MEDIUM\` for general; \`LOW\` for static/public reads.
+
+Do NOT pass \`pentestObjectives\` — \`document_endpoint\` generates them automatically.
+
+## Scope
+
+This agent is responsible for **exactly one** endpoint. Do not document other endpoints. Do not enumerate routes. Your tool registry blocks \`list_files\`, \`grep\`, and \`document_app\` so this is enforced at the tool layer too.
+
+## Workflow
+
+1. \`read_file\` the handler at \`${endpoint.file}:${endpoint.line}\` (use a small line range — you don't need the whole file).
+2. Optionally read the middleware referenced by auth signals if you need to refine \`authRequired\`.
+3. Call \`document_endpoint\` once with the fields above.
+4. Call \`response\` with \`{ endpointsDocumented: 1, summary: "<one-line summary>" }\`.
+`;
+}
+async function runEndpointDocumentationAgent(opts) {
+  const {
+    codebasePath,
+    app,
+    endpoint,
+    frameworks,
+    model,
+    session,
+    authConfig,
+    abortSignal,
+    eventBus,
+    attackSurfaceRegistry,
+    onStepFinish,
+    onCacheMetrics,
+    openAIReasoningEffort,
+    enableThinking,
+    thinkingEffort,
+    projectThreatModel,
+    parentSubagentId,
+    agentLimiter,
+    subagentSpawner,
+    hooks,
+    mintChildId
+  } = opts;
+  const displayMethod = getDocumentMethod(endpoint);
+  const displayName = `${app.name}: ${displayMethod.join(",")} ${endpoint.path}`;
+  const subagentId = mintChildId ? mintChildId(displayName) : newSessionId2();
+  const objective = buildEndpointDocumentationObjective({
+    app,
+    codebasePath,
+    endpoint,
+    frameworks
+  });
+  const spawner = subagentSpawner ?? inProcessSubagentSpawner2;
+  const spawnChild = () => spawner.spawn({
+    spec: {
+      type: "code",
+      codebasePath,
+      objective,
+      system: WHITEBOX_ENDPOINT_DOCUMENTATION_SYSTEM_PROMPT,
+      excludeTools: ["document_app", "list_files", "grep"],
+      responseSchema: DiscoverySummarySchema2,
+      projectThreatModel,
+      attackSurfaceRegistry
+    },
+    runtime: {
+      model,
+      session,
+      authConfig,
+      abortSignal,
+      enableThinking,
+      thinkingEffort,
+      openAIReasoningEffort,
+      onStepFinish,
+      onCacheMetrics,
+      backends: hooks?.backends,
+      sandbox: hooks?.sandbox,
+      languageModelMiddleware: hooks?.languageModelMiddleware,
+      usageRecorder: hooks?.usageRecorder,
+      streamIdFactory: hooks?.streamIdFactory
+    },
+    subagentId,
+    subagentName: displayName,
+    parentBus: eventBus,
+    parentSubagentId,
+    lifecycleInput: {
+      app: app.name,
+      type: "endpointDocumentation",
+      method: displayMethod,
+      path: endpoint.path
+    }
+  });
+  try {
+    await (agentLimiter ? agentLimiter(spawnChild) : spawnChild());
+    return true;
+  } catch (error) {
+    log.error(`"${subagentId}" FAILED`, error instanceof Error ? error : undefined, { error: String(error) });
+    return false;
+  }
+}
+async function runAppEndpointDocumentation(opts) {
+  const { endpoints, ...shared } = opts;
+  if (endpoints.length === 0)
+    return;
+  const spawner = opts.subagentSpawner ?? inProcessSubagentSpawner2;
+  let anyFailed = false;
+  await spawner.spawnMany(endpoints, async (endpoint) => {
+    const ok = await runEndpointDocumentationAgent({ ...shared, endpoint });
+    if (!ok)
+      anyFailed = true;
+  }, { concurrency: ENDPOINT_DOCUMENTATION_CONCURRENCY });
+  if (anyFailed) {
+    throw new Error(`One or more endpoint documentation agents failed for app ${opts.app.name}`);
+  }
+}
+
+// src/core/integrations/surface/index.ts
+import { existsSync } from "node:fs";
+import { dirname, relative, resolve, sep } from "node:path";
+import { map } from "@pensar/surface";
+var DEP_FILENAMES = [
+  "package.json",
+  "requirements.txt",
+  "pyproject.toml",
+  "setup.py",
+  "Pipfile",
+  "go.mod",
+  "Cargo.toml",
+  "pom.xml",
+  "build.gradle",
+  "build.gradle.kts",
+  "Gemfile",
+  "composer.json"
+];
+function findDependencyRoot(appPath, repoRoot) {
+  const absApp = resolve(appPath);
+  const absRoot = resolve(repoRoot);
+  let current = absApp;
+  while (true) {
+    for (const f of DEP_FILENAMES) {
+      if (existsSync(resolve(current, f))) {
+        return current;
+      }
+    }
+    if (current === absRoot)
+      break;
+    const parent = dirname(current);
+    if (parent === current)
+      break;
+    if (!parent.startsWith(absRoot))
+      break;
+    current = parent;
+  }
+  return absApp;
+}
+function consolidateBySameRoute(endpoints) {
+  const groups = new Map;
+  const handlerSets = new Map;
+  for (const ep of endpoints) {
+    const key = `${ep.file}\x00${ep.path}`;
+    const existing = groups.get(key);
+    if (!existing) {
+      groups.set(key, {
+        method: [ep.method],
+        path: ep.path,
+        handler: ep.handler,
+        file: ep.file,
+        line: ep.line,
+        framework: ep.framework,
+        kind: ep.kind,
+        auth: [...ep.auth],
+        internal: ep.internal,
+        transport: ep.transport,
+        grpc: ep.grpc
+      });
+      handlerSets.set(key, new Set(ep.handler ? [ep.handler] : []));
+      continue;
+    }
+    if (!existing.method.includes(ep.method)) {
+      existing.method.push(ep.method);
+    }
+    if (ep.handler) {
+      const handlers = handlerSets.get(key);
+      if (!handlers.has(ep.handler)) {
+        handlers.add(ep.handler);
+        existing.handler = existing.handler ? `${existing.handler}, ${ep.handler}` : ep.handler;
+      }
+    }
+    for (const a of ep.auth) {
+      if (!existing.auth.includes(a)) {
+        existing.auth.push(a);
+      }
+    }
+  }
+  return [...groups.values()];
+}
+function rebaseFileToRepoRoot(endpoints, scanRoot, repoRoot) {
+  const absScan = resolve(scanRoot);
+  const absRoot = resolve(repoRoot);
+  if (absScan === absRoot)
+    return endpoints;
+  return endpoints.map((ep) => ({
+    ...ep,
+    file: relative(absRoot, resolve(absScan, ep.file))
+  }));
+}
+function scopeEndpointsToApp(endpoints, scanRoot, appPath) {
+  const absApp = resolve(appPath);
+  const absScan = resolve(scanRoot);
+  if (absApp === absScan)
+    return endpoints;
+  const prefix = absApp + sep;
+  return endpoints.filter((ep) => {
+    const epAbs = resolve(absScan, ep.file);
+    return epAbs === absApp || epAbs.startsWith(prefix);
+  });
+}
+function mapAppWithSurface(appPath, repoRoot, options) {
+  const absApp = resolve(appPath);
+  const absRoot = resolve(repoRoot);
+  if (absApp === absRoot && !options?.isSingleAppRepo) {
+    return {
+      mode: "fallback",
+      reason: "app.location is repo root — cannot scope"
+    };
+  }
+  const narrow = map(absApp, { includeInternal: false });
+  if (narrow.frameworks.length > 0 && narrow.endpoints.all.length > 0) {
+    const rebased = rebaseFileToRepoRoot(narrow.endpoints.all, absApp, absRoot);
+    return {
+      mode: "surface",
+      endpoints: consolidateBySameRoute(rebased),
+      frameworks: narrow.frameworks
+    };
+  }
+  const scanRoot = findDependencyRoot(appPath, repoRoot);
+  if (resolve(scanRoot) === absApp) {
+    return { mode: "fallback", reason: "no frameworks detected" };
+  }
+  const wide = map(scanRoot, { includeInternal: false });
+  if (wide.frameworks.length === 0) {
+    return { mode: "fallback", reason: "no frameworks detected" };
+  }
+  const scoped = scopeEndpointsToApp(wide.endpoints.all, scanRoot, appPath);
+  if (scoped.length === 0) {
+    return {
+      mode: "fallback",
+      reason: "frameworks detected but zero endpoints in app.location"
+    };
+  }
+  const rebased = rebaseFileToRepoRoot(scoped, scanRoot, absRoot);
+  return {
+    mode: "surface",
+    endpoints: consolidateBySameRoute(rebased),
+    frameworks: wide.frameworks
+  };
+}
+
+// src/core/workflows/whiteboxAttackSurface.ts
+var log2 = scopedLogger(() => createLogger("whitebox-workflow"));
+var DEFAULT_CONCURRENCY = 5;
+var MAX_CONCURRENT_AGENTS = 12;
+var TASK_TYPE_LABELS = {
+  pages: "Pages",
+  apiEndpoints: "API Endpoints",
+  cloudResourceEndpoints: "Cloud Resources"
+};
+var NON_SERVICE_TYPES = ["cloud_resource", "storage", "database"];
+function sanitizeName(name) {
+  return name.toLowerCase().replace(/[^a-z0-9-_.]/g, "_");
+}
+function toAppMetadata(app) {
+  return {
+    name: app.name,
+    type: app.type,
+    framework: app.framework,
+    description: app.description,
+    location: app.location
+  };
+}
+async function runWhiteboxAttackSurfaceApp2(app, appIndex, input) {
+  const {
+    codebasePath,
+    model,
+    session,
+    authConfig,
+    abortSignal,
+    eventBus,
+    attackSurfaceRegistry,
+    onStepFinish,
+    onCacheMetrics,
+    openAIReasoningEffort,
+    enableThinking,
+    thinkingEffort,
+    projectThreatModel,
+    environments,
+    surfaceIntegrationEnabled,
+    isSingleAppRepo,
+    umbrellaId,
+    mintChildId,
+    agentLimiter,
+    subagentSpawner,
+    hooks: sharedHooks,
+    seams
+  } = input;
+  const appNodeId = `app:${sanitizeName(app.name)}`;
+  const hooksForApp = resolveItemHooks2(sharedHooks, seams, app, appIndex);
+  let failed = false;
+  const spawnDiscoveryAgent = async (type, objective) => {
+    const subagentId = mintChildId(TASK_TYPE_LABELS[type]);
+    log2.debug(`Phase 2: spawning agent id="${subagentId}" parent="${appNodeId}" (app="${app.name}", type=${type}, appType=${app.type})`);
+    const spawner = subagentSpawner ?? inProcessSubagentSpawner2;
+    try {
+      await agentLimiter(() => spawner.spawn({
+        spec: {
+          type: "code",
+          codebasePath,
+          objective,
+          system: WHITEBOX_DISCOVERY_SYSTEM_PROMPT2,
+          excludeTools: ["document_app"],
+          responseSchema: DiscoverySummarySchema2,
+          projectThreatModel,
+          attackSurfaceRegistry
+        },
+        runtime: {
+          model,
+          session,
+          authConfig,
+          abortSignal,
+          enableThinking,
+          thinkingEffort,
+          openAIReasoningEffort,
+          onStepFinish,
+          onCacheMetrics,
+          backends: hooksForApp.backends,
+          sandbox: hooksForApp.sandbox,
+          languageModelMiddleware: hooksForApp.languageModelMiddleware,
+          usageRecorder: hooksForApp.usageRecorder,
+          streamIdFactory: hooksForApp.streamIdFactory
+        },
+        subagentId,
+        subagentName: TASK_TYPE_LABELS[type],
+        parentBus: eventBus,
+        parentSubagentId: appNodeId,
+        lifecycleInput: { app: app.name, type }
+      }));
+      log2.debug(`Phase 2: agent "${subagentId}" completed`);
+    } catch (error) {
+      log2.error(`Phase 2: agent "${subagentId}" FAILED`, error instanceof Error ? error : undefined, { error: String(error) });
+      failed = true;
+    }
+  };
+  const spawnPagesAgent = () => spawnDiscoveryAgent("pages", buildPagesDiscoveryObjective(codebasePath, app));
+  const spawnApiEndpointsAgent = () => spawnDiscoveryAgent("apiEndpoints", buildApiEndpointsDiscoveryObjective(codebasePath, app));
+  const spawnCloudResourceAgent = () => spawnDiscoveryAgent("cloudResourceEndpoints", buildCloudResourceEndpointsObjective(codebasePath, app, environments));
+  try {
+    if (NON_SERVICE_TYPES.includes(app.type)) {
+      await spawnCloudResourceAgent();
+    } else if (!surfaceIntegrationEnabled) {
+      log2.debug(`${app.name}: legacy (surfaceIntegrationEnabled=false)`);
+      await Promise.all([spawnPagesAgent(), spawnApiEndpointsAgent()]);
+    } else {
+      const surfaceResult = mapAppWithSurface(join(codebasePath, app.location), codebasePath, { isSingleAppRepo });
+      if (surfaceResult.mode === "surface") {
+        log2.debug(`${app.name}: surface-driven (${surfaceResult.endpoints.length} endpoints, frameworks=${surfaceResult.frameworks.join(",")})`);
+        await runAppEndpointDocumentation({
+          codebasePath,
+          app,
+          endpoints: surfaceResult.endpoints,
+          frameworks: surfaceResult.frameworks,
+          model,
+          session,
+          authConfig,
+          abortSignal,
+          eventBus,
+          attackSurfaceRegistry,
+          onStepFinish,
+          onCacheMetrics,
+          openAIReasoningEffort,
+          enableThinking,
+          thinkingEffort,
+          projectThreatModel,
+          parentSubagentId: appNodeId,
+          agentLimiter,
+          subagentSpawner,
+          hooks: hooksForApp,
+          mintChildId
+        });
+      } else {
+        log2.debug(`${app.name}: fallback (${surfaceResult.reason})`);
+        await Promise.all([spawnPagesAgent(), spawnApiEndpointsAgent()]);
+      }
+    }
+  } catch {
+    failed = true;
+  }
+  eventBus?.emit("subagent-complete", {
+    subagentId: appNodeId,
+    status: failed ? "failed" : "completed",
+    parentSubagentId: umbrellaId
+  });
+  return failed;
+}
+async function runWhiteboxAttackSurfaceWorkflow2(input) {
+  const {
+    codebasePath,
+    model,
+    session,
+    authConfig,
+    abortSignal,
+    eventBus,
+    attackSurfaceRegistry,
+    onStepFinish,
+    onCacheMetrics,
+    openAIReasoningEffort,
+    enableThinking,
+    thinkingEffort,
+    domains,
+    projectThreatModel,
+    environments,
+    surfaceIntegrationEnabled = true,
+    maxConcurrentAgents = MAX_CONCURRENT_AGENTS,
+    subagentSpawner,
+    hooks,
+    seams: inputSeams
+  } = input;
+  const seams = inputSeams ?? inProcessSeams2();
+  const sharedHooks = { subagentSpawner, ...hooks };
+  let nextChildOrdinal = 0;
+  const mintChildId = (name) => seams.ids.newSessionId(name, nextChildOrdinal++);
+  const agentSlots = pLimit(Math.max(1, maxConcurrentAgents));
+  const agentLimiter = (fn) => agentSlots(fn);
+  const WORKFLOW_UMBRELLA_ID = mintChildId("whitebox-apps-discovery");
+  if (input.incremental && !hooks?.backends)
+    throw new Error("Incremental recon requires owned artifact backends");
+  const appsAgent = new CodeAgent2({
+    codebasePath,
+    objective: input.incremental ? buildIncrementalObjective(codebasePath, input.incremental.diffPath, input.incremental.assetsPath, input.incremental.existingResult, domains, environments).replace("- **Non-route changes** (e.g. utility functions, configs, tests) → skip", "- **Shared-library/configuration changes** → trace affected consumers and update only impacted endpoint assets; skip unrelated changes") + `
+Trace changed shared libraries, deleted files, and root/build/deployment configuration to the applications that consume them. A path outside an application directory does not prove that application is unaffected. Leave unrelated endpoint artifacts unchanged.` : buildAppsDiscoveryObjective(codebasePath, domains, environments),
+    system: input.incremental ? WHITEBOX_DISCOVERY_SYSTEM_PROMPT2 : WHITEBOX_APPS_DISCOVERY_SYSTEM_PROMPT2,
+    model,
+    session,
+    authConfig,
+    attackSurfaceRegistry,
+    eventBus,
+    subagentId: WORKFLOW_UMBRELLA_ID,
+    subagentName: "Whitebox Apps Discovery",
+    onStepFinish: (event) => onStepFinish?.(event),
+    onCacheMetrics,
+    openAIReasoningEffort,
+    enableThinking,
+    thinkingEffort,
+    responseSchema: input.incremental ? IncrementalReconResultSchema : AppsDiscoveryResultSchema2,
+    projectThreatModel,
+    excludeTools: input.incremental ? [] : ["document_endpoint"],
+    ...sharedHooks,
+    ...input.incremental ? { attackSurfaceArtifactsPath: input.incremental.assetsPath } : {},
+    abortSignal
+  });
+  log2.info(`Phase 1: discovering apps in ${codebasePath}${domains?.length ? ` (${domains.length} known domains)` : ""}`);
+  eventBus?.emit("subagent-spawn", {
+    subagentId: WORKFLOW_UMBRELLA_ID,
+    name: "Whitebox Apps Discovery",
+    input: { codebasePath }
+  });
+  const appsResult = await agentLimiter(() => appsAgent.consume());
+  if (input.incremental) {
+    if (!hooks?.backends)
+      throw new Error("Incremental recon requires owned artifact backends");
+    const result = await readIncrementalReconAssets(hooks.backends, input.incremental.assetsPath, input.incremental.existingResult, abortSignal);
+    eventBus?.emit("subagent-complete", {
+      subagentId: WORKFLOW_UMBRELLA_ID,
+      status: "completed"
+    });
+    return result;
+  }
+  log2.info(`Phase 1 complete: ${appsResult?.apps.length ?? 0} apps discovered` + (appsResult ? ` (repoType=${appsResult.repoType}, packageManager=${appsResult.packageManager})` : " (no result returned)"));
+  if (appsResult?.apps.length) {
+    for (const app of appsResult.apps) {
+      log2.debug(`app: "${app.name}" type=${app.type} framework="${app.framework}" location="${app.location}"`);
+    }
+  }
+  if (!appsResult || appsResult.apps.length === 0) {
+    eventBus?.emit("subagent-complete", {
+      subagentId: WORKFLOW_UMBRELLA_ID,
+      status: "completed"
+    });
+    return {
+      repoType: appsResult?.repoType ?? "unknown",
+      packageManager: appsResult?.packageManager ?? "unknown",
+      apps: [],
+      summary: {
+        totalApps: 0,
+        totalPages: 0,
+        totalApiEndpoints: 0,
+        totalPentestObjectives: 0
+      }
+    };
+  }
+  const assetsPath = join(session.rootPath, "assets");
+  mkdirSync(assetsPath, { recursive: true });
+  for (const app of appsResult.apps) {
+    const appDir = join(assetsPath, sanitizeName(app.name));
+    mkdirSync(appDir, { recursive: true });
+    writeFileSync(join(appDir, "app.json"), JSON.stringify(toAppMetadata(app), null, 2), "utf-8");
+  }
+  log2.info(`Phase 2: surfaceIntegrationEnabled=${surfaceIntegrationEnabled}`);
+  const serviceApps = appsResult.apps.filter((app) => !NON_SERVICE_TYPES.includes(app.type));
+  const cloudApps = appsResult.apps.filter((app) => NON_SERVICE_TYPES.includes(app.type));
+  log2.info(`Phase 2: ${serviceApps.length} service apps (surface or fallback per app), ${cloudApps.length} cloud resources → ${appsResult.apps.length} total apps`);
+  const totalApps = appsResult.apps.length;
+  let completedAppCount = 0;
+  eventBus?.emit("app-analysis-progress", {
+    totalApps,
+    completedApps: 0
+  });
+  for (const app of appsResult.apps) {
+    eventBus?.emit("subagent-spawn", {
+      subagentId: `app:${sanitizeName(app.name)}`,
+      name: app.name,
+      input: { app: app.name, type: app.type, framework: app.framework },
+      parentSubagentId: WORKFLOW_UMBRELLA_ID
+    });
+  }
+  const appWorkerInput = {
+    codebasePath,
+    model,
+    session,
+    authConfig,
+    abortSignal,
+    eventBus,
+    attackSurfaceRegistry,
+    onStepFinish,
+    onCacheMetrics,
+    openAIReasoningEffort,
+    enableThinking,
+    thinkingEffort,
+    projectThreatModel,
+    environments,
+    surfaceIntegrationEnabled,
+    isSingleAppRepo: serviceApps.length === 1,
+    umbrellaId: WORKFLOW_UMBRELLA_ID,
+    mintChildId,
+    agentLimiter,
+    subagentSpawner,
+    hooks: sharedHooks,
+    seams
+  };
+  assertDepth2(1, seams.limits);
+  await seams.fanOut.spawnMany(appsResult.apps, async (app, appIndex) => {
+    await runWhiteboxAttackSurfaceApp2(app, appIndex, appWorkerInput);
+    completedAppCount++;
+    eventBus?.emit("app-analysis-progress", {
+      totalApps,
+      completedApps: completedAppCount,
+      appName: app.name
+    });
+  }, { concurrency: DEFAULT_CONCURRENCY });
+  eventBus?.emit("subagent-complete", {
+    subagentId: WORKFLOW_UMBRELLA_ID,
+    status: "completed"
+  });
+  log2.info(`Phase 3: reading assets from ${assetsPath}`);
+  const {
+    apps: parsedApps,
+    repoType,
+    packageManager
+  } = readAppsFromAssetsDirectory(assetsPath, appsResult);
+  for (const app of parsedApps) {
+    log2.debug(`Phase 3: "${app.name}" → ${app.pages.length} pages, ${app.apiEndpoints.length} API endpoints`);
+  }
+  const apps = parsedApps;
+  const totalPages = apps.reduce((sum, a) => sum + a.pages.length, 0);
+  const totalApiEndpoints = apps.reduce((sum, a) => sum + a.apiEndpoints.length, 0);
+  const totalPentestObjectives = apps.reduce((sum, a) => sum + [...a.pages, ...a.apiEndpoints].reduce((s, ep) => s + ep.pentestObjectives.length, 0), 0);
+  return {
+    repoType,
+    packageManager,
+    apps,
+    summary: {
+      totalApps: apps.length,
+      totalPages,
+      totalApiEndpoints,
+      totalPentestObjectives
+    }
+  };
+}
+function readAppsFromAssetsDirectory(assetsPath, appsDiscovery) {
+  const repoType = appsDiscovery?.repoType ?? "unknown";
+  const packageManager = appsDiscovery?.packageManager ?? "unknown";
+  if (!existsSync2(assetsPath)) {
+    log2.debug(`readAssets: assets directory does not exist: ${assetsPath}`);
+    return { apps: [], repoType, packageManager };
+  }
+  const entries = readdirSync(assetsPath);
+  log2.debug(`readAssets: found ${entries.length} entries in ${assetsPath}: [${entries.join(", ")}]`);
+  const apps = [];
+  for (const entry of entries) {
+    const entryPath = join(assetsPath, entry);
+    if (!statSync(entryPath).isDirectory()) {
+      log2.debug(`readAssets: skipping non-directory: ${entry}`);
+      continue;
+    }
+    const appJsonPath = join(entryPath, "app.json");
+    let metadata;
+    if (existsSync2(appJsonPath)) {
+      try {
+        metadata = JSON.parse(readFileSync(appJsonPath, "utf-8"));
+      } catch {
+        log2.warn(`readAssets: skipping app folder with unreadable app.json: ${entry}`);
+        continue;
+      }
+    } else {
+      log2.debug(`readAssets: skipping folder without app.json: ${entry}`);
+      continue;
+    }
+    const pages = [];
+    const apiEndpoints = [];
+    const assetFiles = readdirSync(entryPath).filter((f) => f.endsWith(".json") && f !== "app.json");
+    log2.debug(`readAssets: app "${metadata.name}" (${entry}): ${assetFiles.length} asset files`);
+    let parseFailed = 0;
+    for (const file of assetFiles) {
+      try {
+        const raw = readFileSync(join(entryPath, file), "utf-8");
+        const data = JSON.parse(raw);
+        const endpoint = assetRecordToEndpoint(data);
+        if (!endpoint) {
+          log2.debug(`readAssets: ${file}: failed schema validation (assetRecordToEndpoint returned null)`);
+          parseFailed++;
+          continue;
+        }
+        if (isPageEndpoint(data)) {
+          pages.push(endpoint);
+        } else {
+          apiEndpoints.push(endpoint);
+        }
+      } catch {
+        log2.warn(`readAssets: skipping unreadable asset file: ${entry}/${file}`);
+        parseFailed++;
+      }
+    }
+    log2.debug(`readAssets: app "${metadata.name}": ${pages.length} pages, ${apiEndpoints.length} API endpoints, ${parseFailed} failed`);
+    apps.push({
+      name: metadata.name,
+      type: metadata.type ?? "web_application",
+      framework: metadata.framework,
+      description: metadata.description,
+      location: metadata.location,
+      pages,
+      apiEndpoints
+    });
+  }
+  return { apps, repoType, packageManager };
+}
+function assetRecordToEndpoint(record) {
+  const rawMethod = record.method;
+  const method = Array.isArray(rawMethod) ? rawMethod.join(", ") : rawMethod ?? "UNKNOWN";
+  const path = record.routePath;
+  const file = record.file ?? "";
+  const parsed = EndpointSchema2.safeParse({
+    method,
+    path,
+    handler: record.handler,
+    file,
+    line: record.line,
+    authRequired: record.authRequired,
+    description: record.description,
+    pentestObjectives: record.pentestObjectives ?? [],
+    riskScore: record.riskScore,
+    threatModel: record.threatModel,
+    transport: record.transport,
+    grpc: record.grpc
+  });
+  return parsed.success ? parsed.data : null;
+}
+function isPageEndpoint(record) {
+  const method = record.method;
+  if (typeof method === "string") {
+    return method.toUpperCase() === "PAGE";
+  }
+  if (Array.isArray(method)) {
+    return method.length === 1 && method[0].toUpperCase() === "PAGE";
+  }
+  return false;
+}
+function buildAppsDiscoveryObjective(codebasePath, domains, environments) {
+  const domainSection = domains?.length ? `
+## Known Domains
+The following domains are associated with this project. When you document an application, set the \`domain\` field on \`document_app\` if you can determine which domain the app is served from:
+${domains.map((d) => `- ${d}`).join(`
+`)}
+` : "";
+  const environmentsSection = environments?.length ? `
+## Target Environments
+This project is deployed to the following environments:
+${environments.map((e) => `- **${e}**`).join(`
+`)}
+
+**Per-environment app creation:** When infrastructure-as-code or configuration defines resources that are dynamically named per environment (e.g. environment-prefixed S3 buckets, stage-scoped databases, per-environment API endpoints), you MUST create a **separate app entry for each environment**. Use the environment name as a prefix in the app name (e.g. \`${environments[0]}-user-uploads-bucket\`, \`${environments.length > 1 ? environments[1] : "staging"}-api-gateway\`).
+
+**How to identify environment-scoped resources:**
+- IaC that interpolates a stage/environment variable into resource names (e.g. \`\${stage}-my-bucket\`, \`\${env}-api\`, \`$app.$stage.example.com\`)
+- Separate config blocks, Terraform workspaces, SST stages, or CDK stacks per environment
+- Environment variables or config files that change resource identifiers per stage
+
+**For each environment** (${environments.join(", ")}), create an app entry with:
+- **name**: \`<environment>-<resource-name>\` (e.g. \`${environments[0]}-data-bucket\`)
+- **domain**: Substitute the environment name into the IaC naming pattern to derive the environment-specific URL (e.g. IaC has \`\${stage}-data\` → \`https://${environments[0]}-data.s3.amazonaws.com\`). Omit if no naming pattern exists in the code.
+
+**Shared resources:** If a resource is clearly shared across all environments (e.g. a single CDN distribution, a shared auth service), document it once without an environment prefix.
+` : "";
+  return `# Identify All Applications in the Repository
+
+## Phase scope — read this first
+This objective is **Phase 1: app discovery only**. Your job is to enumerate
+applications and call \`document_app\` for each. **Do NOT call
+\`document_endpoint\` in this phase** — endpoints are documented in a later
+phase by per-app subagents. The \`document_endpoint\` tool is intentionally
+unavailable here. Ignore any general guidance in the system prompt that
+tells you to call it; that guidance applies only to later phases.
+
+## Codebase
+- **Path:** ${codebasePath}
+${domainSection}${environmentsSection}
+## Task
+Analyze the repository structure and identify every **deployed application or service** (APIs, web apps, microservices) defined within it. Also discover **cloud resources and external services** referenced in the code that are owned by the target (e.g. S3 buckets, cloud storage, CDN origins, message queues).
+
+**IMPORTANT: Only include deployable apps, services, and owned cloud resources.** Exclude:
+- Libraries, SDKs, and shared packages that are consumed by other code but not deployed on their own
+- Git submodules (external dependencies)
+- Build tools, scripts, CLI utilities, and dev tooling
+- Test suites, fixtures, and test helpers
+- Documentation packages
+- Third-party SaaS services not owned by the target (e.g. Stripe, auth providers)
+- **Individual API routes, web pages, or HTTP endpoints.** Endpoint enumeration is handled by a separate phase that runs after this one. Even if you discover route files (\`page.tsx\`, \`route.ts\`, controller methods) while navigating the codebase, do NOT call \`document_app\` for them. Each \`document_app\` call must represent a deployable application or cloud resource, never a single endpoint. The \`document_endpoint\` tool is intentionally not available to you.
+
+An app/service qualifies if it **listens on a port, serves HTTP traffic, or runs as a deployed process** (e.g. an Express server, a Next.js app, a Django project, a FastAPI service, a background worker with an API).
+
+A **cloud resource** qualifies if it is an **owned infrastructure resource** referenced in the code — S3 buckets, GCS buckets, Azure Blob Storage, CloudFront distributions, Redis/ElastiCache instances, SQS queues, etc. These are part of the attack surface because they may have misconfigured permissions, public access, or sensitive data.
+
+### Steps
+1. List the root directory and read top-level config files (package.json, requirements.txt, Cargo.toml, go.mod, etc.)
+2. **Check for git submodules** — run \`git submodule status\` or check for a \`.gitmodules\` file. Exclude all submodule directories.
+3. Determine the **repo type**: monorepo (workspaces), single-app, multi-package, etc.
+4. Determine the **package manager**: npm, yarn, pnpm, pip, cargo, go modules, etc.
+5. Identify all **deployable** applications/services (ignoring submodules, libraries, and shared packages):
+   - For monorepos: look at workspace packages that have their own server entry point, Dockerfile, or deploy config — skip packages that are libraries/utilities consumed by other packages
+   - For multi-service repos: look at separate service directories with their own server startup
+   - For single apps: the root is the app
+6. **Discover cloud resources** referenced in the codebase:
+   - Search for S3 bucket references (\`s3://\`, \`new S3Client\`, \`boto3.client('s3')\`, bucket name strings in config)
+   - Search for cloud storage URLs (e.g. \`*.s3.amazonaws.com\`, \`storage.googleapis.com\`)
+   - Search for CDN/distribution configs (CloudFront, Cloudflare, etc.)
+   - Search for message queue references (SQS, SNS, RabbitMQ, etc.)
+   - Search for cache/database endpoints (ElastiCache, Redis, DynamoDB, etc.)
+   - Check infrastructure-as-code files (Terraform, CloudFormation, CDK, Pulumi, SST, serverless.yml)
+   - Document each cloud resource as an app with \`appType: "cloud_resource"\` or \`appType: "storage"\`
+7. For each app/resource, determine:
+   - **name**: the application or service name
+   - **framework**: the web framework or cloud service (e.g. "AWS S3", "CloudFront", "Express")
+   - **description**: brief summary of what it does
+   - **location**: path relative to the repository root (for code) or the resource identifier (for cloud resources)
+   - **type**: classify as \`"web_application"\` for frontend-only apps, \`"api"\` for backend API services, \`"full_stack"\` for frameworks serving both UI and API (Next.js, Remix, Nuxt, SvelteKit, Django with templates, Rails), \`"database"\` for databases, \`"cloud_resource"\` for owned cloud infra (SQS, CDN, etc.), \`"storage"\` for S3/GCS/blob storage.
+
+### Setting the \`domain\` field on \`document_app\` — CRITICAL
+
+**Only set \`domain\` when you can deterministically derive it from evidence** — Known Domains list, IaC resource definitions, configuration files, environment variables, or route definitions. Substituting a known environment/stage name into an IaC naming pattern IS deterministic (e.g. IaC defines \`\${stage}-bucket\` and the target environments include "production" → \`https://production-bucket.s3.amazonaws.com\` is valid). However, do NOT invent domains with no supporting evidence — if no domain can be derived from the source, **omit the \`domain\` field entirely**. A missing domain is far better than a hallucinated one.
+
+When you CAN determine the domain, each resource must have its OWN unique, resource-specific domain. Never reuse a generic domain or another application's domain.
+
+**For web apps and API services:** Use the public-facing URL from the Known Domains list, route configuration, or infrastructure definition (e.g., \`https://console.pensar.dev\`, \`https://api.example.com\`).
+
+**For S3 / GCS / blob storage buckets:** Derive the **actual bucket name** from the infrastructure-as-code. The bucket name is defined in the IaC resource definition (e.g., SST \`new sst.aws.Bucket("ProjectData")\` produces a bucket with a name like \`console-staging-projectdata-abc123\`). Set domain to \`https://{actual-bucket-name}.s3.amazonaws.com\`. If the IaC uses a stage/environment variable in the name, substitute the known environment name (e.g. \`\${stage}-projectdata\` with environment "production" → \`https://production-projectdata.s3.amazonaws.com\`). **NEVER use \`https://s3.amazonaws.com\`** — that is the S3 service, not a bucket. If you cannot determine the bucket name at all, omit the domain.
+
+**For databases (RDS, Aurora, DynamoDB):** Use the cluster/instance endpoint from IaC. If the exact endpoint isn't determinable, omit the domain.
+
+**For Redis / ElastiCache:** Use the cache cluster endpoint if determinable, otherwise omit.
+
+**For SQS queues:** Use \`https://sqs.{region}.amazonaws.com/{account}/{queue-name}\` if determinable, otherwise omit.
+
+**For Lambda functions:** Use the Lambda Function URL or the API Gateway route — NOT a generic API domain shared by all functions. If no concrete URL is determinable, omit.
+
+**For CloudFront / CDN:** Use the distribution domain or custom domain alias if determinable, otherwise omit.
+
+**For WebSocket APIs:** Use the WebSocket endpoint URL if determinable, otherwise omit.
+
+When finished, call the \`response\` tool with your structured findings. Do not call \`document_app\` for individual routes, pages, or endpoints — that is a separate phase's responsibility.`;
+}
+function buildPagesDiscoveryObjective(codebasePath, appInfo) {
+  return `# Find All Web Pages in ${appInfo.name}
+
+## Codebase
+- **Repository root:** ${codebasePath}
+- **App location:** ${appInfo.location}
+- **Framework:** ${appInfo.framework}
+
+## Scope — CRITICAL
+**Only document pages/views that are DEFINED within this application (\`${appInfo.location}\`).** A page belongs to this app if its route definition or component file lives inside \`${appInfo.location}\`.
+
+Do NOT document:
+- Routes defined in other applications or packages (even if this app imports/calls them)
+- External URLs or cloud resource endpoints that this app links to or fetches from
+- API endpoints (those are handled separately)
+
+## Task
+Find ALL web pages, views, and routes that render HTML or serve client-side UI **defined in this application's source code**.
+
+### What to look for (by framework)
+- **React/Next.js**: pages/ or app/ directory, route components, layout files
+- **Express**: res.render(), res.sendFile(), static file serving, template routes
+- **Django**: urls.py patterns pointing to template views, class-based views with template_name
+- **Rails**: routes.rb entries pointing to controller actions that render views
+- **Vue/Nuxt**: pages/ directory, router definitions
+- **FastAPI**: routes returning HTMLResponse, Jinja2 template responses
+- **Spring**: @Controller methods returning view names, Thymeleaf templates
+
+### How to document each page
+For each page, call \`document_endpoint\` with:
+- **appName**: \`${appInfo.name}\`
+- **endpointType**: \`"web-endpoint"\`
+- **description**: Brief description of what this page shows
+- **routePath**: The HTTP route this page serves (e.g., \`/dashboard\`). This is the URL path a client requests — it is the endpoint's identity. NOT a file path.
+- **method**: \`"PAGE"\`
+- **file**: Source-code file where this page is defined (e.g., \`src/pages/dashboard.tsx\`). Must be inside \`${appInfo.location}\`. This is NOT the route.
+- **line**: Line number (if determinable)
+- **handler**: Component or handler name
+- **authRequired**: Whether the page requires authentication
+- **riskLevel**: CRITICAL for admin/auth pages, HIGH for user data, MEDIUM for general, LOW for static/public
+
+### Required workflow — NO MANIFESTS, NO BATCHING
+**You MUST call \`document_endpoint\` directly, one page at a time, the moment you identify a route.** It is a hard error to:
+- Build a JSON file, array, or list of pages-to-document and then "process" it (e.g. \`cat > /tmp/pages.json << EOF [...] EOF\`).
+- Write a Python or shell script that emits \`document_endpoint\` calls.
+- Defer documentation until "the end" or until "you have the full picture."
+- Stop early because the calls feel repetitive or because you've documented "the important ones."
+
+These patterns hit per-message output-token limits and silently drop pages — usually the alphabetically-later ones. The only correct loop is: identify route → call \`document_endpoint\` → identify next route → call \`document_endpoint\` → ...
+
+You may use \`list_files\`, \`grep\`, or \`execute_command\` (e.g. \`find ... -name page.tsx\`) to **enumerate** the routes that exist. That enumeration step is fine and encouraged. What is not allowed is using a script to **emit the documentation calls themselves** — those must come directly from you, one tool call per route.
+
+Be thorough — examine every route file, every page directory, every template **within \`${appInfo.location}\`**. Every page surfaced by your enumeration must result in its own \`document_endpoint\` call. Repetitive calls are expected; do not summarize, deduplicate to "interesting" routes, or skip any.
+
+When finished, call \`response\` with a summary of how many pages you documented. The reported count must equal the number of successful \`document_endpoint\` calls you made.`;
+}
+function buildApiEndpointsDiscoveryObjective(codebasePath, appInfo) {
+  return `# Find All API Endpoints in ${appInfo.name}
+
+## Codebase
+- **Repository root:** ${codebasePath}
+- **App location:** ${appInfo.location}
+- **Framework:** ${appInfo.framework}
+
+## Scope — CRITICAL
+**Only document API routes that are DEFINED within this application (\`${appInfo.location}\`).** An endpoint belongs to this app if its route handler or route definition file lives inside \`${appInfo.location}\`.
+
+Do NOT document:
+- Routes defined in other applications or packages
+- External API calls this app makes to third-party services or other internal services
+- S3 bucket URLs, cloud resource endpoints, or CDN URLs that this app interacts with — those belong to the cloud resource, not this API
+- Web pages/views (those are handled separately)
+
+## Task
+Find ALL API endpoints **whose route definitions live in this application's source code**.
+
+### What to look for (by framework)
+- **Express**: app.get(), app.post(), router.get(), router.post(), router.put(), router.delete(), etc.
+- **Next.js**: app/api/ or pages/api/ route handlers (GET, POST, PUT, DELETE exports)
+- **Django**: urls.py patterns pointing to API views, DRF viewsets, routers, @api_view decorators
+- **FastAPI**: @app.get(), @app.post(), @app.put(), @app.delete() decorators
+- **Rails**: routes.rb API namespaces, resources, controller actions
+- **Spring**: @GetMapping, @PostMapping, @PutMapping, @DeleteMapping, @RequestMapping
+- **Go**: http.HandleFunc, mux.Handle, gin router methods
+- **gRPC**: \`.proto\` service definitions (\`service X { rpc Method (Req) returns (Resp); }\`), \`buf.yaml\`/\`buf.gen.yaml\`, or generated gRPC stubs
+
+### gRPC / Connect services — do NOT flatten into HTTP paths
+A gRPC method looks like a path (\`/package.Service/Method\`) but is NOT an HTTP route. When this app defines gRPC/Connect services, document **one \`document_endpoint\` per \`rpc\` method** with:
+- **endpointType**: \`"api-endpoint"\` (a gRPC method is still an API endpoint)
+- **transport**: \`"grpc"\` (or \`"grpc_web"\` / \`"connect"\` if the service is served that way)
+- **routePath**: the wire path \`/package.Service/Method\` (e.g. \`/account.v1.AccountService/GetAccount\`) — do NOT prepend a host
+- **grpc**: \`{ serviceFqn, method, streamingType, schemaSource: "proto" }\` where \`serviceFqn\` is the fully-qualified service (\`account.v1.AccountService\`), \`method\` is the rpc name, and \`streamingType\` is one of \`unary | server_stream | client_stream | bidi\` (based on the \`stream\` keywords in the rpc signature). Set \`reflectionAvailable: true\` if the server registers the gRPC reflection service.
+- If a REST/GraphQL gateway (e.g. grpc-gateway annotations, a GraphQL resolver, a Connect handler) maps to this rpc, set \`grpc.frontingGatewayOperation\` — prefer marking this whenever a gateway mapping exists, since it's what lets us later compute "shadow" methods (proto methods reachable directly but NOT exposed via the gateway, where auth checks usually live).
+
+### How to document each endpoint
+For each **unique route path**, call \`document_endpoint\` with:
+- **appName**: \`${appInfo.name}\`
+- **endpointType**: \`"api-endpoint"\`
+- **description**: Brief description of what this endpoint does across all its methods
+- **routePath**: The HTTP route (e.g., \`/api/users\`, \`/api/orders/:id\`). This is the URL path a client requests — it is the endpoint's identity. NOT a source-file path.
+- **method**: Array of ALL HTTP methods this path supports (e.g., \`["GET", "POST"]\`). **Do NOT create separate entries for each method — consolidate them.**
+- **file**: Source-code file where the endpoint is defined (e.g., \`src/routes/users.ts\`). Must be inside \`${appInfo.location}\`. This is NOT the route.
+- **line**: Line number (if determinable)
+- **handler**: Handler function name (comma-separate if multiple handlers for different methods)
+- **authRequired**: Whether the endpoint requires authentication (true if ANY method requires it)
+- **riskLevel**: CRITICAL for auth/payment/admin, HIGH for user data mutations, MEDIUM for general, LOW for read-only public
+- **transport / grpc**: for gRPC / Connect / gRPC-Web methods, this checklist is not enough — ALSO pass the \`transport\` and \`grpc\` fields exactly as described in the "gRPC / Connect services" section above. Never document an \`rpc\` as a plain HTTP route.
+
+**CRITICAL: ONE entry per route path.** If \`/api/products\` has GET (list) and POST (create), document it as ONE entry with \`method: ["GET", "POST"]\`. Do NOT create two separate entries.
+
+**IMPORTANT — Method consolidation for document_endpoint:** When using the \`document_endpoint\` tool, do NOT create separate entries for different HTTP methods on the same route path. For example, if \`/api/users\` supports GET, POST, and DELETE, document it as ONE entry with \`method: ["GET", "POST", "DELETE"]\` and include pentest objectives covering all methods.
+
+### Required workflow — NO MANIFESTS, NO BATCHING
+**You MUST call \`document_endpoint\` directly, one route at a time, the moment you identify it.** It is a hard error to:
+- Build a JSON file, array, or list of endpoints-to-document and then "process" it (e.g. \`cat > /tmp/endpoints.json << EOF [...] EOF\`).
+- Write a Python or shell script that emits \`document_endpoint\` calls.
+- Defer documentation until you've "mapped everything out."
+- Stop early because the calls feel repetitive or because you've covered "the important ones."
+
+These patterns hit per-message output-token limits and silently drop endpoints — usually the alphabetically-later ones. The only correct loop is: identify route → call \`document_endpoint\` → identify next route → call \`document_endpoint\` → ...
+
+You may use \`list_files\`, \`grep\`, or \`execute_command\` to **enumerate** routes (e.g. extracting all route registrations into a list to read). That enumeration step is fine. What is not allowed is using a script to **emit the documentation calls themselves** — those must come directly from you, one tool call per unique route path.
+
+Be thorough — trace through all route registrations, middleware chains, and controller files **within \`${appInfo.location}\`**. Every unique route path your enumeration surfaces must result in its own \`document_endpoint\` call.
+
+When finished, call \`response\` with a summary of how many endpoints you documented. The reported count must equal the number of successful \`document_endpoint\` calls you made.`;
+}
+function buildCloudResourceEndpointsObjective(codebasePath, appInfo, environments) {
+  const envNote = environments?.length ? `
+## Target Environments
+This resource may exist in the following environments: ${environments.join(", ")}. When documenting entry points, use the **environment-specific resource identifiers** (e.g. environment-prefixed bucket names, stage-scoped queue URLs, per-environment ARNs). If the app name already includes an environment prefix, use that environment's resource names in the endpoints.
+` : "";
+  return `# Document Entry Points for Cloud Resource: ${appInfo.name}
+
+## Codebase
+- **Repository root:** ${codebasePath}
+- **Resource location:** ${appInfo.location}
+- **Service:** ${appInfo.framework}
+${envNote}
+## Context — Application Domain
+The parent application for this cloud resource already has a domain/URL associated with it (set via \`document_app\`). **Do NOT create endpoints that simply repeat the base domain URL.** The domain is already stored on the application record — endpoints should document **distinct access patterns** that go beyond the base domain.
+
+## Scope — CRITICAL
+You are documenting the **distinct access patterns and resource identifiers** for this cloud resource — specific ways the resource can be accessed that are NOT just its base domain URL.
+
+Do NOT document:
+- The base domain URL of the resource (e.g. \`https://bucket-name.s3.amazonaws.com\`) — this is already the application's domain
+- Code locations where the app calls/uses this resource (e.g. "line 42 of api.ts calls S3.putObject" is NOT an endpoint)
+- API routes from other apps that happen to interact with this resource
+- Internal SDK calls or client instantiations
+
+DO document:
+- **Specific access patterns** beyond the base domain (e.g. pre-signed URL patterns, static website hosting paths, object key patterns)
+- **Resource ARNs** that represent programmatic access points (e.g. \`arn:aws:s3:::bucket-name\`, \`arn:aws:sqs:region:account:queue-name\`)
+- **Alternative access URLs** (e.g. CDN distribution URL, static website hosting URL, regional endpoint variants)
+- **Queue/topic URLs** for message-based resources
+
+## Task
+Find the **distinct access patterns and resource identifiers** for this cloud resource by reading infrastructure-as-code and configuration.
+
+### Where to find entry point information
+1. **Infrastructure-as-code** — Terraform (*.tf), CloudFormation (*.yaml/*.json), CDK constructs, SST components (sst.config.ts, infra/), Pulumi, serverless.yml — these define the resource and its access configuration
+2. **Configuration files** — .env files, config modules, environment variable definitions that contain resource URLs
+3. **Resource policies** — bucket policies, CORS configs, access control settings that reveal how the resource is exposed
+
+### What qualifies as an entry point (by resource type)
+- **S3 / GCS / Blob Storage**: Pre-signed URL patterns (e.g. \`/{objectKey}?X-Amz-Signature={sig}\`), static website hosting URL, ARN. Do NOT include the plain bucket HTTPS endpoint — that's the app domain.
+- **CloudFront / CDN**: Custom domain aliases, origin access patterns
+- **SQS / SNS / Message Queues**: Queue URL, topic ARN
+- **Lambda / Cloud Functions**: Function URL, API Gateway integration URL
+- **DynamoDB / ElastiCache / Redis**: Connection endpoint URL, ARN
+
+### How to document each entry point
+For each entry point, call \`document_endpoint\` with:
+- **appName**: \`${appInfo.name}\`
+- **endpointType**: \`"asset"\`
+- **description**: What this entry point exposes (e.g., "Pre-signed HTTP URLs for temporary read access to objects", "AWS resource ARN for programmatic access through IAM policies")
+- **routePath**: The specific access pattern, path template, or ARN — this is the endpoint's identity. NOT the base domain URL. Examples: \`/{objectKey}?X-Amz-Signature={signature}&X-Amz-Credential={credential}\`, \`arn:aws:s3:::bucket-name\`, \`https://sqs.region.amazonaws.com/account/queue-name\`
+- **method**: Access methods on the resource (e.g., \`["GET", "PUT"]\` for S3, \`["SendMessage", "ReceiveMessage"]\` for SQS, \`["READ", "WRITE"]\` for generic)
+- **file**: Infrastructure or config file where this resource is defined (e.g., \`infra/storage.ts\`). NOT application code that calls it.
+- **line**: Line number if determinable
+- **authRequired**: Whether external access requires authentication
+- **riskLevel**: CRITICAL for publicly accessible storage with write access or sensitive data, HIGH for resources with broad IAM permissions, MEDIUM for internal resources, LOW for read-only public assets
+
+### Required workflow — NO MANIFESTS, NO BATCHING
+**You MUST call \`document_endpoint\` directly, one entry point at a time, the moment you identify it.** Do not build a JSON file or list of entry points to "process later," and do not write a script that emits \`document_endpoint\` calls. Those patterns hit per-message output-token limits and silently drop entries. The only correct loop is: identify entry point → call \`document_endpoint\` → identify next → call \`document_endpoint\` → ...
+
+When finished, call \`response\` with a summary of how many entry points you documented. The reported count must equal the number of successful \`document_endpoint\` calls you made.`;
+}
+async function runIncrementalWhiteboxAttackSurfaceWorkflow2(input) {
+  const {
+    codebasePath,
+    previousCommitSha,
+    currentCommitSha,
+    existingResult,
+    model,
+    session,
+    authConfig,
+    abortSignal,
+    eventBus,
+    attackSurfaceRegistry,
+    onStepFinish,
+    projectThreatModel,
+    seams: inputSeams
+  } = input;
+  const seams = inputSeams ?? inProcessSeams2();
+  const diffPath = join(session.rootPath, "diff-output.txt");
+  try {
+    const diff = execFileSync("git", ["diff", `${previousCommitSha}..${currentCommitSha}`], { cwd: codebasePath, maxBuffer: 50 * 1024 * 1024, encoding: "utf-8" });
+    writeFileSync(diffPath, diff, "utf-8");
+  } catch (error) {
+    log2.error("Failed to generate git diff, falling back to full recon", error instanceof Error ? error : undefined, { error: String(error) });
+    return runWhiteboxAttackSurfaceWorkflow2(input);
+  }
+  const assetsPath = join(session.rootPath, "assets");
+  mkdirSync(assetsPath, { recursive: true });
+  let preloadedCount = 0;
+  for (const app of existingResult.apps) {
+    const appDir = join(assetsPath, sanitizeName(app.name));
+    mkdirSync(appDir, { recursive: true });
+    writeFileSync(join(appDir, "app.json"), JSON.stringify(toAppMetadata(app), null, 2), "utf-8");
+    for (const ep of [...app.pages, ...app.apiEndpoints]) {
+      const isPage = app.pages.includes(ep);
+      const rawKey = `${app.name}__${ep.path}`.toLowerCase();
+      const hash = createHash("sha256").update(rawKey).digest("hex").slice(0, 8);
+      const sanitizedPath = sanitizeName(ep.path);
+      const filename = `asset_${sanitizedPath}_${hash}.json`;
+      const { riskScore: _staleScore, threatModel, ...epWithoutMeta } = ep;
+      const assetData = {
+        assetName: ep.path,
+        assetType: "endpoint",
+        appName: app.name,
+        description: ep.description ?? `${ep.method} ${ep.path}`,
+        details: {
+          url: ep.path,
+          method: isPage ? "PAGE" : ep.method,
+          file: ep.file,
+          line: ep.line,
+          handler: ep.handler,
+          authRequired: ep.authRequired
+        },
+        riskLevel: "MEDIUM",
+        pentestObjectives: epWithoutMeta.pentestObjectives ?? [],
+        ...threatModel ? { threatModel } : {},
+        discoveredAt: new Date().toISOString(),
+        sessionId: session.id,
+        target: ""
+      };
+      writeFileSync(join(appDir, filename), JSON.stringify(assetData, null, 2), "utf-8");
+      preloadedCount++;
+    }
+  }
+  log2.info(`Incremental recon: wrote ${preloadedCount} existing endpoint assets to ${assetsPath}`);
+  const IncrementalResultSchema = z.object({
+    repoType: z.string(),
+    packageManager: z.string(),
+    changedApps: z.array(z.string()).describe("Names of applications that were affected by the diff"),
+    addedEndpoints: z.number().describe("Count of new endpoints added"),
+    modifiedEndpoints: z.number().describe("Count of existing endpoints modified"),
+    removedEndpoints: z.number().describe("Count of endpoints removed"),
+    summary: z.string().describe("Brief summary of what changed")
+  });
+  const objective = buildIncrementalObjective(codebasePath, diffPath, assetsPath, existingResult, input.domains, input.environments);
+  const incrementalSubagentId = seams.ids.newSessionId("incremental-recon", 0);
+  const agent = new CodeAgent2({
+    codebasePath,
+    objective,
+    system: WHITEBOX_DISCOVERY_SYSTEM_PROMPT2,
+    model,
+    session,
+    authConfig,
+    attackSurfaceRegistry,
+    eventBus,
+    subagentId: incrementalSubagentId,
+    subagentName: "Incremental Recon",
+    onStepFinish: (event) => onStepFinish?.(event),
+    openAIReasoningEffort: input.openAIReasoningEffort,
+    enableThinking: input.enableThinking,
+    thinkingEffort: input.thinkingEffort,
+    responseSchema: IncrementalResultSchema,
+    projectThreatModel,
+    subagentSpawner: input.subagentSpawner,
+    ...input.hooks,
+    abortSignal
+  });
+  eventBus?.emit("subagent-spawn", {
+    subagentId: incrementalSubagentId,
+    name: "Incremental Recon",
+    input: { codebasePath }
+  });
+  let agentResult;
+  try {
+    agentResult = await agent.consume();
+    eventBus?.emit("subagent-complete", {
+      subagentId: incrementalSubagentId,
+      status: "completed"
+    });
+  } catch (e) {
+    eventBus?.emit("subagent-complete", {
+      subagentId: incrementalSubagentId,
+      status: "failed"
+    });
+    throw e;
+  }
+  log2.info(`Incremental agent finished: ${agentResult?.summary ?? "no summary"}`);
+  const { apps: parsedApps } = readAppsFromAssetsDirectory(assetsPath);
+  const existingEndpointMap = new Map;
+  for (const existingApp of existingResult.apps) {
+    for (const ep of [...existingApp.pages, ...existingApp.apiEndpoints]) {
+      existingEndpointMap.set(`${ep.method}:${ep.file}:${ep.path}`, ep);
+    }
+  }
+  function carryForwardRiskScore(ep) {
+    if (ep.riskScore)
+      return ep;
+    const key = `${ep.method}:${ep.file}:${ep.path}`;
+    const existing = existingEndpointMap.get(key);
+    return existing?.riskScore ? { ...ep, riskScore: existing.riskScore } : ep;
+  }
+  const apps = parsedApps.map((app) => ({
+    ...app,
+    pages: app.pages.map(carryForwardRiskScore),
+    apiEndpoints: app.apiEndpoints.map(carryForwardRiskScore)
+  }));
+  const totalPages = apps.reduce((sum, a) => sum + a.pages.length, 0);
+  const totalApiEndpoints = apps.reduce((sum, a) => sum + a.apiEndpoints.length, 0);
+  const totalPentestObjectives = apps.reduce((sum, a) => sum + [...a.pages, ...a.apiEndpoints].reduce((s, ep) => s + ep.pentestObjectives.length, 0), 0);
+  return {
+    repoType: existingResult.repoType,
+    packageManager: existingResult.packageManager,
+    apps,
+    summary: {
+      totalApps: apps.length,
+      totalPages,
+      totalApiEndpoints,
+      totalPentestObjectives
+    }
+  };
+}
+function buildIncrementalObjective(codebasePath, diffPath, assetsPath, existingResult, domains, environments) {
+  const appsSummary = existingResult.apps.map((app) => {
+    const epCount = app.pages.length + app.apiEndpoints.length;
+    return `  - **${app.name}** (${app.framework}) at \`${app.location}\` — ${epCount} endpoints`;
+  }).join(`
+`);
+  const domainSection = domains?.length ? `
+## Known Domains
+The following domains are associated with this project. When documenting new apps, set the \`domain\` field on \`document_app\` if you can determine which domain serves the app:
+${domains.map((d) => `- ${d}`).join(`
+`)}
+` : "";
+  const environmentsSection = environments?.length ? `
+## Target Environments
+This project is deployed to: ${environments.join(", ")}. When the diff introduces new dynamically-named resources (e.g. environment-prefixed S3 buckets, stage-scoped databases), create a **separate app entry per environment** using the environment name as a prefix (e.g. \`${environments[0]}-<resource>\`). Use environment-specific identifiers in domains and endpoints.
+` : "";
+  return `# Incremental Attack Surface Update
+
+## Context
+You are updating the attack surface map for a repository after a new commit. Rather than analyzing the entire codebase, you will analyze only the **changed files** and update the existing endpoint assets accordingly. Also check for any new cloud resources (S3 buckets, storage, CDN origins, etc.) introduced in the diff.
+
+## Codebase
+- **Path:** ${codebasePath}
+- **Diff file:** ${diffPath} (contains \`git diff\` output between the previous and current commit)
+- **Existing assets directory:** ${assetsPath}
+${domainSection}${environmentsSection}
+## Directory Structure
+The assets directory uses app-scoped folders:
+\`\`\`
+assets/
+  <app-name>/
+    app.json           — app metadata (name, framework, description, location)
+    asset_*.json       — one file per endpoint (written by document_endpoint)
+\`\`\`
+
+## Existing Applications
+${appsSummary}
+
+## Task
+
+### Step 1: Read and understand the diff
+Read the diff file at \`${diffPath}\`. If it's very large, read it in chunks. Identify which files were added, modified, or deleted.
+
+### Step 2: Determine impact on the attack surface
+For each changed file, determine if it affects any endpoints:
+- **New route/endpoint definitions** → use \`document_endpoint\` with the appropriate \`appName\`
+- **Modified route handlers** → read the existing asset file, then use \`execute_command\` to update it
+- **Deleted route files or endpoint definitions** → delete the corresponding asset file
+- **Non-route changes** (e.g. utility functions, configs, tests) → skip
+
+### Step 3: Update assets
+For new endpoints, use \`document_endpoint\` with:
+- \`appName\` set to the correct application name
+- \`routePath\` set to the HTTP route (e.g., \`/api/users\`) — this is NOT a file path
+- \`method\` as an array of ALL HTTP methods the path supports
+- \`file\` set to the source-code file (e.g., \`src/routes/users.ts\`) — this is NOT the route
+- \`line\`, \`handler\`, \`authRequired\` filled in
+
+For modified endpoints, update the existing JSON file via \`execute_command\`.
+For removed endpoints, delete the file via \`execute_command\`.
+
+**IMPORTANT: ONE entry per route path.** Do NOT create separate entries for different HTTP methods on the same path.
+
+**IMPORTANT: NO MANIFESTS, NO BATCHING.** Call \`document_endpoint\` directly, one new endpoint at a time, the moment you identify it. Do not build a JSON file or list of endpoints-to-document and process it later, and do not write a script that emits \`document_endpoint\` calls — that pattern hits output-token limits and silently drops endpoints.
+
+### Step 4: Report
+When finished, call the \`response\` tool with a summary of your changes.
+
+**IMPORTANT:** Be conservative. Only add/modify/remove endpoints that are clearly affected by the diff. Do not re-analyze the entire codebase.`;
+}
+var IncrementalReconResultSchema = z.object({
+  repoType: z.string(),
+  packageManager: z.string(),
+  changedApps: z.array(z.string()).describe("Names of applications that were affected by the diff"),
+  addedEndpoints: z.number().describe("Count of new endpoints added"),
+  modifiedEndpoints: z.number().describe("Count of existing endpoints modified"),
+  removedEndpoints: z.number().describe("Count of endpoints removed"),
+  summary: z.string().describe("Brief summary of what changed")
+});
+async function readIncrementalReconAssets(backends, assetsPath, existing, abortSignal) {
+  const fs = backends.fs;
+  const list = async (path) => {
+    abortSignal?.throwIfAborted();
+    const result = await fs.list(path);
+    if (!result.success)
+      throw new Error(`Incomplete recon asset listing: ${path}`);
+    if (!result.truncated)
+      return result.files;
+    const files = [];
+    let total;
+    for (let offset = 0;; ) {
+      abortSignal?.throwIfAborted();
+      const quote = (value) => `'${value.replaceAll("'", "'\\''")}'`;
+      const output = await collectCommand(backends.command.run(`python3 -c ${quote(RECON_ARTIFACT_PAGE_SCRIPT)} ${quote(assetsPath)} ${quote(path)} ${offset}`, { timeoutSeconds: 30, abortSignal }));
+      if (output.exitCode !== 0 || output.timedOut || output.stdoutTruncated)
+        throw new Error(`Recon artifact enumeration failed: ${path}`);
+      const page = z.object({
+        files: z.array(z.string()).max(64),
+        total: z.number().int().min(0).max(1e5),
+        next: z.number().int().min(1).nullable()
+      }).parse(JSON.parse(output.stdout));
+      total ??= page.total;
+      if (page.total !== total || page.next !== null && page.next !== offset + page.files.length || page.next !== null && (page.files.length === 0 || page.next >= total))
+        throw new Error("Recon artifact enumeration did not advance consistently");
+      files.push(...page.files);
+      if (page.next === null) {
+        if (files.length !== total || new Set(files).size !== total)
+          throw new Error("Incomplete recon artifact pagination");
+        return files;
+      }
+      offset = page.next;
+    }
+  };
+  const read = async (path) => {
+    abortSignal?.throwIfAborted();
+    const result = await fs.readRaw(path);
+    if (!result.success)
+      throw new Error(`Recon artifact read failed: ${path}`);
+    return JSON.parse(result.content);
+  };
+  const apps = [];
+  for (const directory of await list(assetsPath)) {
+    if (!directory.endsWith("/"))
+      continue;
+    if (directory === "../" || directory === "./" || directory.slice(0, -1).includes("/"))
+      throw new Error("Invalid recon artifact directory");
+    const appPath = join(assetsPath, directory);
+    const metadata = AppInfoSchema2.parse(await read(join(appPath, "app.json")));
+    const previousApp = existing.apps.find((app) => app.name === metadata.name);
+    const app = {
+      ...previousApp,
+      ...metadata,
+      pages: [],
+      apiEndpoints: []
+    };
+    for (const file of await list(appPath)) {
+      if (file === "app.json" || !file.endsWith(".json"))
+        continue;
+      if (file.includes("/") || file === "..")
+        throw new Error("Invalid recon artifact filename");
+      const raw = await read(join(appPath, file));
+      const record = z.object({
+        method: z.union([z.string(), z.array(z.string())]),
+        routePath: z.string()
+      }).passthrough().parse(raw);
+      const endpoint = assetRecordToEndpoint(record);
+      if (!endpoint)
+        throw new Error(`Invalid recon endpoint artifact: ${file}`);
+      const previous = previousApp && [...previousApp.pages, ...previousApp.apiEndpoints].find((ep) => ep.method === endpoint.method && ep.file === endpoint.file && ep.path === endpoint.path);
+      const restored = {
+        ...previous,
+        ...endpoint,
+        ...endpoint.riskScore ? {} : previous?.riskScore ? { riskScore: previous.riskScore } : {}
+      };
+      (isPageEndpoint(record) ? app.pages : app.apiEndpoints).push(restored);
+    }
+    apps.push(app);
+  }
+  return {
+    ...existing,
+    apps,
+    summary: {
+      totalApps: apps.length,
+      totalPages: apps.reduce((sum, app) => sum + app.pages.length, 0),
+      totalApiEndpoints: apps.reduce((sum, app) => sum + app.apiEndpoints.length, 0),
+      totalPentestObjectives: apps.reduce((sum, app) => sum + [...app.pages, ...app.apiEndpoints].reduce((count, ep) => count + ep.pentestObjectives.length, 0), 0)
+    }
+  };
+}
+var RECON_ARTIFACT_PAGE_SCRIPT = `import os,sys,json,itertools
+base=os.path.realpath(sys.argv[1]); directory=os.path.realpath(sys.argv[2]); offset=int(sys.argv[3])
+if os.path.commonpath([base,directory]) != base: raise ValueError("Artifact directory escaped root")
+with os.scandir(directory) as scan:
+ entries=list(itertools.islice(scan,100001))
+if len(entries)>100000: raise ValueError("Artifact inventory exceeds limit")
+if any(entry.is_symlink() for entry in entries): raise ValueError("Artifact links are not supported")
+files=sorted(entry.name+("/" if entry.is_dir() else "") for entry in entries)
+end=min(len(files),offset+64)
+print(json.dumps({"files":files[offset:end],"total":len(files),"next":end if end<len(files) else None}))`;
+
+export { runWhiteboxAttackSurfaceApp2, runWhiteboxAttackSurfaceWorkflow2, runIncrementalWhiteboxAttackSurfaceWorkflow2, exports_whiteboxAttackSurface };