inspecto 1.0.12 → 1.0.13

package/dist/index.js

@@ -68,6 +68,7 @@ Expected: ${projectsDir}`
               sessionId,
               projectSlug: projectDir,
               mtime: fileStat.mtime,
+              birthtime: fileStat.birthtime,
               subagentPaths
             };
           } catch {
@@ -256,7 +257,7 @@ function normalizeContent(content) {
 // src/metrics/reads-per-edit.ts
 var EDIT_TOOLS = /* @__PURE__ */ new Set(["Write", "Edit", "NotebookEdit"]);
 var READ_TOOL = "Read";
-function computeReadsPerEdit(session) {
+function computeReadsPerEdit(session, thresholds) {
   let readsSinceLastEdit = 0;
   const ratios = [];
   for (const turn of session.turns) {
@@ -282,10 +283,11 @@ function computeReadsPerEdit(session) {
     };
   }
   const average2 = ratios.reduce((a, b) => a + b, 0) / ratios.length;
+  const { healthy, warning } = thresholds ?? { healthy: 4, warning: 2 };
   return {
     name: "reads-per-edit",
     value: round(average2),
-    status: average2 >= 4 ? "healthy" : average2 >= 2 ? "warning" : "critical",
+    status: average2 >= healthy ? "healthy" : average2 >= warning ? "warning" : "critical",
     label: round(average2).toString()
   };
 }
@@ -294,7 +296,7 @@ function round(n) {
 }
 
 // src/metrics/rewrite-ratio.ts
-function computeRewriteRatio(session) {
+function computeRewriteRatio(session, thresholds) {
   let writes = 0;
   let edits = 0;
   for (const turn of session.turns) {
@@ -317,10 +319,11 @@ function computeRewriteRatio(session) {
     };
   }
   const ratio = writes / total;
+  const { healthy, warning } = thresholds ?? { healthy: 0.25, warning: 0.5 };
   return {
     name: "rewrite-ratio",
     value: round2(ratio),
-    status: ratio <= 0.25 ? "healthy" : ratio <= 0.5 ? "warning" : "critical",
+    status: ratio <= healthy ? "healthy" : ratio <= warning ? "warning" : "critical",
     label: round2(ratio).toString()
   };
 }
@@ -329,7 +332,7 @@ function round2(n) {
 }
 
 // src/metrics/cache-hit-rate.ts
-function computeCacheHitRate(session) {
+function computeCacheHitRate(session, thresholds) {
   let totalCacheRead = 0;
   let totalCacheCreation = 0;
   for (const turn of session.turns) {
@@ -348,10 +351,11 @@ function computeCacheHitRate(session) {
     };
   }
   const rate = totalCacheRead / totalInput;
+  const { healthy, warning } = thresholds ?? { healthy: 0.5, warning: 0.2 };
   return {
     name: "cache-hit-rate",
     value: round3(rate),
-    status: rate >= 0.5 ? "healthy" : rate >= 0.2 ? "warning" : "critical",
+    status: rate >= healthy ? "healthy" : rate >= warning ? "warning" : "critical",
     label: round3(rate).toString()
   };
 }
@@ -368,7 +372,7 @@ var INTENT_PATTERNS = [
   /\bI'll (?:also |then )?(?:fix|add|create|implement|refactor|modify|change|write|edit|update)\b/i,
   /\bI'm going to\b/i
 ];
-function computeTaskCompletion(session) {
+function computeTaskCompletion(session, thresholds) {
   const assistantTurns = session.turns.filter(
     (t) => t.role === "assistant" && t.complete
   );
@@ -393,10 +397,11 @@ function computeTaskCompletion(session) {
     };
   }
   const rate = 1 - unfulfilledIntents / totalIntents;
+  const { healthy, warning } = thresholds ?? { healthy: 0.9, warning: 0.7 };
   return {
     name: "task-completion",
     value: round4(rate),
-    status: rate >= 0.9 ? "healthy" : rate >= 0.7 ? "warning" : "critical",
+    status: rate >= healthy ? "healthy" : rate >= warning ? "warning" : "critical",
     label: round4(rate).toString()
   };
 }
@@ -454,7 +459,7 @@ function normalizedSimilarity(a, b, maxLen = 200) {
 }
 
 // src/metrics/retry-density.ts
-function computeRetryDensity(session) {
+function computeRetryDensity(session, thresholds) {
   const humanTexts = [];
   for (const turn of session.turns) {
     if (!turn.isHumanTurn) continue;
@@ -479,10 +484,11 @@ function computeRetryDensity(session) {
     }
   }
   const density = retries / pairs;
+  const { healthy, warning } = thresholds ?? { healthy: 0.1, warning: 0.25 };
   return {
     name: "retry-density",
     value: round5(density),
-    status: density <= 0.1 ? "healthy" : density <= 0.25 ? "warning" : "critical",
+    status: density <= healthy ? "healthy" : density <= warning ? "warning" : "critical",
     label: round5(density).toString()
   };
 }
@@ -491,7 +497,7 @@ function round5(n) {
 }
 
 // src/metrics/tool-diversity.ts
-function computeToolDiversity(session) {
+function computeToolDiversity(session, thresholds) {
   const toolCounts = /* @__PURE__ */ new Map();
   for (const turn of session.turns) {
     if (turn.role !== "assistant") continue;
@@ -523,10 +529,11 @@ function computeToolDiversity(session) {
   const topTool = sorted[0];
   const topPercent = Math.round(topTool[1] / totalCalls * 100);
   const detail = `Most used: ${topTool[0]} (${topPercent}%)`;
+  const { healthy, warning } = thresholds ?? { healthy: 0.6, warning: 0.4 };
   return {
     name: "tool-diversity",
     value: round6(normalized),
-    status: normalized >= 0.6 ? "healthy" : normalized >= 0.4 ? "warning" : "critical",
+    status: normalized >= healthy ? "healthy" : normalized >= warning ? "warning" : "critical",
     label: round6(normalized).toString(),
     detail
   };
@@ -537,7 +544,7 @@ function round6(n) {
 
 // src/metrics/tokens-per-edit.ts
 var EDIT_TOOLS2 = /* @__PURE__ */ new Set(["Write", "Edit", "NotebookEdit"]);
-function computeTokensPerEdit(session) {
+function computeTokensPerEdit(session, thresholds) {
   let totalOutputTokens = 0;
   let editCount = 0;
   for (const turn of session.turns) {
@@ -561,10 +568,11 @@ function computeTokensPerEdit(session) {
     };
   }
   const ratio = totalOutputTokens / editCount;
+  const { healthy, warning } = thresholds ?? { healthy: 5e3, warning: 15e3 };
   return {
     name: "tokens-per-edit",
     value: Math.round(ratio),
-    status: ratio <= 5e3 ? "healthy" : ratio <= 15e3 ? "warning" : "critical",
+    status: ratio <= healthy ? "healthy" : ratio <= warning ? "warning" : "critical",
     label: Math.round(ratio).toLocaleString("en-US")
   };
 }
@@ -611,57 +619,231 @@ function computeSubagentOverhead(session) {
   };
 }
 
-// src/metrics/grader.ts
-var METRIC_WEIGHTS = [
-  {
-    compute: computeReadsPerEdit,
-    weight: 0.2,
-    // 0 reads → 0, 2 reads → 50, 4+ reads → 100
-    score: (v) => clamp(v / 4 * 100, 0, 100)
-  },
-  {
-    compute: computeRewriteRatio,
-    weight: 0.15,
-    // 0 ratio → 100, 0.25 → 50, 0.5+ → 0 (inverted: lower is better)
-    score: (v) => clamp((1 - v / 0.5) * 100, 0, 100)
-  },
-  {
-    compute: computeCacheHitRate,
-    weight: 0.15,
-    // 0% → 0, 50% → 100
-    score: (v) => clamp(v / 0.5 * 100, 0, 100)
-  },
-  {
-    compute: computeTaskCompletion,
-    weight: 0.15,
-    // 0.7 → 0, 0.9 → 50, 1.0 → 100
-    score: (v) => clamp((v - 0.7) / 0.3 * 100, 0, 100)
-  },
-  {
-    compute: computeRetryDensity,
-    weight: 0.1,
-    // 0% → 100, 10% → 60, 25%+ → 0 (inverted)
-    score: (v) => clamp((1 - v / 0.25) * 100, 0, 100)
-  },
-  {
-    compute: computeToolDiversity,
-    weight: 0.05,
-    // 0 → 0, 0.4 → 50, 0.6+ → 100
-    score: (v) => clamp(v / 0.6 * 100, 0, 100)
-  },
-  {
-    compute: computeTokensPerEdit,
-    weight: 0.15,
-    // 5000 → 100, 10000 → 50, 15000+ → 0 (inverted)
-    score: (v) => clamp((1 - (v - 5e3) / 1e4) * 100, 0, 100)
-  },
-  {
-    compute: computeSubagentOverhead,
-    weight: 0.05,
-    // main ratio 0 → 100, 0.6 → 100 (threshold), 0.8 → 50, 1.0 → 0 (inverted)
-    score: (v) => clamp((1 - v) / 0.4 * 100, 0, 100)
+// src/metrics/tool-error-rate.ts
+function computeToolErrorRate(session) {
+  let totalResults = 0;
+  let errorResults = 0;
+  for (const turn of session.turns) {
+    for (const block of turn.content) {
+      if (block.type !== "tool_result") continue;
+      const resultBlock = block;
+      totalResults++;
+      if (resultBlock.is_error === true) errorResults++;
+    }
   }
-];
+  if (totalResults === 0) {
+    return {
+      name: "tool-error-rate",
+      value: null,
+      status: "healthy",
+      label: "N/A",
+      detail: "No tool calls in this session"
+    };
+  }
+  const rate = errorResults / totalResults;
+  return {
+    name: "tool-error-rate",
+    value: round7(rate),
+    status: rate <= 0.05 ? "healthy" : rate <= 0.15 ? "warning" : "critical",
+    label: `${(rate * 100).toFixed(1)}%`
+  };
+}
+function round7(n) {
+  return Math.round(n * 1e4) / 1e4;
+}
+
+// src/metrics/thinking-utilization.ts
+function computeThinkingUtilization(session) {
+  const assistantTurns = session.turns.filter((t) => t.role === "assistant");
+  const hasAnyToolUse = assistantTurns.some(
+    (t) => t.content.some((b) => b.type === "tool_use")
+  );
+  if (!hasAnyToolUse) {
+    return {
+      name: "thinking-utilization",
+      value: null,
+      status: "healthy",
+      label: "N/A",
+      detail: "No tool use in this session"
+    };
+  }
+  const turnsWithThinking = assistantTurns.filter(
+    (t) => t.content.some((b) => b.type === "thinking")
+  ).length;
+  if (turnsWithThinking === 0) {
+    return {
+      name: "thinking-utilization",
+      value: 0,
+      status: "critical",
+      label: "0%",
+      detail: "No extended thinking blocks detected"
+    };
+  }
+  const ratio = Math.min(turnsWithThinking / assistantTurns.length, 1);
+  return {
+    name: "thinking-utilization",
+    value: round8(ratio),
+    status: ratio >= 0.3 ? "healthy" : ratio >= 0.1 ? "warning" : "critical",
+    label: `${(ratio * 100).toFixed(1)}%`
+  };
+}
+function round8(n) {
+  return Math.round(n * 1e4) / 1e4;
+}
+
+// src/metrics/mcp-usage.ts
+function computeMcpUsage(session) {
+  const assistantTurnsWithTools = session.turns.filter(
+    (t) => t.role === "assistant" && t.content.some((b) => b.type === "tool_use")
+  );
+  if (assistantTurnsWithTools.length === 0) {
+    return {
+      name: "mcp-usage",
+      value: null,
+      status: "healthy",
+      label: "N/A",
+      detail: "No tool use in this session"
+    };
+  }
+  let mcpTurnCount = 0;
+  for (const turn of assistantTurnsWithTools) {
+    const hasMcpTool = turn.content.some(
+      (b) => b.type === "tool_use" && b.name.startsWith("mcp__")
+    );
+    const hasServerToolUse = (turn.usage?.server_tool_use?.web_search_requests ?? 0) > 0 || (turn.usage?.server_tool_use?.web_fetch_requests ?? 0) > 0;
+    if (hasMcpTool || hasServerToolUse) mcpTurnCount++;
+  }
+  const ratio = mcpTurnCount / assistantTurnsWithTools.length;
+  return {
+    name: "mcp-usage",
+    value: round9(ratio),
+    status: "healthy",
+    label: `${mcpTurnCount} turn${mcpTurnCount !== 1 ? "s" : ""}`
+  };
+}
+function round9(n) {
+  return Math.round(n * 1e4) / 1e4;
+}
+
+// src/metrics/session-cost.ts
+var PRICE_PER_M = {
+  output: 15,
+  cacheCreation: 3.75,
+  cacheRead: 0.3,
+  input: 3
+};
+function computeSessionCost(session, thresholds) {
+  let outputTokens = 0;
+  let cacheCreationTokens = 0;
+  let cacheReadTokens = 0;
+  for (const turn of session.turns) {
+    if (!turn.usage) continue;
+    outputTokens += turn.usage.output_tokens ?? 0;
+    cacheCreationTokens += turn.usage.cache_creation_input_tokens ?? 0;
+    cacheReadTokens += turn.usage.cache_read_input_tokens ?? 0;
+  }
+  const totalTokens = outputTokens + cacheCreationTokens + cacheReadTokens;
+  if (totalTokens === 0) {
+    return {
+      name: "session-cost",
+      value: null,
+      status: "healthy",
+      label: "N/A",
+      detail: "No token usage data in this session"
+    };
+  }
+  const cost = (outputTokens * PRICE_PER_M.output + cacheCreationTokens * PRICE_PER_M.cacheCreation + cacheReadTokens * PRICE_PER_M.cacheRead) / 1e6;
+  const { healthy, warning } = thresholds ?? { healthy: 2, warning: 5 };
+  return {
+    name: "session-cost",
+    value: round10(cost),
+    status: cost <= healthy ? "healthy" : cost <= warning ? "warning" : "critical",
+    label: `$${cost.toFixed(2)}`
+  };
+}
+function round10(n) {
+  return Math.round(n * 1e4) / 1e4;
+}
+
+// src/metrics/grader.ts
+function buildMetricWeights(config2) {
+  const t = config2?.thresholds ?? {};
+  const w = config2?.weights ?? {};
+  return [
+    {
+      compute: (session) => computeReadsPerEdit(session, t.readsPerEdit),
+      weight: w.readsPerEdit ?? 0.14,
+      // 0 reads → 0, 2 reads → 50, 4+ reads → 100
+      score: (v) => clamp(v / 4 * 100, 0, 100)
+    },
+    {
+      compute: (session) => computeRewriteRatio(session, t.rewriteRatio),
+      weight: w.rewriteRatio ?? 0.11,
+      // 0 ratio → 100, 0.25 → 50, 0.5+ → 0 (inverted: lower is better)
+      score: (v) => clamp((1 - v / 0.5) * 100, 0, 100)
+    },
+    {
+      compute: (session) => computeCacheHitRate(session, t.cacheHitRate),
+      weight: w.cacheHitRate ?? 0.11,
+      // 0% → 0, 50% → 100
+      score: (v) => clamp(v / 0.5 * 100, 0, 100)
+    },
+    {
+      compute: (session) => computeTaskCompletion(session, t.taskCompletion),
+      weight: w.taskCompletion ?? 0.1,
+      // 0.7 → 0, 0.9 → 50, 1.0 → 100
+      score: (v) => clamp((v - 0.7) / 0.3 * 100, 0, 100)
+    },
+    {
+      compute: (session) => computeRetryDensity(session, t.retryDensity),
+      weight: w.retryDensity ?? 0.07,
+      // 0% → 100, 10% → 60, 25%+ → 0 (inverted)
+      score: (v) => clamp((1 - v / 0.25) * 100, 0, 100)
+    },
+    {
+      compute: (session) => computeToolDiversity(session, t.toolDiversity),
+      weight: w.toolDiversity ?? 0.06,
+      // 0 → 0, 0.4 → 50, 0.6+ → 100
+      score: (v) => clamp(v / 0.6 * 100, 0, 100)
+    },
+    {
+      compute: (session) => computeTokensPerEdit(session, t.tokensPerEdit),
+      weight: w.tokensPerEdit ?? 0.11,
+      // 5000 → 100, 10000 → 50, 15000+ → 0 (inverted)
+      score: (v) => clamp((1 - (v - 5e3) / 1e4) * 100, 0, 100)
+    },
+    {
+      compute: computeSubagentOverhead,
+      weight: 0.05,
+      // main ratio 0 → 100, 0.6 → 100 (threshold), 0.8 → 50, 1.0 → 0 (inverted)
+      score: (v) => clamp((1 - v) / 0.4 * 100, 0, 100)
+    },
+    {
+      compute: computeToolErrorRate,
+      weight: 0.08,
+      // 0% → 100, 5% → 83, 15% → 50, 30%+ → 0 (inverted: lower is better)
+      score: (v) => clamp((1 - v / 0.3) * 100, 0, 100)
+    },
+    {
+      compute: computeThinkingUtilization,
+      weight: 0.07,
+      // 0% → 0, 10% → 33, 30%+ → 100
+      score: (v) => clamp(v / 0.3 * 100, 0, 100)
+    },
+    {
+      compute: computeMcpUsage,
+      weight: 0.05,
+      // Informational: always contributes max score
+      score: (_v) => 100
+    },
+    {
+      compute: (session) => computeSessionCost(session, t.sessionCost),
+      weight: 0.05,
+      // $0 → 100, $5 → 50, $10+ → 0 (inverted: lower cost is better)
+      score: (v) => clamp((1 - v / 10) * 100, 0, 100)
+    }
+  ];
+}
 var GRADE_THRESHOLDS = [
   [97, "A+"],
   [93, "A"],
@@ -680,11 +862,12 @@ var GRADE_THRESHOLDS = [
 function gradeLetterFromScore(score) {
   return GRADE_THRESHOLDS.find(([threshold]) => score >= threshold)?.[1] ?? "F";
 }
-function gradeSession(session) {
+function gradeSession(session, config2) {
+  const metricWeights = buildMetricWeights(config2);
   const metrics = [];
   let weightedSum = 0;
   let totalWeight = 0;
-  for (const mw of METRIC_WEIGHTS) {
+  for (const mw of metricWeights) {
     const result = mw.compute(session);
     metrics.push(result);
     if (result.value !== null) {
@@ -756,6 +939,18 @@ var TIPS = {
   "tokens-per-edit": {
     warning: "Tokens per edit is above average. Claude may be verbose without being productive.",
     critical: "Very high token cost per edit. Claude is burning tokens without proportional output."
+  },
+  "tool-error-rate": {
+    warning: "Elevated tool error rate. Claude may be calling tools with invalid arguments or on wrong paths.",
+    critical: "High tool error rate. Frequent tool failures indicate misaligned inputs or environment issues."
+  },
+  "thinking-utilization": {
+    warning: "Extended thinking is underutilized. Enable it in your Claude Code settings for complex tasks.",
+    critical: "No extended thinking detected on tool-using turns. Complex tasks benefit greatly from thinking blocks."
+  },
+  "session-cost": {
+    warning: "Session cost is above $2. Consider breaking long sessions into smaller focused tasks.",
+    critical: "Session cost exceeds $5. Review if Claude is re-reading large files or running redundant operations."
   }
 };
 function getTip(metric) {
@@ -999,13 +1194,119 @@ function formatCacheCheckJson(results) {
   return JSON.stringify({ cacheCheck: results }, null, 2);
 }
 
+// src/reporter/csv-reporter.ts
+function csvEscape(value) {
+  if (value === null) return "";
+  const str = String(value);
+  if (str.includes(",") || str.includes('"') || str.includes("\n") || str.includes("\r")) {
+    return `"${str.replace(/"/g, '""')}"`;
+  }
+  return str;
+}
+function csvRow(fields) {
+  return fields.map(csvEscape).join(",");
+}
+function exportAuditCsv(grade) {
+  const lines = [];
+  lines.push(csvRow(["name", "value", "status", "label"]));
+  for (const metric of grade.metrics) {
+    lines.push(csvRow([metric.name, metric.value, metric.status, metric.label]));
+  }
+  return lines.join("\n");
+}
+function exportTrendCsv(results) {
+  const lines = [];
+  lines.push(csvRow(["name", "recentAvg", "fullAvg", "changePercent", "status"]));
+  for (const r of results) {
+    lines.push(csvRow([r.name, r.recentAvg, r.fullAvg, r.changePercent, r.status]));
+  }
+  return lines.join("\n");
+}
+
+// src/config/loader.ts
+import { readFileSync } from "fs";
+import { join as join3 } from "path";
+var KNOWN_THRESHOLD_KEYS = /* @__PURE__ */ new Set([
+  "readsPerEdit",
+  "rewriteRatio",
+  "cacheHitRate",
+  "taskCompletion",
+  "retryDensity",
+  "toolDiversity",
+  "tokensPerEdit",
+  "sessionCost"
+]);
+var KNOWN_WEIGHT_KEYS = /* @__PURE__ */ new Set([
+  "readsPerEdit",
+  "rewriteRatio",
+  "cacheHitRate",
+  "taskCompletion",
+  "retryDensity",
+  "toolDiversity",
+  "tokensPerEdit"
+]);
+var KNOWN_TOP_KEYS = /* @__PURE__ */ new Set(["thresholds", "weights", "dataDir", "defaultProject"]);
+function loadConfig() {
+  const configPath = join3(process.cwd(), ".inspecto.json");
+  let raw;
+  try {
+    raw = readFileSync(configPath, "utf8");
+  } catch {
+    return {};
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    process.stderr.write("inspecto: warning: .inspecto.json contains invalid JSON, using defaults\n");
+    return {};
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    process.stderr.write("inspecto: warning: .inspecto.json must be a JSON object, using defaults\n");
+    return {};
+  }
+  const config2 = parsed;
+  for (const key of Object.keys(config2)) {
+    if (!KNOWN_TOP_KEYS.has(key)) {
+      process.stderr.write(`inspecto: warning: .inspecto.json unknown key "${key}"
+`);
+    }
+  }
+  if (config2["thresholds"] && typeof config2["thresholds"] === "object" && !Array.isArray(config2["thresholds"])) {
+    for (const key of Object.keys(config2["thresholds"])) {
+      if (!KNOWN_THRESHOLD_KEYS.has(key)) {
+        process.stderr.write(`inspecto: warning: .inspecto.json unknown thresholds key "${key}"
+`);
+      }
+    }
+  }
+  if (config2["weights"] && typeof config2["weights"] === "object" && !Array.isArray(config2["weights"])) {
+    for (const key of Object.keys(config2["weights"])) {
+      if (!KNOWN_WEIGHT_KEYS.has(key)) {
+        process.stderr.write(`inspecto: warning: .inspecto.json unknown weights key "${key}"
+`);
+      }
+    }
+    const weights = config2["weights"];
+    const numericValues = Object.values(weights).filter((v) => typeof v === "number");
+    const sum = numericValues.reduce((a, b) => a + b, 0);
+    if (sum > 1 + 1e-9) {
+      process.stderr.write(
+        `inspecto: warning: weights in .inspecto.json sum to ${sum.toFixed(4)}, which exceeds 1.0
+`
+      );
+    }
+  }
+  return parsed;
+}
+
 // src/commands/audit.ts
 var KNOWN_FORMAT_VERSION = "2.1.167";
 async function runAudit(options) {
-  const sessionFile = await getMostRecentSession({
-    dataDir: options.dataDir,
-    project: options.project
-  });
+  const config2 = loadConfig();
+  const dataDir = options.dataDir ?? config2.dataDir;
+  const project = options.project ?? config2.defaultProject;
+  const sessionFile = await getMostRecentSession({ dataDir, project });
   const records = readJsonl(sessionFile.path);
   const session = await buildSession(
     records,
@@ -1013,24 +1314,29 @@ async function runAudit(options) {
     sessionFile.projectSlug,
     sessionFile.subagentPaths
   );
-  const grade = gradeSession(session);
-  if (options.json) {
+  const grade = gradeSession(session, config2);
+  if (options.json || options.format === "json") {
     console.log(formatAuditJson(session, grade));
-    return;
-  }
-  if (session.formatVersion && session.formatVersion !== KNOWN_FORMAT_VERSION) {
-    console.log(
-      chalk2.yellow(
-        `\u26A0 JSONL format version ${session.formatVersion} detected (expected ${KNOWN_FORMAT_VERSION}). Metrics may be inaccurate.`
-      )
-    );
-  }
-  if (session.unknownRecordTypes.size > 0) {
-    const types = [...session.unknownRecordTypes].sort().join(", ");
-    process.stdout.write(chalk2.dim(`Note: skipped unknown record types: ${types}
+  } else if (options.format === "csv") {
+    console.log(exportAuditCsv(grade));
+  } else {
+    if (session.formatVersion && session.formatVersion !== KNOWN_FORMAT_VERSION) {
+      console.log(
+        chalk2.yellow(
+          `\u26A0 JSONL format version ${session.formatVersion} detected (expected ${KNOWN_FORMAT_VERSION}). Metrics may be inaccurate.`
+        )
+      );
+    }
+    if (session.unknownRecordTypes.size > 0) {
+      const types = [...session.unknownRecordTypes].sort().join(", ");
+      process.stdout.write(chalk2.dim(`Note: skipped unknown record types: ${types}
 `));
+    }
+    console.log(renderAuditReport(session, grade));
+  }
+  if (options.fail !== false && grade.score < 67) {
+    process.exitCode = 1;
   }
-  console.log(renderAuditReport(session, grade));
 }
 
 // src/anomaly/baseline.ts
@@ -1173,13 +1479,12 @@ function setCachedGrade(sessionPath, mtime, grade) {
 // src/commands/trend.ts
 var CONCURRENCY = 16;
 async function runTrend(options) {
+  const config2 = loadConfig();
+  const dataDir = options.dataDir ?? config2.dataDir;
+  const project = options.project ?? config2.defaultProject;
   const duration = options.since ?? "7d";
   const sinceDate = parseDuration(duration);
-  const sessionFiles = await scanSessions({
-    dataDir: options.dataDir,
-    project: options.project,
-    since: sinceDate
-  });
+  const sessionFiles = await scanSessions({ dataDir, project, since: sinceDate });
   if (sessionFiles.length === 0) {
     console.log(`No sessions found in the last ${duration}.`);
     return;
@@ -1189,7 +1494,7 @@ async function runTrend(options) {
     if (cached) return cached;
     const records = readJsonl(sf.path);
     const session = await buildSession(records, sf.sessionId, sf.projectSlug, sf.subagentPaths);
-    const grade = gradeSession(session);
+    const grade = gradeSession(session, config2);
     setCachedGrade(sf.path, sf.mtime, grade);
     return grade;
   });
@@ -1201,11 +1506,16 @@ async function runTrend(options) {
   const recentCount = Math.max(1, Math.floor(grades.length / 2));
   const baselines = computeBaselines(grades, recentCount);
   const regressions = detectRegressions(baselines);
-  if (options.json) {
+  if (options.json || options.format === "json") {
     console.log(formatTrendJson(regressions));
+  } else if (options.format === "csv") {
+    console.log(exportTrendCsv(regressions));
   } else {
     console.log(renderTrendReport(regressions, grades.length, duration));
   }
+  if (options.fail !== false && regressions.some((r) => r.status === "regression")) {
+    process.exitCode = 1;
+  }
 }
 
 // src/anomaly/cache-anomaly.ts
@@ -1257,6 +1567,9 @@ async function runCacheCheck(options) {
   } else {
     console.log(renderCacheCheckReport(results));
   }
+  if (options.fail !== false && results.some((r) => r.isAnomaly)) {
+    process.exitCode = 1;
+  }
 }
 
 // src/commands/compare.ts
@@ -1264,14 +1577,13 @@ import chalk3 from "chalk";
 import Table2 from "cli-table3";
 var CONCURRENCY2 = 16;
 async function runCompare(options) {
+  const config2 = loadConfig();
+  const dataDir = options.dataDir ?? config2.dataDir;
   const projectNames = options.projects.split(",").map((p) => p.trim());
   const summaries = [];
   const projectSummaries = await Promise.all(
     projectNames.map(async (projectFilter) => {
-      const sessionFiles = await scanSessions({
-        dataDir: options.dataDir,
-        project: projectFilter
-      });
+      const sessionFiles = await scanSessions({ dataDir, project: projectFilter });
       if (sessionFiles.length === 0) return null;
       const settled = await concurrentSettled(
         sessionFiles,
@@ -1286,7 +1598,7 @@ async function runCompare(options) {
             sf.projectSlug,
             sf.subagentPaths
           );
-          const grade = gradeSession(session);
+          const grade = gradeSession(session, config2);
           setCachedGrade(sf.path, sf.mtime, grade);
           return grade;
         }
@@ -1372,37 +1684,269 @@ async function runCompare(options) {
   console.log(lines.join("\n"));
 }
 
+// src/commands/list.ts
+import chalk4 from "chalk";
+import Table3 from "cli-table3";
+var TABLE_CHARS = {
+  top: "\u2500",
+  "top-mid": "\u2500",
+  "top-left": "  ",
+  "top-right": "",
+  bottom: "\u2500",
+  "bottom-mid": "\u2500",
+  "bottom-left": "  ",
+  "bottom-right": "",
+  left: "  ",
+  "left-mid": "  ",
+  mid: "\u2500",
+  "mid-mid": "\u2500",
+  right: "",
+  "right-mid": "",
+  middle: "  "
+};
+var TABLE_STYLE = { head: [], border: [], "padding-left": 2, "padding-right": 2 };
+async function runList(options) {
+  const sessionFiles = await scanSessions({
+    dataDir: options.dataDir,
+    project: options.project
+  });
+  if (sessionFiles.length === 0) {
+    console.log("No sessions found.");
+    return;
+  }
+  if (options.sessions || options.project) {
+    const toShow = options.project ? sessionFiles : sessionFiles.slice(0, 20);
+    const lines = [""];
+    if (options.project) {
+      lines.push(chalk4.bold(`  Sessions for ${options.project}`) + chalk4.dim(` (${toShow.length})`));
+    } else {
+      lines.push(chalk4.bold("  20 most recent sessions"));
+    }
+    lines.push("");
+    const table = new Table3({
+      head: ["Session", "Project", "Date", "Duration"].map((h) => chalk4.dim(h)),
+      style: TABLE_STYLE,
+      chars: TABLE_CHARS
+    });
+    for (const sf of toShow) {
+      const dateStr = sf.mtime.toISOString().slice(0, 10);
+      let durStr = "\u2014";
+      if (sf.birthtime && sf.birthtime.getTime() > 0 && sf.birthtime.getTime() < sf.mtime.getTime()) {
+        durStr = formatDuration(sf.mtime.getTime() - sf.birthtime.getTime());
+      }
+      table.push([shortSessionId(sf.sessionId), sf.projectSlug, dateStr, durStr]);
+    }
+    lines.push(table.toString());
+    lines.push("");
+    console.log(lines.join("\n"));
+  } else {
+    const projectMap = /* @__PURE__ */ new Map();
+    for (const sf of sessionFiles) {
+      const existing = projectMap.get(sf.projectSlug);
+      if (!existing) {
+        projectMap.set(sf.projectSlug, { count: 1, lastActive: sf.mtime });
+      } else {
+        existing.count++;
+        if (sf.mtime > existing.lastActive) existing.lastActive = sf.mtime;
+      }
+    }
+    const projects = [...projectMap.entries()].sort(
+      (a, b) => b[1].lastActive.getTime() - a[1].lastActive.getTime()
+    );
+    const lines = [""];
+    lines.push(chalk4.bold("  Projects") + chalk4.dim(` (${projects.length} found)`));
+    lines.push("");
+    const table = new Table3({
+      head: ["Project", "Sessions", "Last active"].map((h) => chalk4.dim(h)),
+      style: TABLE_STYLE,
+      chars: TABLE_CHARS
+    });
+    for (const [slug, info] of projects) {
+      table.push([slug, info.count.toString(), info.lastActive.toISOString().slice(0, 10)]);
+    }
+    lines.push(table.toString());
+    lines.push("");
+    console.log(lines.join("\n"));
+  }
+}
+
+// src/commands/config-validate.ts
+import chalk5 from "chalk";
+import Table4 from "cli-table3";
+
+// src/config/types.ts
+var DEFAULT_THRESHOLDS = {
+  readsPerEdit: { healthy: 4, warning: 2 },
+  rewriteRatio: { healthy: 0.25, warning: 0.4 },
+  cacheHitRate: { healthy: 0.5, warning: 0.3 },
+  taskCompletion: { healthy: 0.9, warning: 0.7 },
+  retryDensity: { healthy: 0.1, warning: 0.2 },
+  toolDiversity: { healthy: 0.6, warning: 0.4 },
+  tokensPerEdit: { healthy: 5e3, warning: 1e4 },
+  sessionCost: { healthy: 2, warning: 5 }
+};
+var DEFAULT_WEIGHTS = {
+  readsPerEdit: 0.14,
+  rewriteRatio: 0.11,
+  cacheHitRate: 0.11,
+  taskCompletion: 0.1,
+  retryDensity: 0.07,
+  toolDiversity: 0.06,
+  tokensPerEdit: 0.11
+};
+
+// src/commands/config-validate.ts
+async function runConfigValidate() {
+  const config2 = loadConfig();
+  const hasConfig = Object.keys(config2).length > 0;
+  console.log("");
+  if (!hasConfig) {
+    console.log(chalk5.dim("  No .inspecto.json found in current directory. Showing all defaults.\n"));
+  } else {
+    console.log(chalk5.bold("  .inspecto.json") + chalk5.dim(" \u2014 effective configuration\n"));
+  }
+  const thresholdTable = new Table4({
+    head: ["Metric", "healthy", "warning", "Source"].map((h) => chalk5.dim(h)),
+    style: { head: [], border: [], "padding-left": 2, "padding-right": 2 },
+    chars: {
+      top: "\u2500",
+      "top-mid": "\u2500",
+      "top-left": "  ",
+      "top-right": "",
+      bottom: "\u2500",
+      "bottom-mid": "\u2500",
+      "bottom-left": "  ",
+      "bottom-right": "",
+      left: "  ",
+      "left-mid": "  ",
+      mid: "\u2500",
+      "mid-mid": "\u2500",
+      right: "",
+      "right-mid": "",
+      middle: "  "
+    }
+  });
+  const thresholdEntries = [
+    ["readsPerEdit", "reads-per-edit"],
+    ["rewriteRatio", "rewrite-ratio"],
+    ["cacheHitRate", "cache-hit-rate"],
+    ["taskCompletion", "task-completion"],
+    ["retryDensity", "retry-density"],
+    ["toolDiversity", "tool-diversity"],
+    ["tokensPerEdit", "tokens-per-edit"],
+    ["sessionCost", "session-cost"]
+  ];
+  for (const [key, label] of thresholdEntries) {
+    const override = config2.thresholds?.[key];
+    const def = DEFAULT_THRESHOLDS[key];
+    const effective = { ...def, ...override };
+    const source = override ? chalk5.green("config") : chalk5.dim("default");
+    thresholdTable.push([label, String(effective.healthy), String(effective.warning), source]);
+  }
+  console.log(chalk5.bold("  Thresholds"));
+  console.log(thresholdTable.toString());
+  console.log("");
+  const weightTable = new Table4({
+    head: ["Metric", "Weight", "Source"].map((h) => chalk5.dim(h)),
+    style: { head: [], border: [], "padding-left": 2, "padding-right": 2 },
+    chars: {
+      top: "\u2500",
+      "top-mid": "\u2500",
+      "top-left": "  ",
+      "top-right": "",
+      bottom: "\u2500",
+      "bottom-mid": "\u2500",
+      "bottom-left": "  ",
+      "bottom-right": "",
+      left: "  ",
+      "left-mid": "  ",
+      mid: "\u2500",
+      "mid-mid": "\u2500",
+      right: "",
+      "right-mid": "",
+      middle: "  "
+    }
+  });
+  const weightEntries = [
+    ["readsPerEdit", "reads-per-edit"],
+    ["rewriteRatio", "rewrite-ratio"],
+    ["cacheHitRate", "cache-hit-rate"],
+    ["taskCompletion", "task-completion"],
+    ["retryDensity", "retry-density"],
+    ["toolDiversity", "tool-diversity"],
+    ["tokensPerEdit", "tokens-per-edit"]
+  ];
+  let configuredWeightSum = 0;
+  for (const [key] of weightEntries) {
+    configuredWeightSum += config2.weights?.[key] ?? DEFAULT_WEIGHTS[key];
+  }
+  for (const [key, label] of weightEntries) {
+    const override = config2.weights?.[key];
+    const effective = override ?? DEFAULT_WEIGHTS[key];
+    const source = override !== void 0 ? chalk5.green("config") : chalk5.dim("default");
+    weightTable.push([label, effective.toFixed(2), source]);
+  }
+  console.log(chalk5.bold("  Weights") + chalk5.dim(` (configurable sum: ${configuredWeightSum.toFixed(2)})`));
+  console.log(weightTable.toString());
+  console.log("");
+  if (config2.dataDir || config2.defaultProject) {
+    console.log(chalk5.bold("  Other settings"));
+    if (config2.dataDir) {
+      console.log(`  ${chalk5.dim("dataDir")}        ${config2.dataDir}  ${chalk5.green("(config)")}`);
+    }
+    if (config2.defaultProject) {
+      console.log(`  ${chalk5.dim("defaultProject")} ${config2.defaultProject}  ${chalk5.green("(config)")}`);
+    }
+    console.log("");
+  }
+}
+
 // src/index.ts
 var program = new Command();
 program.name("inspecto").description("Claude Code session quality analyzer \u2014 grade sessions, detect regressions, catch cache bugs").version(VERSION);
-program.command("audit", { isDefault: true }).description("Grade the most recent Claude Code session").option("--json", "Output as JSON").option("--verbose", "Show per-message breakdown").option("--data-dir <path>", "Custom Claude data directory").option("--project <name>", "Filter to a specific project").action(async (options) => {
+program.command("audit", { isDefault: true }).description("Grade the most recent Claude Code session").option("--json", "Output as JSON").option("--format <format>", "Output format: json, csv").option("--verbose", "Show per-message breakdown").option("--data-dir <path>", "Custom Claude data directory").option("--project <name>", "Filter to a specific project").option("--no-fail", "Always exit 0, even for D/F grades").action(async (options) => {
   try {
     await runAudit(options);
   } catch (error) {
     handleError(error);
   }
 });
-program.command("trend").description("Analyze quality trends and detect regressions over time").option("--since <duration>", "Time range: 7d, 14d, 30d", "7d").option("--json", "Output as JSON").option("--data-dir <path>", "Custom Claude data directory").option("--project <name>", "Filter to a specific project").action(async (options) => {
+program.command("trend").description("Analyze quality trends and detect regressions over time").option("--since <duration>", "Time range: 7d, 14d, 30d", "7d").option("--json", "Output as JSON").option("--format <format>", "Output format: json, csv").option("--data-dir <path>", "Custom Claude data directory").option("--project <name>", "Filter to a specific project").option("--no-fail", "Always exit 0, even on regressions").action(async (options) => {
   try {
     await runTrend(options);
   } catch (error) {
     handleError(error);
   }
 });
-program.command("cache-check").description("Detect prompt cache bugs that inflate token costs").option("--since <duration>", "Time range: 7d, 14d, 30d", "7d").option("--json", "Output as JSON").option("--data-dir <path>", "Custom Claude data directory").action(async (options) => {
+program.command("cache-check").description("Detect prompt cache bugs that inflate token costs").option("--since <duration>", "Time range: 7d, 14d, 30d", "7d").option("--json", "Output as JSON").option("--data-dir <path>", "Custom Claude data directory").option("--no-fail", "Always exit 0, even when anomalies are detected").action(async (options) => {
   try {
     await runCacheCheck(options);
   } catch (error) {
     handleError(error);
   }
 });
-program.command("compare").description("Compare quality metrics across projects").requiredOption("--projects <names>", "Comma-separated project names").option("--json", "Output as JSON").option("--data-dir <path>", "Custom Claude data directory").option("--since <duration>", "Time range: 7d, 14d, 30d").action(async (options) => {
+program.command("compare").description("Compare quality metrics across projects").requiredOption("--projects <names>", "Comma-separated project names").option("--json", "Output as JSON").option("--data-dir <path>", "Custom Claude data directory").option("--since <duration>", "Time range: 7d, 14d, 30d").option("--no-fail", "No-op (compare always exits 0)").action(async (options) => {
   try {
     await runCompare(options);
   } catch (error) {
     handleError(error);
   }
 });
+program.command("list").description("List discovered projects and sessions").option("--sessions", "Show 20 most recent sessions instead of projects").option("--project <name>", "Filter to sessions for a specific project").option("--data-dir <path>", "Custom Claude data directory").action(async (options) => {
+  try {
+    await runList(options);
+  } catch (error) {
+    handleError(error);
+  }
+});
+var config = program.command("config").description("Manage inspecto configuration");
+config.command("validate").description("Show effective configuration merged from .inspecto.json and defaults").action(async () => {
+  try {
+    await runConfigValidate();
+  } catch (error) {
+    handleError(error);
+  }
+});
 var cache = program.command("cache").description("Manage the inspecto grade cache");
 cache.command("clear").description("Delete the grade cache file (~/.claude/inspecto-cache.db)").action(async () => {
   try {