specvector 0.1.9 → 0.3.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specvector",
-  "version": "0.1.9",
+  "version": "0.3.3",
   "description": "Context-aware AI code review using Model Context Protocol (MCP)",
   "type": "module",
   "main": "src/index.ts",
@@ -44,9 +44,7 @@
   "engines": {
     "bun": ">=1.0.0"
   },
-  "dependencies": {
-    "@larryhudson/linear-mcp-server": "0.1.4"
-  },
+  "dependencies": {},
   "devDependencies": {
     "@types/bun": "latest"
   },

package/src/agent/loop.ts

@@ -17,6 +17,7 @@
 import { ok, err } from "../types/result";
 import type { Message, ToolCall } from "../types/llm";
 import type { LLMProvider, LLMError } from "../llm/provider";
+import { withRetry } from "../llm/provider";
 import type {
   Tool,
   AgentConfig,
@@ -70,12 +71,15 @@ export class AgentLoop {
         return err(AgentErrors.timeout());
       }
 
-      // Get LLM response
-      const llmResult = await this.provider.chat(
-        messages,
-        {
-          tools: Array.from(this.tools.values()).map(toolToLLMTool),
-        }
+      // Get LLM response with retry on transient errors
+      const llmResult = await withRetry(
+        () => this.provider.chat(
+          messages,
+          {
+            tools: Array.from(this.tools.values()).map(toolToLLMTool),
+          }
+        ),
+        { maxRetries: 1, delayMs: 2000 }
       );
 
       if (!llmResult.ok) {

package/src/config/index.ts

@@ -280,19 +280,19 @@ export function getStrictnessModifier(strictness: SpecVectorConfig["strictness"]
   switch (strictness) {
     case "strict":
       return `Be VERY strict. Flag any potential issue, no matter how minor. 
-Focus on: security vulnerabilities, performance issues, error handling, edge cases.
+Focus on: security vulnerabilities, logic errors, boundary conditions, data flow issues, performance problems, error handling, edge cases.
 Do not approve code that could be improved.`;
     
     case "lenient":
       return `Be lenient and focus only on critical issues.
-Only flag: bugs that would cause runtime errors, security vulnerabilities, obvious mistakes.
-Skip: style issues, minor improvements, suggestions.
+Only flag: bugs that would cause runtime errors, logic errors causing crashes or data corruption, security vulnerabilities, obvious mistakes.
+Skip: style issues, minor improvements, suggestions, theoretical problems.
 Approve unless there are blocking issues.`;
     
     case "normal":
     default:
       return `Use balanced judgement. Flag important issues but don't be nitpicky.
-Focus on: bugs, security, performance, maintainability.
-Skip: purely stylistic preferences.`;
+Focus on: logic errors that would cause real bugs in production, security, performance, maintainability.
+Skip: purely stylistic preferences, theoretical issues you haven't verified.`;
   }
 }

package/src/context/linear.ts

@@ -1,9 +1,10 @@
 /**
  * Linear Context Provider - Fetches ticket context for reviews.
  *
- * Extracts ticket ID from branch name/PR and fetches details via Linear GraphQL API.
+ * Extracts ticket ID from branch name/PR and fetches details via MCP.
  */
 
+import { createMCPClient } from "../mcp";
 import type { Result } from "../types/result";
 import { ok, err } from "../types/result";
 
@@ -12,12 +13,12 @@ import { ok, err } from "../types/result";
 // ============================================================================
 
 export interface LinearTicket {
-  identifier?: string;
-  title?: string;
-  description?: string;
-  state?: { name?: string };
-  priority?: number;
-  labels?: { nodes?: Array<{ name?: string }> };
+  id: string;
+  title: string;
+  description: string;
+  state: string;
+  priority: number;
+  labels: string[];
 }
 
 export interface LinearContextError {
@@ -72,14 +73,21 @@ export function extractTicketId(
 // Linear Context Fetching
 // ============================================================================
 
+/** Extended ticket data from Linear MCP */
+export interface LinearTicketData {
+  context: string;
+  title?: string;
+  url?: string;
+}
+
 /**
  * Fetch Linear ticket context for a review.
  *
- * Uses Linear's GraphQL API directly - simpler and more reliable than MCP.
+ * Returns formatted context string and extracted metadata.
  */
 export async function fetchLinearContext(
   ticketId: string
-): Promise<Result<string, LinearContextError>> {
+): Promise<Result<LinearTicketData, LinearContextError>> {
   // Check for API token
   const apiToken = process.env.LINEAR_API_TOKEN;
   if (!apiToken) {
@@ -89,85 +97,83 @@ export async function fetchLinearContext(
     });
   }
 
-  try {
-    // Use Linear GraphQL API directly
-    const response = await fetch("https://api.linear.app/graphql", {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        Authorization: apiToken,
-      },
-      body: JSON.stringify({
-        query: `
-          query GetIssue($id: String!) {
-            issue(id: $id) {
-              identifier
-              title
-              description
-              state { name }
-              priority
-              labels { nodes { name } }
-            }
-          }
-        `,
-        variables: { id: ticketId },
-      }),
+  // Create MCP client
+  const clientResult = await createMCPClient({
+    name: "linear",
+    command: "npx",
+    args: ["linear-mcp-server"],
+    env: {
+      LINEAR_API_KEY: apiToken,
+    },
+    timeout: 30000,
+  });
+
+  if (!clientResult.ok) {
+    return err({
+      code: "CONNECTION_FAILED",
+      message: clientResult.error.message,
     });
+  }
+
+  const client = clientResult.value;
 
-    if (!response.ok) {
+  try {
+    // Fetch issue details using Linear MCP
+    const ticketResult = await client.callTool("get_issue", { issue_id: ticketId });
+
+    if (!ticketResult.ok) {
       return err({
         code: "FETCH_FAILED",
-        message: `Linear API error: ${response.status}`,
+        message: ticketResult.error.message,
       });
     }
 
-    const data = await response.json() as { data?: { issue?: LinearTicket | null }; errors?: Array<{ message: string }> };
+    // Parse the response
+    const content = ticketResult.value.content;
+    const textContent = content.find(c => c.type === "text");
     
-    if (data.errors?.length) {
+    if (!textContent?.text) {
       return err({
         code: "FETCH_FAILED",
-        message: data.errors[0]?.message ?? "GraphQL error",
+        message: "No ticket data returned",
       });
     }
 
-    const issue = data.data?.issue;
-    if (!issue) {
-      return err({
-        code: "FETCH_FAILED",
-        message: `Issue ${ticketId} not found`,
-      });
-    }
+    const ticketText = textContent.text;
+    
+    // Extract URL from MCP response if present (Linear API includes url field)
+    // Pattern matches: "url": "https://linear.app/..." or URL: https://linear.app/...
+    const urlMatch = ticketText.match(/"?url"?:\s*"?(https:\/\/linear\.app\/[^"\s]+)"?/i);
+    const extractedUrl = urlMatch?.[1];
+    
+    // Extract title from MCP response if present
+    const titleMatch = ticketText.match(/"?title"?:\s*"([^"]+)"/i);
+    const extractedTitle = titleMatch?.[1];
 
     // Format the context for the review prompt
-    const contextBlock = formatLinearContext(ticketId, issue);
-    return ok(contextBlock);
-
-  } catch (error) {
-    return err({
-      code: "FETCH_FAILED",
-      message: error instanceof Error ? error.message : "Unknown error",
+    const contextBlock = formatLinearContext(ticketId, ticketText);
+    
+    return ok({
+      context: contextBlock,
+      title: extractedTitle,
+      url: extractedUrl,
     });
+
+  } finally {
+    await client.close();
   }
 }
 
 /**
- * Format Linear issue data as context for review prompt.
+ * Format Linear ticket data as context for review prompt.
  */
-function formatLinearContext(ticketId: string, issue: { title?: string; description?: string; state?: { name?: string }; priority?: number; labels?: { nodes?: Array<{ name?: string }> } }): string {
-  const labels = issue.labels?.nodes?.map(l => l.name).filter(Boolean).join(", ") || "none";
-  const priority = issue.priority ?? 0;
-  const priorityLabels = ["", "Urgent", "High", "Medium", "Low", "No Priority"];
-
+function formatLinearContext(ticketId: string, ticketData: string): string {
   return `
 ## Linear Ticket Context: ${ticketId}
 
-**Title:** ${issue.title ?? "Untitled"}
-**Status:** ${issue.state?.name ?? "Unknown"}
-**Priority:** ${priorityLabels[priority] ?? "Unknown"}
-**Labels:** ${labels}
+The following is the context from the linked Linear ticket. Use this to understand the business requirements and acceptance criteria for this PR.
 
-### Description
-${issue.description ?? "No description provided."}
+${ticketData}
 
 ---
 When reviewing, check that the PR changes align with the ticket requirements above.
@@ -184,7 +190,7 @@ export async function getLinearContextForReview(
   branchName?: string,
   prTitle?: string,
   prBody?: string
-): Promise<{ context: string | null; ticketId: string | null; warning?: string }> {
+): Promise<{ context: string | null; ticketId: string | null; ticketTitle?: string; ticketUrl?: string; warning?: string }> {
   // Extract ticket ID
   const ticketId = extractTicketId(branchName, prTitle, prBody);
 
@@ -212,8 +218,14 @@ export async function getLinearContextForReview(
     };
   }
 
+  const { context, title, url } = result.value;
+  
   return {
-    context: result.value,
+    context,
     ticketId,
+    // Use extracted title from MCP if available, fallback to generic
+    ticketTitle: title ?? `Linear Ticket ${ticketId}`,
+    // Use extracted URL from MCP if available (no fallback - better to have no link than broken link)
+    ticketUrl: url,
   };
 }

package/src/index.ts

@@ -9,6 +9,7 @@ import { postPRComment } from "./github/comment";
 import { parseDiff, getDiffSummary } from "./review/diff-parser";
 import { formatReviewComment, formatReviewSummary } from "./review/formatter";
 import { runReview } from "./review/engine";
+import { redactError } from "./utils/redact";
 
 const VERSION = "0.1.0";
 
@@ -132,7 +133,6 @@ async function handleReview(args: string[]): Promise<void> {
     displayAndPostReview(mockReview, prNumber, dryRun);
   } else {
     console.log("🤖 Running AI review...");
-    console.log("   (this may take 15-30 seconds)");
     console.log("");
 
     // Get branch name for Linear context
@@ -242,6 +242,6 @@ function generateMockReview(filesReviewed: number): import("./types/review").Rev
 
 // Run the CLI
 main().catch((error) => {
-  console.error("Fatal error:", error);
+  console.error("Fatal error:", redactError(error));
   process.exit(1);
 });

package/src/llm/index.ts

@@ -33,8 +33,8 @@ export type {
 } from "../types/llm";
 
 // Re-export provider interface and errors
-export type { LLMProvider, LLMError, LLMErrorCode } from "./provider";
-export { LLMErrors, isRetryableError, createLLMError } from "./provider";
+export type { LLMProvider, LLMError, LLMErrorCode, RetryConfig } from "./provider";
+export { LLMErrors, isRetryableError, createLLMError, withRetry } from "./provider";
 
 // Re-export factory
 export {

package/src/llm/provider.ts

@@ -131,3 +131,70 @@ export const LLMErrors = {
       retryable: false,
     }),
 };
+
+/**
+ * Retry configuration for LLM calls.
+ */
+export interface RetryConfig {
+  /** Maximum number of retries (default: 1) */
+  maxRetries?: number;
+  /** Delay between retries in ms (default: 2000) */
+  delayMs?: number;
+  /** Whether to log retry attempts (default: true) */
+  logRetries?: boolean;
+}
+
+/**
+ * Wrap an async function with retry logic for transient errors.
+ * 
+ * @param fn - Async function returning Result<T, LLMError>
+ * @param config - Retry configuration
+ * @returns Result with success value or final error
+ */
+export async function withRetry<T>(
+  fn: () => Promise<Result<T, LLMError>>,
+  config: RetryConfig = {}
+): Promise<Result<T, LLMError>> {
+  const maxRetries = config.maxRetries ?? 1;
+  const delayMs = config.delayMs ?? 2000;
+  const logRetries = config.logRetries ?? true;
+
+  let lastError: LLMError | undefined;
+  
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    const result = await fn();
+    
+    if (result.ok) {
+      return result;
+    }
+    
+    lastError = result.error;
+    
+    // Check if we should retry
+    if (attempt < maxRetries && isRetryableError(result.error)) {
+      const retryDelay = result.error.retryAfterMs ?? delayMs;
+      
+      if (logRetries) {
+        console.warn(
+          `⚠️  LLM call failed (${result.error.code}), retrying in ${retryDelay}ms... (${attempt + 1}/${maxRetries})`
+        );
+      }
+      
+      await sleep(retryDelay);
+      continue;
+    }
+    
+    // Non-retryable error or max retries reached
+    return result;
+  }
+  
+  // Should not reach here, but return last error if we do
+  return { ok: false, error: lastError! };
+}
+
+/**
+ * Sleep for a given number of milliseconds.
+ */
+function sleep(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}

package/src/mcp/mcp-client.ts

@@ -17,6 +17,7 @@ import type {
   MCPToolsListResult,
   MCPToolCallResult,
 } from "./types";
+import { redactSecrets, buildSafeEnv } from "../utils/redact";
 
 // ============================================================================
 // Constants
@@ -73,7 +74,7 @@ export async function createMCPClient(
   let proc: Subprocess;
   try {
     proc = spawn([config.command, ...config.args], {
-      env: { ...process.env, ...config.env },
+      env: buildSafeEnv(config.env as Record<string, string> | undefined),
       stdin: "pipe",
       stdout: "pipe",
       stderr: "pipe",
@@ -351,7 +352,7 @@ function startReadingStderr(state: MCPClientState): void {
         const text = decoder.decode(value, { stream: true });
         // Log stderr for debugging (could be made configurable)
         if (text.trim()) {
-          console.error(`[MCP:${state.config.name}] ${text.trim()}`);
+          console.error(`[MCP:${state.config.name}] ${redactSecrets(text.trim())}`);
         }
       }
     } catch {

package/src/review/engine.ts

@@ -16,7 +16,7 @@ import { createListDirTool } from "../agent/tools/list-dir";
 import { createOutlineTool } from "../agent/tools/outline";
 import { createFindSymbolTool } from "../agent/tools/find-symbol";
 import { calculateStats, determineRecommendation } from "../types/review";
-import type { ReviewResult, ReviewFinding, Severity } from "../types/review";
+import type { ReviewResult, ReviewFinding, Severity, ContextSource } from "../types/review";
 import type { Result } from "../types/result";
 import { ok, err } from "../types/result";
 import { loadConfig, getStrictnessModifier } from "../config";
@@ -100,6 +100,9 @@ export async function runReview(
   const strictnessGuidance = getStrictnessModifier(strictness);
   let systemPrompt = REVIEW_SYSTEM_PROMPT + `\n\n## Strictness Setting: ${strictness.toUpperCase()}\n${strictnessGuidance}`;
 
+  // Track context sources for citation
+  const contextSources: ContextSource[] = [];
+
   // Fetch Linear context if available
   const linearResult = await getLinearContextForReview(
     config.branchName,
@@ -110,6 +113,16 @@ export async function runReview(
   if (linearResult.context) {
     systemPrompt = linearResult.context + "\n\n" + systemPrompt;
     console.log(`📎 Loaded Linear context for ticket: ${linearResult.ticketId}`);
+    
+    // Track Linear as a context source (only if we have a valid ticket ID)
+    if (linearResult.ticketId) {
+      contextSources.push({
+        type: "linear",
+        id: linearResult.ticketId,
+        title: linearResult.ticketTitle,
+        url: linearResult.ticketUrl,
+      });
+    }
   } else if (linearResult.warning) {
     console.warn(`⚠️  ${linearResult.warning}`);
   }
@@ -119,12 +132,21 @@ export async function runReview(
   if (adrResult) {
     systemPrompt = adrResult.formatted + "\n\n" + systemPrompt;
     console.log(`📚 Loaded ${adrResult.context.count} ADR files from ${adrResult.context.path}`);
+    
+    // Track each ADR file as a context source
+    for (const adrFile of adrResult.context.files) {
+      contextSources.push({
+        type: "adr",
+        id: adrFile.name,
+        title: adrFile.name.replace(".md", ""),
+      });
+    }
   }
 
   // Create agent
   const agent = createAgentLoop(providerResult.value, tools, {
     maxIterations: config.maxIterations || fileConfig.maxIterations || 15,
-    timeoutMs: 3 * 60 * 1000, // 3 minutes
+    timeoutMs: 15 * 60 * 1000, // 15 minutes for larger PRs with slower models
     systemPrompt,
   });
 
@@ -142,7 +164,7 @@ export async function runReview(
   }
 
   // Parse the response into structured findings
-  const reviewResult = parseReviewResponse(agentResult.value, diffSummary);
+  const reviewResult = parseReviewResponse(agentResult.value, diffSummary, contextSources);
 
   return ok(reviewResult);
 }
@@ -150,7 +172,7 @@ export async function runReview(
 /**
  * System prompt for the code review agent.
  */
-const REVIEW_SYSTEM_PROMPT = `You are a pragmatic code reviewer. Your job is to catch REAL problems, not nitpick.
+export const REVIEW_SYSTEM_PROMPT = `You are a pragmatic code reviewer. Your job is to catch REAL problems, not nitpick.
 
 ## Tools Available
 - read_file: Read source files to understand context
@@ -159,21 +181,43 @@ const REVIEW_SYSTEM_PROMPT = `You are a pragmatic code reviewer. Your job is to
 - get_outline: Get functions/classes in a file (fast overview)
 - find_symbol: Find where a function or class is defined
 
+## Tool Use Strategy
+Before flagging any issue, you MUST verify your understanding:
+1. **Read the full file** for any function being changed — don't judge from diff alone
+2. **Use find_symbol** to trace how changed functions are called by other code
+3. **Use grep** to find other usages of modified functions or variables
+4. **Only flag an issue if you have verified it** by reading the surrounding context
+
 ## What to Look For (in priority order)
 1. **CRITICAL**: Security vulnerabilities, data loss, crashes
 2. **HIGH**: Bugs that WILL break functionality in production
 3. **MEDIUM**: Significant code quality issues (not style nits)
 
+## Business Logic Patterns to Detect
+Focus on real logic errors that cause incorrect behavior:
+- **Off-by-one errors**: Wrong boundary conditions, < vs <=, array index issues
+- **Null/undefined handling**: Missing null checks on values that can be null
+- **Race conditions**: Shared state without synchronization, async ordering bugs
+- **Incorrect boolean logic**: Inverted conditions, wrong operator (AND vs OR)
+- **Missing error paths**: Happy-path-only code that ignores failure cases in data flows
+- **Wrong operator**: Using = instead of ==, + instead of -, incorrect comparisons
+- **State management bugs**: Mutating shared state, stale closures, incorrect resets
+- **Type coercion issues**: Implicit conversions causing unexpected behavior
+
 ## What NOT to Flag
 - Style preferences or "I would do it differently"
 - Theoretical performance issues without evidence
 - Missing edge case tests for working code
 - "Could be refactored" suggestions
 - Code that works but isn't perfect
+- Naming convention preferences
+- Comment formatting or missing comments
+- Import ordering or grouping
 
 ## Key Principle
 Most PRs should have 0-2 findings. If you're finding 5+ issues, you're being too picky.
 Only flag issues you'd actually block a PR for in a real code review.
+Verify every finding with tool use before reporting it.
 
 ## Response Format
 SUMMARY: [1-2 sentences - is this code ready to merge?]
@@ -206,15 +250,15 @@ ${diff.length > 15000 ? "\n(diff truncated, use tools to read full files if need
 
 ## Instructions
 1. First, understand what the changes are doing
-2. Use tools to explore related code if needed (find usages, read implementations)
-3. Identify any issues with the changes
+2. Use tools to explore related code — read full files, trace call chains, check usages
+3. For each potential issue, verify it by reading surrounding context before flagging
 4. Provide your review in the specified format`;
 }
 
 /**
  * Parse the agent's response into structured findings.
  */
-function parseReviewResponse(response: string, diffSummary: string): ReviewResult {
+export function parseReviewResponse(response: string, diffSummary: string, contextSources: ContextSource[] = []): ReviewResult {
   const findings: ReviewFinding[] = [];
   
   // Extract summary
@@ -270,5 +314,6 @@ function parseReviewResponse(response: string, diffSummary: string): ReviewResul
     recommendation,
     stats,
     filesReviewed: parseInt(filesReviewed, 10) || 0,
+    contextSources: contextSources.length > 0 ? contextSources : undefined,
   };
 }

package/src/review/formatter.ts

@@ -3,7 +3,7 @@
  * Converts ReviewResult into markdown for PR comments.
  */
 
-import type { ReviewFinding, ReviewResult, Severity } from "../types/review";
+import type { ReviewFinding, ReviewResult, Severity, ContextSource } from "../types/review";
 
 /**
  * Severity emoji indicators.
@@ -60,6 +60,14 @@ export function formatReviewComment(result: ReviewResult): string {
   lines.push(result.summary);
   lines.push("");
 
+  // Context Used section (if any context was used)
+  if (result.contextSources && result.contextSources.length > 0) {
+    lines.push("### Context Used");
+    lines.push("");
+    lines.push(...formatContextSources(result.contextSources));
+    lines.push("");
+  }
+
   // Findings by severity (only include sections with findings)
   if (result.stats.critical > 0) {
     lines.push("---");
@@ -134,6 +142,35 @@ function formatFindings(findings: ReviewFinding[], severity: Severity): string[]
   return lines;
 }
 
+/**
+ * Format context sources for the Context Used section.
+ * Renders Linear tickets with clickable links and ADR files as a list.
+ */
+function formatContextSources(sources: ContextSource[]): string[] {
+  const lines: string[] = [];
+  
+  // Group sources by type
+  const linearSources = sources.filter(s => s.type === "linear");
+  const adrSources = sources.filter(s => s.type === "adr");
+  
+  // Format Linear tickets
+  for (const source of linearSources) {
+    if (source.url) {
+      lines.push(`- **Linear ticket:** [${source.id}](${source.url})`);
+    } else {
+      lines.push(`- **Linear ticket:** ${source.id}`);
+    }
+  }
+  
+  // Format ADR files
+  if (adrSources.length > 0) {
+    const adrList = adrSources.map(s => `\`${s.id}\``).join(", ");
+    lines.push(`- **ADRs referenced:** ${adrList}`);
+  }
+  
+  return lines;
+}
+
 /**
  * Format recommendation as human-readable text.
  */

package/src/types/review.ts

@@ -32,6 +32,25 @@ export interface ReviewFinding {
  */
 export type Recommendation = "APPROVE" | "REQUEST_CHANGES" | "COMMENT";
 
+/**
+ * Type of external context source used in the review.
+ */
+export type ContextSourceType = "linear" | "adr";
+
+/**
+ * External context source that informed the review.
+ */
+export interface ContextSource {
+  /** Type of context source */
+  type: ContextSourceType;
+  /** Identifier (ticket ID or file path) */
+  id: string;
+  /** Display title */
+  title?: string;
+  /** URL for clickable link (Linear tickets) */
+  url?: string;
+}
+
 /**
  * Statistics about the review findings.
  */
@@ -57,6 +76,8 @@ export interface ReviewResult {
   stats: ReviewStats;
   /** Files that were reviewed */
   filesReviewed: number;
+  /** External context sources used in the review */
+  contextSources?: ContextSource[];
 }
 
 /**

package/src/utils/redact.ts

@@ -0,0 +1,125 @@
+/**
+ * Secret redaction utilities.
+ * 
+ * Prevents API keys, tokens, and other sensitive values from appearing
+ * in logs, error messages, or PR comments.
+ * 
+ * Story 7.4: Security Enforcement (NFR4, NFR5)
+ */
+
+/**
+ * Environment variable names that contain secrets.
+ * Values from these variables will be redacted from any output.
+ */
+const SECRET_ENV_VARS = [
+  "OPENROUTER_API_KEY",
+  "LINEAR_API_TOKEN",
+  "LINEAR_API_KEY",
+  "GITHUB_TOKEN",
+  "GH_TOKEN",
+] as const;
+
+/**
+ * Environment variable names that are safe to pass to MCP subprocesses.
+ * Only these variables (plus explicitly provided config.env) are forwarded.
+ */
+export const MCP_SAFE_ENV_VARS = [
+  "PATH",
+  "HOME",
+  "USER",
+  "SHELL",
+  "TERM",
+  "LANG",
+  "LC_ALL",
+  "NODE_ENV",
+  "TMPDIR",
+  "XDG_RUNTIME_DIR",
+  // Node/Bun runtime
+  "NODE_PATH",
+  "BUN_INSTALL",
+  // npm/npx needs these to find packages
+  "npm_config_prefix",
+  "npm_config_cache",
+  "NVM_DIR",
+  "NVM_BIN",
+  "VOLTA_HOME",
+] as const;
+
+/**
+ * Redact known secret values from a string.
+ * 
+ * Scans the string for any values that match current environment variable
+ * secrets and replaces them with "[REDACTED]".
+ * 
+ * @param text - The string to redact secrets from
+ * @returns The redacted string
+ */
+export function redactSecrets(text: string): string {
+  let redacted = text;
+
+  for (const envVar of SECRET_ENV_VARS) {
+    const value = process.env[envVar];
+    if (value && value.length >= 4) {
+      // Replace all occurrences of the secret value
+      redacted = redacted.replaceAll(value, "[REDACTED]");
+    }
+  }
+
+  return redacted;
+}
+
+/**
+ * Safely stringify an error, redacting any secrets.
+ * 
+ * Handles unknown error types (Error, string, object, etc.)
+ * and ensures no secret values leak through error messages.
+ * 
+ * @param error - The error to stringify
+ * @returns A safe, redacted error string
+ */
+export function redactError(error: unknown): string {
+  let message: string;
+
+  if (error instanceof Error) {
+    // Only use message, not stack (stack can contain env var values)
+    message = error.message;
+  } else if (typeof error === "string") {
+    message = error;
+  } else {
+    try {
+      message = JSON.stringify(error) ?? String(error);
+    } catch {
+      message = String(error);
+    }
+  }
+
+  return redactSecrets(message);
+}
+
+/**
+ * Build a filtered environment for MCP subprocesses.
+ * 
+ * Only includes safe, non-secret environment variables from process.env,
+ * merged with any explicitly provided config env vars.
+ * 
+ * @param configEnv - Additional env vars from MCP config (may include tokens intentionally)
+ * @returns A filtered environment object
+ */
+export function buildSafeEnv(configEnv?: Record<string, string>): Record<string, string> {
+  const safeEnv: Record<string, string> = {};
+
+  // Only copy allowed env vars from process.env
+  for (const key of MCP_SAFE_ENV_VARS) {
+    const value = process.env[key];
+    if (value !== undefined) {
+      safeEnv[key] = value;
+    }
+  }
+
+  // Merge explicitly provided config env (these are intentional, e.g., LINEAR_API_KEY)
+  if (configEnv) {
+    Object.assign(safeEnv, configEnv);
+  }
+
+  return safeEnv;
+}