gsd-pi 2.60.0-dev.d9052f5 → 2.61.0

package/src/resources/extensions/gsd/model-router.ts

@@ -2,7 +2,7 @@
 // Maps complexity tiers to models, enforcing downgrade-only semantics.
 // The user's configured model is always the ceiling.
 
-import type { ComplexityTier, ClassificationResult } from "./complexity-classifier.js";
+import type { ComplexityTier, ClassificationResult, TaskMetadata } from "./complexity-classifier.js";
 import { tierOrdinal } from "./complexity-classifier.js";
 import type { ResolvedModelConfig } from "./preferences.js";
 
@@ -33,14 +33,27 @@ export interface RoutingDecision {
   wasDowngraded: boolean;
   /** Human-readable reason for this decision */
   reason: string;
-  /** How the model was selected. */
-  selectionMethod?: "tier-only" | "capability-scored";
-  /** Capability scores per model (when capability-scored). */
+  /** How the model was selected */
+  selectionMethod: "tier-only" | "capability-scored";
+  /** Capability scores per eligible model (capability-scored path only) */
   capabilityScores?: Record<string, number>;
-  /** Task requirement vector (when capability-scored). */
+  /** Task requirement vector used for scoring */
   taskRequirements?: Partial<Record<string, number>>;
 }
 
+// ─── Capability Profiles ─────────────────────────────────────────────────────
+
+/** Seven-dimension capability profile for a model. All values in 0–100 range. */
+export interface ModelCapabilities {
+  coding: number;
+  debugging: number;
+  research: number;
+  reasoning: number;
+  speed: number;
+  longContext: number;
+  instruction: number;
+}
+
 // ─── Known Model Tiers ───────────────────────────────────────────────────────
 // Maps known model IDs to their capability tier. Used when tier_models is not
 // explicitly configured to pick the best available model for each tier.
@@ -121,33 +134,27 @@ const MODEL_COST_PER_1K_INPUT: Record<string, number> = {
   "deepseek-chat": 0.00014,
 };
 
-// ─── Capability Profiles (ADR-004 Phase 2) ──────────────────────────────────
-// 7-dimension profiles, 0–100 normalized. Models without a profile
-// score 50 uniformly — capability scoring is a no-op for them.
-
-export interface ModelCapabilities {
-  coding: number;
-  debugging: number;
-  research: number;
-  reasoning: number;
-  speed: number;
-  longContext: number;
-  instruction: number;
-}
+// ─── Capability Profiles Data Table ──────────────────────────────────────────
+// Per-model capability profiles (0–100 scale). Used for capability-aware
+// model selection within an eligible tier set.
 
 export const MODEL_CAPABILITY_PROFILES: Record<string, ModelCapabilities> = {
-  "claude-opus-4-6":     { coding: 95, debugging: 90, research: 85, reasoning: 95, speed: 30, longContext: 80, instruction: 90 },
-  "claude-sonnet-4-6":   { coding: 85, debugging: 80, research: 75, reasoning: 80, speed: 60, longContext: 75, instruction: 85 },
-  "claude-haiku-4-5":    { coding: 60, debugging: 50, research: 45, reasoning: 50, speed: 95, longContext: 50, instruction: 75 },
-  "gpt-4o":              { coding: 80, debugging: 75, research: 70, reasoning: 75, speed: 65, longContext: 70, instruction: 80 },
-  "gpt-4o-mini":         { coding: 55, debugging: 45, research: 40, reasoning: 45, speed: 90, longContext: 45, instruction: 70 },
-  "gemini-2.5-pro":      { coding: 75, debugging: 70, research: 85, reasoning: 75, speed: 55, longContext: 90, instruction: 75 },
-  "gemini-2.0-flash":    { coding: 50, debugging: 40, research: 50, reasoning: 40, speed: 95, longContext: 60, instruction: 65 },
-  "deepseek-chat":       { coding: 75, debugging: 65, research: 55, reasoning: 70, speed: 70, longContext: 55, instruction: 65 },
-  "o3":                  { coding: 80, debugging: 85, research: 80, reasoning: 92, speed: 25, longContext: 70, instruction: 85 },
+  "claude-opus-4-6":   { coding: 95, debugging: 90, research: 85, reasoning: 95, speed: 30, longContext: 80, instruction: 90 },
+  "claude-sonnet-4-6": { coding: 85, debugging: 80, research: 75, reasoning: 80, speed: 60, longContext: 75, instruction: 85 },
+  "claude-haiku-4-5":  { coding: 60, debugging: 50, research: 45, reasoning: 50, speed: 95, longContext: 50, instruction: 75 },
+  "gpt-4o":            { coding: 80, debugging: 75, research: 70, reasoning: 75, speed: 65, longContext: 70, instruction: 80 },
+  "gpt-4o-mini":       { coding: 55, debugging: 45, research: 40, reasoning: 45, speed: 90, longContext: 45, instruction: 70 },
+  "gemini-2.5-pro":    { coding: 75, debugging: 70, research: 85, reasoning: 75, speed: 55, longContext: 90, instruction: 75 },
+  "gemini-2.0-flash":  { coding: 50, debugging: 40, research: 50, reasoning: 40, speed: 95, longContext: 60, instruction: 65 },
+  "deepseek-chat":     { coding: 75, debugging: 65, research: 55, reasoning: 70, speed: 70, longContext: 55, instruction: 65 },
+  "o3":                { coding: 80, debugging: 85, research: 80, reasoning: 92, speed: 25, longContext: 70, instruction: 85 },
 };
 
-const BASE_REQUIREMENTS: Record<string, Partial<Record<keyof ModelCapabilities, number>>> = {
+// ─── Base Task Requirements Data Table ───────────────────────────────────────
+// Per-unit-type base requirement vectors. Weights indicate how important each
+// capability dimension is for this unit type.
+
+export const BASE_REQUIREMENTS: Record<string, Partial<Record<keyof ModelCapabilities, number>>> = {
   "execute-task":       { coding: 0.9, instruction: 0.7, speed: 0.3 },
   "research-milestone": { research: 0.9, longContext: 0.7, reasoning: 0.5 },
   "research-slice":     { research: 0.9, longContext: 0.7, reasoning: 0.5 },
@@ -161,15 +168,36 @@ const BASE_REQUIREMENTS: Record<string, Partial<Record<keyof ModelCapabilities,
   "complete-milestone": { instruction: 0.8, reasoning: 0.5 },
 };
 
+// ─── Public API ──────────────────────────────────────────────────────────────
+
 /**
- * Compute a task requirement vector from unit type and optional metadata.
+ * Score a model's suitability for a task given a requirement vector.
+ * Returns a weighted average of capability dimensions (0–100).
+ * Returns 50 if requirements are empty (neutral score).
+ */
+export function scoreModel(
+  model: ModelCapabilities,
+  requirements: Partial<Record<keyof ModelCapabilities, number>>,
+): number {
+  let weightedSum = 0;
+  let weightSum = 0;
+  for (const [dim, weight] of Object.entries(requirements)) {
+    const capability = model[dim as keyof ModelCapabilities] ?? 50;
+    weightedSum += weight * capability;
+    weightSum += weight;
+  }
+  return weightSum > 0 ? weightedSum / weightSum : 50;
+}
+
+/**
+ * Compute dynamic task requirements from unit type and optional task metadata.
+ * Returns a requirement vector refined by task-specific signals.
  */
 export function computeTaskRequirements(
   unitType: string,
-  metadata?: { tags?: string[]; complexityKeywords?: string[]; fileCount?: number; estimatedLines?: number },
+  metadata?: TaskMetadata,
 ): Partial<Record<keyof ModelCapabilities, number>> {
-  const base = { ...(BASE_REQUIREMENTS[unitType] ?? { reasoning: 0.5 }) };
-
+  const base = BASE_REQUIREMENTS[unitType] ?? { reasoning: 0.5 };
   if (unitType === "execute-task" && metadata) {
     if (metadata.tags?.some(t => /^(docs?|readme|comment|config|typo|rename)$/i.test(t))) {
       return { ...base, instruction: 0.9, coding: 0.3, speed: 0.7 };
@@ -184,29 +212,101 @@ export function computeTaskRequirements(
       return { ...base, coding: 0.9, reasoning: 0.7 };
     }
   }
-
   return base;
 }
 
 /**
- * Score a model against a task requirement vector.
- * Returns weighted average in range 0–100. Returns 50 for empty requirements.
+ * Score all eligible models against a requirement vector and return them
+ * sorted by score descending. Within 2 points: prefer cheaper; equal cost:
+ * lexicographic tie-break by model ID.
  */
-export function scoreModel(
-  capabilities: ModelCapabilities,
+export function scoreEligibleModels(
+  eligibleModelIds: string[],
   requirements: Partial<Record<keyof ModelCapabilities, number>>,
-): number {
-  let weightedSum = 0;
-  let weightSum = 0;
-  for (const [dim, weight] of Object.entries(requirements)) {
-    const capability = capabilities[dim as keyof ModelCapabilities] ?? 50;
-    weightedSum += weight * capability;
-    weightSum += weight;
+  capabilityOverrides?: Record<string, Partial<ModelCapabilities>>,
+): Array<{ modelId: string; score: number }> {
+  const scored = eligibleModelIds.map(modelId => {
+    const builtin = MODEL_CAPABILITY_PROFILES[modelId];
+    const override = capabilityOverrides?.[modelId];
+    const profile: ModelCapabilities = builtin
+      ? override ? { ...builtin, ...override } : builtin
+      : { coding: 50, debugging: 50, research: 50, reasoning: 50, speed: 50, longContext: 50, instruction: 50 };
+    return { modelId, score: scoreModel(profile, requirements) };
+  });
+  scored.sort((a, b) => {
+    const scoreDiff = b.score - a.score;
+    if (Math.abs(scoreDiff) > 2) return scoreDiff;
+    const costA = MODEL_COST_PER_1K_INPUT[a.modelId] ?? Infinity;
+    const costB = MODEL_COST_PER_1K_INPUT[b.modelId] ?? Infinity;
+    if (costA !== costB) return costA - costB;
+    return a.modelId.localeCompare(b.modelId);
+  });
+  return scored;
+}
+
+/**
+ * Return all models eligible for a given tier, sorted cheapest first.
+ * If routingConfig.tier_models[tier] is set and available, returns only that
+ * model. Otherwise filters availableModelIds by tier from MODEL_CAPABILITY_TIER.
+ */
+export function getEligibleModels(
+  tier: ComplexityTier,
+  availableModelIds: string[],
+  routingConfig: DynamicRoutingConfig,
+): string[] {
+  // 1. Check explicit tier_models config
+  const explicitModel = routingConfig.tier_models?.[tier];
+  if (explicitModel) {
+    // Exact match
+    if (availableModelIds.includes(explicitModel)) return [explicitModel];
+    // Provider-prefix-stripped match
+    const match = availableModelIds.find(id => {
+      const bareAvail = id.includes("/") ? id.split("/").pop()! : id;
+      const bareExplicit = explicitModel.includes("/") ? explicitModel.split("/").pop()! : explicitModel;
+      return bareAvail === bareExplicit;
+    });
+    if (match) return [match];
   }
-  return weightSum > 0 ? weightedSum / weightSum : 50;
+
+  // 2. Auto-detect: filter by tier, sort cheapest first
+  return availableModelIds
+    .filter(id => getModelTier(id) === tier)
+    .sort((a, b) => {
+      const costA = getModelCost(a);
+      const costB = getModelCost(b);
+      return costA - costB;
+    });
 }
 
-// ─── Public API ──────────────────────────────────────────────────────────────
+/**
+ * Build a fallback chain for a selected model: [selectedModel, ...configuredFallbacks, configuredPrimary]
+ * Deduplicates entries while preserving order.
+ */
+function buildFallbackChain(selectedModelId: string, phaseConfig: ResolvedModelConfig): string[] {
+  return [
+    ...phaseConfig.fallbacks.filter(f => f !== selectedModelId),
+    phaseConfig.primary,
+  ].filter(f => f !== selectedModelId);
+}
+
+/**
+ * Load capability overrides from user preferences' modelOverrides section.
+ * Returns a map of model ID → partial capability overrides to deep-merge with built-in profiles.
+ *
+ * Per D-17: partial capability overrides via models.json modelOverrides, deep-merged with defaults.
+ */
+export function loadCapabilityOverrides(
+  prefs: { modelOverrides?: Record<string, { capabilities?: Partial<ModelCapabilities> }> },
+): Record<string, Partial<ModelCapabilities>> {
+  const result: Record<string, Partial<ModelCapabilities>> = {};
+  if (!prefs.modelOverrides) return result;
+  for (const [modelId, overrideEntry] of Object.entries(prefs.modelOverrides)) {
+    if (overrideEntry.capabilities) {
+      result[modelId] = overrideEntry.capabilities;
+    }
+  }
+  return result;
+}
 
 /**
  * Resolve the model to use for a given complexity tier.
@@ -214,10 +314,18 @@ export function scoreModel(
  * Downgrade-only: the returned model is always equal to or cheaper than
  * the user's configured primary model. Never upgrades beyond configuration.
  *
- * @param classification  The complexity classification result
- * @param phaseConfig     The user's configured model for this phase (ceiling)
- * @param routingConfig   Dynamic routing configuration
- * @param availableModelIds  List of available model IDs (from registry)
+ * STEP 1: Filter to eligible models for the requested tier.
+ * STEP 2: Capability scoring — ranks eligible models by task-capability match
+ *         when capability_routing is enabled and multiple eligible models exist.
+ * STEP 3: Fallback chain assembly.
+ *
+ * @param classification      The complexity classification result
+ * @param phaseConfig         The user's configured model for this phase (ceiling)
+ * @param routingConfig       Dynamic routing configuration
+ * @param availableModelIds   List of available model IDs (from registry)
+ * @param unitType            The unit type for capability requirement computation (optional)
+ * @param taskMetadata        Task metadata for refined requirement vectors (optional)
+ * @param capabilityOverrides User-provided capability overrides (deep-merged with built-in profiles, optional)
  */
 export function resolveModelForComplexity(
   classification: ClassificationResult,
@@ -225,7 +333,8 @@ export function resolveModelForComplexity(
   routingConfig: DynamicRoutingConfig,
   availableModelIds: string[],
   unitType?: string,
-  metadata?: { tags?: string[]; complexityKeywords?: string[]; fileCount?: number; estimatedLines?: number },
+  taskMetadata?: TaskMetadata,
+  capabilityOverrides?: Record<string, Partial<ModelCapabilities>>,
 ): RoutingDecision {
   // If no phase config or routing disabled, pass through
   if (!phaseConfig || !routingConfig.enabled) {
@@ -235,6 +344,7 @@ export function resolveModelForComplexity(
       tier: classification.tier,
       wasDowngraded: false,
       reason: "dynamic routing disabled or no phase config",
+      selectionMethod: "tier-only",
     };
   }
 
@@ -254,6 +364,7 @@ export function resolveModelForComplexity(
       tier: requestedTier,
       wasDowngraded: false,
       reason: `configured model "${configuredPrimary}" is not in the known tier map — honoring explicit config`,
+      selectionMethod: "tier-only",
     };
   }
 
@@ -265,48 +376,52 @@ export function resolveModelForComplexity(
       tier: requestedTier,
       wasDowngraded: false,
       reason: `tier ${requestedTier} >= configured ${configuredTier}`,
+      selectionMethod: "tier-only",
     };
   }
 
-  // Find the best model for the requested tier
-  const useCapabilityScoring = routingConfig.capability_routing && unitType;
-
-  let targetModelId: string | null;
-  let capabilityScores: Record<string, number> | undefined;
-  let taskRequirements: Partial<Record<string, number>> | undefined;
-  let selectionMethod: "tier-only" | "capability-scored" = "tier-only";
-
-  if (useCapabilityScoring) {
-    const result = findModelForTierWithCapability(
-      requestedTier, routingConfig, availableModelIds,
-      routingConfig.cross_provider !== false, unitType, metadata,
-    );
-    targetModelId = result.modelId;
-    capabilityScores = Object.keys(result.scores).length > 0 ? result.scores : undefined;
-    taskRequirements = Object.keys(result.requirements).length > 0 ? result.requirements : undefined;
-    selectionMethod = capabilityScores ? "capability-scored" : "tier-only";
-  } else {
-    targetModelId = findModelForTier(
-      requestedTier, routingConfig, availableModelIds,
-      routingConfig.cross_provider !== false,
-    );
-  }
+  // STEP 1: Get all eligible models for the requested tier
+  const eligible = getEligibleModels(requestedTier, availableModelIds, routingConfig);
 
-  if (!targetModelId) {
+  if (eligible.length === 0) {
+    // No suitable model found — use configured primary
     return {
       modelId: configuredPrimary,
       fallbacks: phaseConfig.fallbacks,
       tier: requestedTier,
       wasDowngraded: false,
       reason: `no ${requestedTier}-tier model available`,
-      selectionMethod,
+      selectionMethod: "tier-only",
     };
   }
 
-  const fallbacks = [
-    ...phaseConfig.fallbacks.filter(f => f !== targetModelId),
-    configuredPrimary,
-  ].filter(f => f !== targetModelId);
+  // STEP 2: Capability scoring (when enabled and multiple eligible models exist)
+  if (routingConfig.capability_routing !== false && eligible.length > 1 && unitType) {
+    const requirements = computeTaskRequirements(unitType, taskMetadata);
+    const scored = scoreEligibleModels(eligible, requirements, capabilityOverrides);
+    const winner = scored[0];
+    if (winner) {
+      const capScores: Record<string, number> = {};
+      for (const s of scored) capScores[s.modelId] = s.score;
+      const fallbacks = buildFallbackChain(winner.modelId, phaseConfig);
+      return {
+        modelId: winner.modelId,
+        fallbacks,
+        tier: requestedTier,
+        wasDowngraded: true,
+        reason: `capability-scored: ${winner.modelId} (${winner.score.toFixed(1)}) for ${unitType}`,
+        capabilityScores: capScores,
+        taskRequirements: requirements,
+        selectionMethod: "capability-scored",
+      };
+    }
+  }
+
+  // STEP 3: Fallback — use first eligible model (cheapest in tier, or single eligible)
+  const targetModelId = eligible[0];
+
+  // Build fallback chain: [downgraded_model, ...configured_fallbacks, configured_primary]
+  const fallbacks = buildFallbackChain(targetModelId, phaseConfig);
 
   return {
     modelId: targetModelId,
@@ -314,9 +429,7 @@ export function resolveModelForComplexity(
     tier: requestedTier,
     wasDowngraded: true,
     reason: classification.reason,
-    selectionMethod,
-    capabilityScores,
-    taskRequirements,
+    selectionMethod: "tier-only",
   };
 }
 
@@ -338,7 +451,7 @@ export function escalateTier(currentTier: ComplexityTier): ComplexityTier | null
 export function defaultRoutingConfig(): DynamicRoutingConfig {
   return {
     enabled: true,
-    capability_routing: false,
+    capability_routing: true,
     escalate_on_failure: true,
     budget_pressure: true,
     cross_provider: true,
@@ -360,8 +473,8 @@ function getModelTier(modelId: string): ComplexityTier {
     if (bareId.includes(knownId) || knownId.includes(bareId)) return tier;
   }
 
-  // Unknown models are assumed heavy (safest assumption)
-  return "heavy";
+  // Unknown models are assumed standard (per D-15: avoids silently ignoring user config)
+  return "standard";
 }
 
 /** Check if a model ID has a known capability tier mapping. (#2192) */
@@ -374,93 +487,6 @@ function isKnownModel(modelId: string): boolean {
   return false;
 }
 
-function findModelForTier(
-  tier: ComplexityTier,
-  config: DynamicRoutingConfig,
-  availableModelIds: string[],
-  crossProvider: boolean,
-): string | null {
-  // 1. Check explicit tier_models config
-  const explicitModel = config.tier_models?.[tier];
-  if (explicitModel && availableModelIds.includes(explicitModel)) {
-    return explicitModel;
-  }
-  // Also check with provider prefix stripped
-  if (explicitModel) {
-    const match = availableModelIds.find(id => {
-      const bareAvail = id.includes("/") ? id.split("/").pop()! : id;
-      const bareExplicit = explicitModel.includes("/") ? explicitModel.split("/").pop()! : explicitModel;
-      return bareAvail === bareExplicit;
-    });
-    if (match) return match;
-  }
-
-  // 2. Auto-detect: find the cheapest available model in the requested tier
-  const candidates = availableModelIds
-    .filter(id => {
-      const modelTier = getModelTier(id);
-      return modelTier === tier;
-    })
-    .sort((a, b) => {
-      if (!crossProvider) return 0;
-      const costA = getModelCost(a);
-      const costB = getModelCost(b);
-      return costA - costB;
-    });
-
-  return candidates[0] ?? null;
-}
-
-function findModelForTierWithCapability(
-  tier: ComplexityTier,
-  config: DynamicRoutingConfig,
-  availableModelIds: string[],
-  crossProvider: boolean,
-  unitType: string,
-  metadata?: { tags?: string[]; complexityKeywords?: string[]; fileCount?: number; estimatedLines?: number },
-): { modelId: string | null; scores: Record<string, number>; requirements: Partial<Record<string, number>> } {
-  const explicitModel = config.tier_models?.[tier];
-  if (explicitModel) {
-    const match = availableModelIds.find(id => {
-      const bareAvail = id.includes("/") ? id.split("/").pop()! : id;
-      const bareExplicit = explicitModel.includes("/") ? explicitModel.split("/").pop()! : explicitModel;
-      return bareAvail === bareExplicit || id === explicitModel;
-    });
-    if (match) return { modelId: match, scores: {}, requirements: {} };
-  }
-
-  const requirements = computeTaskRequirements(unitType, metadata);
-  const candidates = availableModelIds.filter(id => getModelTier(id) === tier);
-  if (candidates.length === 0) return { modelId: null, scores: {}, requirements };
-
-  const scores: Record<string, number> = {};
-  for (const id of candidates) {
-    const bareId = id.includes("/") ? id.split("/").pop()! : id;
-    const profile = getModelProfile(bareId);
-    scores[id] = scoreModel(profile, requirements);
-  }
-
-  candidates.sort((a, b) => {
-    const scoreDiff = scores[b] - scores[a];
-    if (Math.abs(scoreDiff) > 2) return scoreDiff;
-    if (crossProvider) {
-      const costDiff = getModelCost(a) - getModelCost(b);
-      if (costDiff !== 0) return costDiff;
-    }
-    return a.localeCompare(b);
-  });
-
-  return { modelId: candidates[0], scores, requirements };
-}
-
-function getModelProfile(bareId: string): ModelCapabilities {
-  if (MODEL_CAPABILITY_PROFILES[bareId]) return MODEL_CAPABILITY_PROFILES[bareId];
-  for (const [knownId, profile] of Object.entries(MODEL_CAPABILITY_PROFILES)) {
-    if (bareId.includes(knownId) || knownId.includes(bareId)) return profile;
-  }
-  return { coding: 50, debugging: 50, research: 50, reasoning: 50, speed: 50, longContext: 50, instruction: 50 };
-}
-
 function getModelCost(modelId: string): number {
   const bareId = modelId.includes("/") ? modelId.split("/").pop()! : modelId;
 

package/src/resources/extensions/gsd/parallel-merge.ts

@@ -15,6 +15,7 @@ import { MergeConflictError } from "./git-service.js";
 import { removeSessionStatus } from "./session-status-io.js";
 import type { WorkerInfo } from "./parallel-orchestrator.js";
 import { getErrorMessage } from "./error-utils.js";
+import { logWarning } from "./workflow-logger.js";
 
 // ─── Types ─────────────────────────────────────────────────────────────────
 
@@ -47,7 +48,8 @@ export function isMilestoneCompleteInWorktreeDb(basePath: string, mid: string):
       { timeout: 3000, encoding: "utf-8" },
     );
     return (result.stdout || "").trim() === "complete";
-  } catch {
+  } catch (e) {
+    logWarning("parallel", `spawnSync milestone completion check failed for ${mid}: ${(e as Error).message}`);
     return false;
   }
 }
@@ -65,8 +67,8 @@ function discoverDbCompletedMilestones(basePath: string): Set<string> {
         completed.add(entry);
       }
     }
-  } catch {
-    // worktrees dir may not exist
+  } catch (e) {
+    logWarning("parallel", `readdirSync for completed set failed: ${(e as Error).message}`);
   }
   return completed;
 }

package/src/resources/extensions/gsd/parallel-orchestrator.ts

@@ -41,6 +41,7 @@ import {
   type ParallelCandidates,
 } from "./parallel-eligibility.js";
 import { getErrorMessage } from "./error-utils.js";
+import { logWarning } from "./workflow-logger.js";
 
 // ─── Types ─────────────────────────────────────────────────────────────────
 
@@ -126,7 +127,7 @@ export function persistState(basePath: string): void {
     const tmp = dest + TMP_SUFFIX;
     writeFileSync(tmp, JSON.stringify(persisted, null, 2), "utf-8");
     renameSync(tmp, dest);
-  } catch { /* non-fatal */ }
+  } catch (e) { logWarning("parallel", `persist parallel state failed: ${(e as Error).message}`); }
 }
 
 /**
@@ -136,7 +137,7 @@ function removeStateFile(basePath: string): void {
   try {
     const p = stateFilePath(basePath);
     if (existsSync(p)) unlinkSync(p);
-  } catch { /* non-fatal */ }
+  } catch (e) { logWarning("parallel", `clear parallel state file failed: ${(e as Error).message}`); }
 }
 
 function isPidAlive(pid: number): boolean {
@@ -144,7 +145,8 @@ function isPidAlive(pid: number): boolean {
   try {
     process.kill(pid, 0);
     return true;
-  } catch {
+  } catch (e) {
+    logWarning("parallel", `pid alive check failed for pid ${pid}: ${(e as Error).message}`);
     return false;
   }
 }
@@ -176,7 +178,8 @@ export function restoreState(basePath: string): PersistedState | null {
     }
 
     return persisted;
-  } catch {
+  } catch (e) {
+    logWarning("parallel", `readParallelState JSON parse failed: ${(e as Error).message}`);
     return null;
   }
 }
@@ -190,8 +193,8 @@ function appendWorkerLog(basePath: string, milestoneId: string, chunk: string):
     const dir = join(gsdRoot(basePath), "parallel");
     if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
     appendFileSync(workerLogPath(basePath, milestoneId), chunk, "utf-8");
-  } catch {
-    // Non-fatal — diagnostics should never break orchestration.
+  } catch (e) {
+    logWarning("parallel", `appendFileSync worker log failed for ${milestoneId}: ${(e as Error).message}`);
   }
 }
 
@@ -430,9 +433,8 @@ export async function startParallel(
       let wtPath: string;
       try {
         wtPath = createMilestoneWorktree(basePath, mid);
-      } catch {
-        // Worktree creation may fail in test environments or when git
-        // is not available. Fall back to a placeholder path.
+      } catch (e) {
+        logWarning("parallel", `createMilestoneWorktree fallback for ${mid}: ${(e as Error).message}`);
         wtPath = worktreePath(basePath, mid);
       }
 
@@ -564,7 +566,8 @@ export function spawnWorker(
       stdio: ["ignore", "pipe", "pipe"],
       detached: false,
     });
-  } catch {
+  } catch (e) {
+    logWarning("parallel", `spawnSync worker failed for ${milestoneId}: ${(e as Error).message}`);
     return false;
   }
 
@@ -694,7 +697,8 @@ function resolveGsdBin(): string | null {
   let thisDir: string;
   try {
     thisDir = dirname(fileURLToPath(import.meta.url));
-  } catch {
+  } catch (e) {
+    logWarning("parallel", `dirname(fileURLToPath) failed: ${(e as Error).message}`);
     thisDir = process.cwd();
   }
   const candidates = [
@@ -722,7 +726,7 @@ function processWorkerLine(basePath: string, milestoneId: string, line: string):
   try {
     event = JSON.parse(line);
   } catch {
-    return; // Not valid JSON — skip (stderr leakage, debug output, etc.)
+    return; // Non-NDJSON lines (progress text, tool output) are expected — silent drop
   }
 
   const type = String(event.type ?? "");
@@ -817,7 +821,7 @@ export async function stopParallel(
         } else if (worker.pid !== process.pid) {
           process.kill(worker.pid, "SIGTERM");
         }
-      } catch { /* process may already be dead */ }
+      } catch (e) { logWarning("parallel", `process.kill SIGTERM failed for pid ${worker.pid}: ${(e as Error).message}`); }
     }
 
     // Wait for the headless process to cascade SIGTERM to its RPC child.
@@ -833,7 +837,7 @@ export async function stopParallel(
         } else if (worker.pid !== process.pid) {
           process.kill(worker.pid, "SIGKILL");
         }
-      } catch { /* process may already be dead */ }
+      } catch (e) { logWarning("parallel", `process.kill SIGKILL failed for pid ${worker.pid}: ${(e as Error).message}`); }
       await waitForWorkerExit(worker, 250);
     }