diff --git a/apps/worker/src/ai/pi-executor.ts b/apps/worker/src/ai/pi-executor.ts
index 66dc06e..b62758b 100644
--- a/apps/worker/src/ai/pi-executor.ts
+++ b/apps/worker/src/ai/pi-executor.ts
@@ -173,7 +173,7 @@ function extractAssistantText(message: AgentMessage): string {
 }
 
 /**
- * Classify error-bearing text into a PentestError, mirroring the prior SDK error
+ * Classify error-bearing text into a PentestError, mirroring the prior provider error
  * handling. Spending-cap / billing text is retryable (Temporal backs off and
  * recovers when the cap resets); session limit is permanent.
  */
diff --git a/apps/worker/src/mcp-server/recon-collector.ts b/apps/worker/src/mcp-server/recon-collector.ts
index 81c16ac..0662673 100644
--- a/apps/worker/src/mcp-server/recon-collector.ts
+++ b/apps/worker/src/mcp-server/recon-collector.ts
@@ -16,7 +16,7 @@
  * A skipped tool renders a "not provided" placeholder in that section rather
  * than failing the activity. getCallStatus() exposes the per-run call pattern
  * for logging. Each schema's field-level descriptions carry the section
- * guidance, so the SDK injects it into the agent's tool catalog.
+ * guidance, so pi injects it into the agent's tool catalog.
  */
 
 import { defineTool, type ToolDefinition } from '@earendil-works/pi-coding-agent';
diff --git a/apps/worker/src/services/agent-execution.ts b/apps/worker/src/services/agent-execution.ts
index f0c5874..1ad85b6 100644
--- a/apps/worker/src/services/agent-execution.ts
+++ b/apps/worker/src/services/agent-execution.ts
@@ -312,7 +312,7 @@ export class AgentExecutionService {
   static toMetrics(endResult: AgentEndResult, result: PiPromptResult): AgentMetrics {
     return {
       durationMs: endResult.duration_ms,
-      inputTokens: null, // Not currently exposed by SDK wrapper
+      inputTokens: null, // Not currently exposed by the pi executor
       outputTokens: null,
       costUsd: endResult.cost_usd,
       numTurns: result.turns ?? null,
diff --git a/apps/worker/src/services/error-handling.ts b/apps/worker/src/services/error-handling.ts
index 99fb394..e6e1b0d 100644
--- a/apps/worker/src/services/error-handling.ts
+++ b/apps/worker/src/services/error-handling.ts
@@ -160,7 +160,7 @@ function classifyByErrorCode(code: ErrorCode, retryableFromError: boolean): { ty
  *
  * Classification priority:
  * 1. If error is PentestError with ErrorCode, classify by code (reliable)
- * 2. Fall through to string matching for external errors (SDK, network, etc.)
+ * 2. Fall through to string matching for external errors (provider, network, etc.)
  */
 export function classifyErrorForTemporal(error: unknown): { type: string; retryable: boolean } {
   // === CODE-BASED CLASSIFICATION (Preferred for internal errors) ===
diff --git a/apps/worker/src/services/findings-renderer.ts b/apps/worker/src/services/findings-renderer.ts
index 6dfb5cc..f41e5f9 100644
--- a/apps/worker/src/services/findings-renderer.ts
+++ b/apps/worker/src/services/findings-renderer.ts
@@ -9,7 +9,7 @@
  *
  * Used when exploit=false: the exploit agents didn't run, so there is no
  * `*_exploitation_evidence.md` to concatenate into the report. This module
- * reads each `*_exploitation_queue.json` (already SDK-validated against the
+ * reads each `*_exploitation_queue.json` (already validated by the submit tool against the
  * schemas in ../ai/queue-schemas.ts) and writes a `*_findings.md` per class
  * in the canonical body shape that report-executive.txt's cleanup expects.
  *
diff --git a/apps/worker/src/services/preflight.ts b/apps/worker/src/services/preflight.ts
index af3a2c4..c95925f 100644
--- a/apps/worker/src/services/preflight.ts
+++ b/apps/worker/src/services/preflight.ts
@@ -247,7 +247,7 @@ async function validateCodePathsExist(
 
 // === Credential Validation ===
 
-/** Map SDK error type to a human-readable preflight PentestError. */
+/** Map provider error text to a human-readable preflight PentestError. */
 /** Classify a provider error message (thrown or from a failed turn) into a PentestError. */
 function classifyCredentialError(text: string, authType: string): Result<void, PentestError> {
   const lower = text.toLowerCase();
@@ -357,7 +357,7 @@ async function validateCredentials(
   providerConfig?: import('../types/config.js').ProviderConfig,
 ): Promise<Result<void, PentestError>> {
   // 0. If providerConfig is present, credentials are managed by the caller.
-  //    The executor will map providerConfig directly to sdkEnv — no process.env needed.
+  //    The executor/provider layer owns providerConfig resolution — no env preflight needed.
   if (providerConfig) {
     logger.info(
       `Provider config present (type: ${providerConfig.providerType || 'anthropic_api'}) — skipping env-based credential validation`,
@@ -365,7 +365,7 @@ async function validateCredentials(
     return ok(undefined);
   }
 
-  // 0b. If apiKey provided via config, set it in env for SDK validation
+  // 0b. If apiKey provided via config, set it in env for pi validation
   //     This avoids requiring process.env.ANTHROPIC_API_KEY when key is threaded via input
   if (apiKey) {
     process.env.ANTHROPIC_API_KEY = apiKey;
@@ -594,7 +594,7 @@ export async function runPreflightChecks(
     }
   }
 
-  // 4. Credential check (cheap — 1 SDK round-trip, skipped when providerConfig present)
+  // 4. Credential check (cheap — 1 pi round-trip, skipped when providerConfig present)
   const credResult = await validateCredentials(logger, apiKey, providerConfig);
   if (!credResult.ok) {
     return credResult;
diff --git a/apps/worker/src/session-manager.ts b/apps/worker/src/session-manager.ts
index 7bf812e..5f31ad5 100644
--- a/apps/worker/src/session-manager.ts
+++ b/apps/worker/src/session-manager.ts
@@ -130,7 +130,7 @@ export const AGENT_PHASE_MAP: Readonly<Record<AgentName, PhaseName>> = Object.fr
 // Post-MCP-migration, the analysis_deliverable.md is rendered by the activity
 // wrapper after validateAgentOutput runs, so the previous "both files exist"
 // check would race the renderer. The validator only checks the queue.json —
-// that file is written by the SDK structured-output path in agent-execution.ts
+// that file is written by the submit-tool path in agent-execution.ts
 // before this validator runs. The downstream checkExploitationQueue still
 // renders the .md.
 function createVulnValidator(vulnType: VulnType): AgentValidator {
diff --git a/apps/worker/src/temporal/activities.ts b/apps/worker/src/temporal/activities.ts
index 510c366..ae7e193 100644
--- a/apps/worker/src/temporal/activities.ts
+++ b/apps/worker/src/temporal/activities.ts
@@ -462,7 +462,7 @@ export async function runReportAgent(input: ActivityInput): Promise<AgentMetrics
  * 3. Credential validation (API key, OAuth, or Bedrock)
  * 4. Target URL reachable from the container
  *
- * NOT using runAgentActivity — preflight doesn't run an agent via the SDK.
+ * NOT using runAgentActivity — preflight doesn't run a full analysis agent.
  */
 export async function runPreflightValidation(input: ActivityInput): Promise<void> {
   const startTime = Date.now();
diff --git a/apps/worker/src/temporal/workflows.ts b/apps/worker/src/temporal/workflows.ts
index 5d4c03e..53039ff 100644
--- a/apps/worker/src/temporal/workflows.ts
+++ b/apps/worker/src/temporal/workflows.ts
@@ -92,7 +92,7 @@ const TESTING_RETRY = {
 // Activity proxy with production retry configuration (default)
 const acts = proxyActivities<typeof activities>({
   startToCloseTimeout: '2 hours',
-  heartbeatTimeout: '60 minutes', // Extended for sub-agent execution (SDK blocks event loop during Task tool calls)
+  heartbeatTimeout: '60 minutes', // Extended for nested pi task execution
   retry: PRODUCTION_RETRY,
 });
 
@@ -135,7 +135,7 @@ const preflightActs = proxyActivities<typeof activities>({
   retry: PREFLIGHT_RETRY,
 });
 
-// Credential rejection is not retryable; transient SDK errors get 3 attempts.
+// Credential rejection is not retryable; transient provider errors get 3 attempts.
 const AUTH_VALIDATION_RETRY = {
   initialInterval: '10 seconds',
   maximumInterval: '1 minute',
@@ -452,7 +452,7 @@ export async function pentestPipeline(input: PipelineInput): Promise<PipelineSta
     // === Initialize Deliverables Git ===
     await a.initDeliverableGit(activityInput);
 
-    // === Sync SDK deny rules ===
+    // === Sync code_path deny rules ===
     await a.syncCodePathDenyRules(activityInput);
 
     log.info(`Run scope: vuln_classes=[${selectedVulnClasses.join(', ')}] exploit=${exploit}`);
diff --git a/apps/worker/src/types/config.ts b/apps/worker/src/types/config.ts
index 8c00616..edb5e4c 100644
--- a/apps/worker/src/types/config.ts
+++ b/apps/worker/src/types/config.ts
@@ -125,6 +125,6 @@ export interface ContainerConfig {
   readonly apiKey?: string;
   /** Prompt directory override — when set, prompt manager loads from this path */
   readonly promptDir?: string;
-  /** LLM provider configuration — when set, executor maps to SDK env vars directly */
+  /** LLM provider configuration for the pi executor */
   readonly providerConfig?: ProviderConfig;
 }
diff --git a/apps/worker/src/utils/billing-detection.ts b/apps/worker/src/utils/billing-detection.ts
index ea6c544..7d41354 100644
--- a/apps/worker/src/utils/billing-detection.ts
+++ b/apps/worker/src/utils/billing-detection.ts
@@ -8,7 +8,7 @@
  * Consolidated billing/spending cap detection utilities.
  *
  * Anthropic's spending cap behavior is inconsistent:
- * - Sometimes a proper SDK error (billing_error)
+ * - Sometimes a proper provider error (billing_error)
  * - Sometimes the agent responds with text about the cap
  * - Sometimes partial billing before cutoff
  *
@@ -17,8 +17,8 @@
  */
 
 /**
- * Text patterns for SDK output sniffing (what the agent says).
- * Used by message-handlers.ts and the behavioral heuristic.
+ * Text patterns for provider/harness output sniffing (what the agent says).
+ * Used by the pi event stream and the behavioral heuristic.
  */
 export const BILLING_TEXT_PATTERNS = [
   'spending cap',
@@ -48,7 +48,7 @@ export const BILLING_API_PATTERNS = [
 
 /**
  * Checks if text matches any billing text pattern.
- * Used for sniffing SDK output content for spending cap messages.
+ * Used for sniffing agent output content for spending cap messages.
  */
 export function matchesBillingTextPattern(text: string): boolean {
   const lowerText = text.toLowerCase();