avorelo 0.1.0

package/scripts/lib/metrics.js

@@ -0,0 +1,699 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { buildOutcomeEvent, appendOutcomeEvents } = require("./unified-events");
+const { getEffectiveConfig } = require("./config");
+const { normalizeAttribution } = require("./attribution");
+
+const SLICE1_RECOMMENDATION_IDS = new Set([
+  "REC_LOOP_REPLAN",
+  "REC_RETRY_SUPPRESSION",
+  "REC_PROMPT_ENVELOPE",
+  "REC_ENABLE_TOOL_SEARCH",
+  "REC_MCP_OUTPUT_CAP",
+  "REC_PRECOMPACT_EVIDENCE",
+]);
+
+function metricsPath(cwd) {
+  return path.join(cwd, ".claude", "cco", "metrics", "metrics.jsonl");
+}
+
+function appendJsonl(file, obj) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.appendFileSync(file, JSON.stringify(obj) + "\n", "utf8");
+}
+
+function logMetric(cwd, entry) {
+  const line = {
+    ts: new Date().toISOString(),
+    sessionId: entry.sessionId || "unknown",
+    event: entry.event,
+    tool: entry.tool || null,
+    action: entry.action || null,
+    reasonCodes: entry.reasonCodes || [],
+    meta: entry.meta || {},
+  };
+  const attribution = normalizeAttribution({ ...entry, ...line });
+  if (attribution) line.attribution = attribution;
+
+  appendJsonl(metricsPath(cwd), line);
+
+  try {
+    if (line.meta?.skipOutcomeEvent) return;
+    const effective = getEffectiveConfig(cwd)?.config || {};
+    const projectId = String(line.meta?.projectId || effective.cloud?.projectId || path.basename(cwd).toLowerCase());
+    const userId = String(line.meta?.userId || process.env.CCO_USER_ID || "local-user");
+    const outcome = buildOutcomeEvent({
+      metric: line,
+      platform: "claude",
+      projectId,
+      repoId: projectId,
+      userId,
+    });
+    appendOutcomeEvents(cwd, [outcome]);
+  } catch {
+    // Outcome instrumentation must never break runtime metrics.
+  }
+}
+
+function readAllMetrics(cwd) {
+  const p = metricsPath(cwd);
+  if (!fs.existsSync(p)) return [];
+  return fs
+    .readFileSync(p, "utf8")
+    .split("\n")
+    .filter(Boolean)
+    .map((ln) => {
+      try {
+        return JSON.parse(ln);
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean);
+}
+
+function readSessionMetrics(cwd, sessionId) {
+  return readAllMetrics(cwd).filter((x) => x && x.sessionId === sessionId);
+}
+
+function confidenceFromScore(score) {
+  if (score >= 10) return "high";
+  if (score >= 5) return "medium";
+  return "low";
+}
+
+function percentile(values, p) {
+  if (!Array.isArray(values) || values.length === 0) return 0;
+  const sorted = values.slice().sort((a, b) => a - b);
+  const idx = Math.min(sorted.length - 1, Math.max(0, Math.floor((p / 100) * (sorted.length - 1))));
+  return sorted[idx];
+}
+
+function weightsForProfile(profile) {
+  const p = profile || "balanced";
+  if (p === "cost-saver") return { cost: 1.35, quality: 0.85, security: 1.0, ux: 0.9 };
+  if (p === "quality") return { cost: 0.85, quality: 1.35, security: 1.25, ux: 1.1 };
+  return { cost: 1.0, quality: 1.0, security: 1.0, ux: 1.0 };
+}
+
+function buildRecommendationTraces(signals, profile) {
+  const w = weightsForProfile(profile);
+
+  const recs = [
+    {
+      id: "REC_MCP_OUTPUT_CAP",
+      text: "Tune MAX_MCP_OUTPUT_TOKENS and use pagination/filters for noisy tools.",
+      score: Math.round((signals.largeOutputsStored * 2 + Math.floor((signals.outputBytesAvg || 0) / 25000)) * w.cost),
+      signalEvidence: [`largeOutputsStored=${signals.largeOutputsStored}`, `avgOutputBytes=${signals.outputBytesAvg || 0}`, `p95OutputBytes=${signals.outputBytesP95 || 0}`],
+      estimatedImpact: "Lower context pressure and fewer compactions.",
+      actionPath: "settings -> MAX_MCP_OUTPUT_TOKENS",
+      triggerEvent: "PostToolUse",
+      saturationGroup: "cost",
+    },
+    {
+      id: "REC_ENABLE_TOOL_SEARCH",
+      text: "Enable ENABLE_TOOL_SEARCH to reduce idle MCP schema overhead.",
+      score: Math.round((Math.max(0, signals.mcpToolCalls - 3) + signals.mcpServerCount) * w.cost),
+      signalEvidence: [`mcpToolCalls=${signals.mcpToolCalls}`, `mcpServerCount=${signals.mcpServerCount}`],
+      estimatedImpact: "Lower token overhead for MCP-heavy workflows.",
+      actionPath: "settings -> ENABLE_TOOL_SEARCH",
+      triggerEvent: "PreToolUse",
+      saturationGroup: "cost",
+    },
+    {
+      id: "REC_MCP_MATCHER_NARROW",
+      text: "Narrow MCP matchers to active servers to reduce hook routing overhead.",
+      score: Math.round((signals.mcpServerCount > 1 ? signals.mcpServerCount + 2 : 0) * w.cost),
+      signalEvidence: [`mcpServerCount=${signals.mcpServerCount}`],
+      estimatedImpact: "Lower hook overhead in multi-server repos.",
+      actionPath: "hooks -> matcher narrowing (mcp__<server>__.*)",
+      triggerEvent: "PreToolUse",
+      saturationGroup: "cost",
+    },
+    {
+      id: "REC_CLI_OVER_MCP",
+      text: "Prefer equivalent CLI tools over MCP where practical for lower context overhead.",
+      score: Math.round((signals.mcpToolCalls > 6 ? Math.ceil(signals.mcpToolCalls / 3) : 0) * w.cost),
+      signalEvidence: [`mcpToolCalls=${signals.mcpToolCalls}`, `cliToolCalls=${signals.cliToolCalls}`],
+      estimatedImpact: "Reduce schema overhead and permission churn.",
+      actionPath: "workflow -> choose CLI when equivalent",
+      triggerEvent: "PreToolUse",
+      saturationGroup: "cost",
+    },
+    {
+      id: "REC_LOOP_REPLAN",
+      text: "Repeated loops detected. Add stricter DoD and split tasks into smaller chunks.",
+      score: Math.round((signals.loopsInterrupted * 3 + signals.failRetryGuards * 2) * w.quality),
+      signalEvidence: [`loopsInterrupted=${signals.loopsInterrupted}`, `failRetryGuards=${signals.failRetryGuards}`],
+      estimatedImpact: "Reduce retries and wasted tool calls.",
+      actionPath: "prompt-quality -> DoD/output format/constraints",
+      triggerEvent: "PreToolUse",
+      saturationGroup: "quality",
+    },
+    {
+      id: "REC_RETRY_SUPPRESSION",
+      text: "On repeated failures, summarize stderr and re-plan before retrying tools.",
+      score: Math.round((signals.postToolFailures * 2 + signals.failRetryGuards * 2) * w.quality),
+      signalEvidence: [`postToolFailures=${signals.postToolFailures}`, `failRetryGuards=${signals.failRetryGuards}`],
+      estimatedImpact: "Prevent runaway retries and lower cycle time.",
+      actionPath: "PostToolUseFailure -> re-plan policy",
+      triggerEvent: "PostToolUseFailure",
+      saturationGroup: "quality",
+    },
+    {
+      id: "REC_PROMPT_ENVELOPE",
+      text: "Prompt lint opportunities detected. Keep DoD, output format, and constraints explicit.",
+      score: Math.round((signals.promptLintInjects + Math.max(0, signals.promptBypass - 1)) * w.quality),
+      signalEvidence: [`promptLintInjects=${signals.promptLintInjects}`, `promptBypass=${signals.promptBypass}`],
+      estimatedImpact: "Fewer clarification turns and faster completion.",
+      actionPath: "UserPromptSubmit -> quality envelope",
+      triggerEvent: "UserPromptSubmit",
+      saturationGroup: "quality",
+    },
+    {
+      id: "REC_THINKING_BUDGET",
+      text: "Set profile-aware MAX_THINKING_TOKENS for predictable cost/quality behavior.",
+      score: Math.round((signals.toolCalls > 15 ? 3 : signals.toolCalls > 8 ? 2 : 1) * w.cost),
+      signalEvidence: [`toolCalls=${signals.toolCalls}`, `profile=${profile || "balanced"}`],
+      estimatedImpact: "More predictable spend and latency.",
+      actionPath: "settings -> MAX_THINKING_TOKENS",
+      triggerEvent: "PreToolUse",
+      saturationGroup: "cost",
+    },
+    {
+      id: "REC_SECURITY_AUDIT",
+      text: "Security risk signals observed. Run /cco-audit and review remediation jobs.",
+      score: Math.round((signals.riskyIntercepts * 3 + signals.remediationJobs * 2 + signals.suppressionEvents) * w.security),
+      signalEvidence: [`riskyIntercepts=${signals.riskyIntercepts}`, `remediationJobs=${signals.remediationJobs}`, `suppressionEvents=${signals.suppressionEvents}`],
+      estimatedImpact: "Lower supply-chain and command execution risk.",
+      actionPath: "security -> /cco-audit -> remediation",
+      triggerEvent: "PostToolUse",
+      saturationGroup: "security",
+    },
+    {
+      id: "REC_TRUST_SURFACE_REVIEW",
+      text: "Trust-surface alerts detected. Review changed skills/agents/hooks before execution.",
+      score: Math.round((signals.trustAlerts * 3 + signals.worktreeEvents) * w.security),
+      signalEvidence: [`trustAlerts=${signals.trustAlerts}`, `worktreeEvents=${signals.worktreeEvents}`],
+      estimatedImpact: "Reduce malicious skill/plugin supply-chain risk.",
+      actionPath: "trust-audit -> review unknown/untrusted files",
+      triggerEvent: "WorktreeCreate",
+      saturationGroup: "security",
+    },
+    {
+      id: "REC_PERMISSION_CONSOLIDATION",
+      text: "Permission fatigue observed. Consolidate repeated safe approvals and narrow high-risk prompts.",
+      score: Math.round((signals.permissionRequests + signals.permissionAsks - signals.permissionFatigueAllows) * w.ux),
+      signalEvidence: [
+        `permissionRequests=${signals.permissionRequests}`,
+        `permissionAsks=${signals.permissionAsks}`,
+        `fatigueConsolidations=${signals.permissionFatigueAllows}`,
+      ],
+      estimatedImpact: "Lower approval friction while preserving safeguards.",
+      actionPath: "PermissionRequest -> consolidation policy",
+      triggerEvent: "PermissionRequest",
+      saturationGroup: "ux",
+    },
+    {
+      id: "REC_PRECOMPACT_EVIDENCE",
+      text: "Use PreCompact snapshots and evidence bundles before long sessions compact.",
+      score: Math.round((signals.precompactSnapshots > 0 ? 2 : 4) * w.quality),
+      signalEvidence: [`precompactSnapshots=${signals.precompactSnapshots}`],
+      estimatedImpact: "Reduce context-loss regressions after compaction.",
+      actionPath: "PreCompact -> snapshot/evidence bundle",
+      triggerEvent: "PreCompact",
+      saturationGroup: "quality",
+    },
+    {
+      id: "REC_IDLE_DEEP_SCAN",
+      text: "Use idle windows for deferred scans and trust refresh tasks.",
+      score: Math.round((signals.teammateIdleEvents + signals.notificationsDeduped) * w.ux),
+      signalEvidence: [`teammateIdleEvents=${signals.teammateIdleEvents}`, `notificationsDeduped=${signals.notificationsDeduped}`],
+      estimatedImpact: "Improved risk freshness without interrupting active work.",
+      actionPath: "TeammateIdle -> deferred scan",
+      triggerEvent: "TeammateIdle",
+      saturationGroup: "ux",
+    },
+    {
+      id: "REC_WORKTREE_POLICY_RESCAN",
+      text: "Worktree changes detected. Re-run trust and security checks on creation/removal.",
+      score: Math.round((signals.worktreeEvents > 0 ? signals.worktreeEvents + 1 : 0) * w.security),
+      signalEvidence: [`worktreeEvents=${signals.worktreeEvents}`],
+      estimatedImpact: "Prevent policy drift across ephemeral worktrees.",
+      actionPath: "WorktreeCreate/WorktreeRemove -> trust audit",
+      triggerEvent: "WorktreeCreate",
+      saturationGroup: "security",
+    },
+    {
+      id: "REC_COMPACT_PRESSURE",
+      text: "Compact pressure is high. Trigger /compact earlier and rely on memory snapshots.",
+      score: Math.round((signals.compactPressureEvents > 1 ? signals.compactPressureEvents * 2 : 0) * w.quality),
+      signalEvidence: [`compactPressureEvents=${signals.compactPressureEvents}`],
+      estimatedImpact: "Stabilize long sessions and lower context churn.",
+      actionPath: "compact-discipline -> precompact snapshot + focused resume",
+      triggerEvent: "PreCompact",
+      saturationGroup: "quality",
+    },
+    {
+      id: "REC_BATCH_CANDIDATE",
+      text: "High repetition detected. Move repeated jobs to headless/API batch mode.",
+      score: Math.round((signals.batchCandidates + signals.batchJobsCreated) * w.cost),
+      signalEvidence: [`batchCandidates=${signals.batchCandidates}`, `batchJobsCreated=${signals.batchJobsCreated}`],
+      estimatedImpact: "Lower interactive overhead and improve throughput.",
+      actionPath: "batch -> cco-batch create",
+      triggerEvent: "TaskCompleted",
+      saturationGroup: "cost",
+    },
+    {
+      id: "REC_HTTP_HOOK_TEMPLATE",
+      text: "Use direct HTTP hook actions with HMAC and timeout policies for integrations.",
+      score: Math.round((signals.httpHookActions + (signals.cloudSyncs === 0 ? 1 : 0)) * w.ux),
+      signalEvidence: [`httpHookActions=${signals.httpHookActions}`, `cloudSyncs=${signals.cloudSyncs}`],
+      estimatedImpact: "Safer non-Python hook integrations with auditable controls.",
+      actionPath: "http-hook -> cco-http-hook endpoint=...",
+      triggerEvent: "Notification",
+      saturationGroup: "ux",
+    },
+    {
+      id: "REC_VOICE_ALPHA",
+      text: "Enable edge-first voice alpha for low-latency command routing.",
+      score: Math.round((signals.voiceCommands > 0 ? 2 : 1) * w.ux),
+      signalEvidence: [`voiceCommands=${signals.voiceCommands}`],
+      estimatedImpact: "Faster command entry with confirmation on risky intents.",
+      actionPath: "voice -> cco-voice transcript=...",
+      triggerEvent: "Notification",
+      saturationGroup: "ux",
+    },
+  ];
+
+  return recs
+    .map((r) => ({
+      ...r,
+      recommendationId: r.id,
+      confidence: confidenceFromScore(r.score),
+      weight: r.score,
+      memoryEvidence: [],
+    }))
+    .sort((a, b) => b.score - a.score)
+    .slice(0, 14);
+}
+
+function filterSlice1RecommendationTraces(traces) {
+  return (Array.isArray(traces) ? traces : [])
+    .filter((t) => SLICE1_RECOMMENDATION_IDS.has(String(t.id || t.recommendationId || "")))
+    .slice(0, 5);
+}
+
+function rankRecommendations(signals, profile) {
+  return filterSlice1RecommendationTraces(buildRecommendationTraces(signals, profile)).map((x) => x.text);
+}
+
+function buildSignalSummary(metrics, profile) {
+  const toolCalls = metrics.filter((m) => m.event === "PreToolUse").length;
+  const mcpToolCalls = metrics.filter((m) => String(m.tool || "").startsWith("mcp__")).length;
+  const cliToolCalls = metrics.filter((m) => m.event === "PreToolUse" && m.tool === "Bash").length;
+
+  const loopsInterrupted = metrics.filter((m) => (m.reasonCodes || []).includes("LOOP_REPEATED_TOOL")).length;
+  const riskyIntercepts = metrics.filter((m) => (m.reasonCodes || []).some((c) => String(c).startsWith("SEC_"))).length;
+  const largeOutputsStored = metrics.filter((m) => (m.reasonCodes || []).includes("CTX_LARGE_OUTPUT")).length;
+  const suppressionEvents = metrics.filter((m) => (m.reasonCodes || []).includes("SEC_SUPPRESSION_AUDIT")).length;
+  const trustAlerts = metrics.filter((m) => (m.reasonCodes || []).includes("SEC_TRUST_UNKNOWN_HIGH") || (m.reasonCodes || []).includes("SEC_TRUST_AUDIT")).length;
+  const failRetryGuards = metrics.filter((m) => (m.reasonCodes || []).includes("FAIL_RETRY_GUARD")).length;
+  const scanSkips = metrics.filter((m) => (m.reasonCodes || []).includes("CTX_SCAN_SKIPPED_UNCHANGED")).length;
+
+  const permissionRequests = metrics.filter((m) => m.event === "PermissionRequest").length;
+  const permissionAsks = metrics.filter((m) => m.event === "PermissionRequest" && m.action === "ask").length;
+  const permissionDenies = metrics.filter((m) => m.event === "PermissionRequest" && m.action === "deny").length;
+  const permissionFatigueAllows = metrics.filter((m) => (m.reasonCodes || []).includes("PERM_FATIGUE_CONSOLIDATED")).length;
+
+  const notificationsDeduped = metrics.filter((m) => (m.reasonCodes || []).includes("NOTIF_DEDUPED")).length;
+  const subagentStarts = metrics.filter((m) => m.event === "SubagentStart").length;
+  const subagentStops = metrics.filter((m) => m.event === "SubagentStop").length;
+  const subagentPressure = metrics.filter((m) => (m.reasonCodes || []).includes("CTX_COST_PRESSURE_SUBAGENT")).length;
+  const stopSnapshots = metrics.filter((m) => (m.reasonCodes || []).includes("STOP_SNAPSHOT")).length;
+  const teammateIdleEvents = metrics.filter((m) => m.event === "TeammateIdle").length;
+  const taskCompletedEvents = metrics.filter((m) => m.event === "TaskCompleted").length;
+  const worktreeEvents = metrics.filter((m) => m.event === "WorktreeCreate" || m.event === "WorktreeRemove").length;
+  const precompactSnapshots = metrics.filter((m) => (m.reasonCodes || []).includes("CTX_SNAPSHOT")).length;
+
+  const promptLintInjects = metrics.filter((m) => m.event === "UserPromptSubmit" && m.action === "injectAdditionalContext").length;
+  const promptBypass = metrics.filter((m) => (m.reasonCodes || []).includes("PROMPT_BYPASS")).length;
+  const remediationJobs = metrics.filter((m) => (m.reasonCodes || []).includes("SEC_REMEDIATION_JOB_CREATED")).length;
+  const postToolFailures = metrics.filter((m) => m.event === "PostToolUseFailure").length;
+
+  const batchJobsCreated = metrics.filter((m) => (m.reasonCodes || []).includes("BATCH_JOB_CREATED")).length;
+  const batchJobsCompleted = metrics.filter((m) => (m.reasonCodes || []).includes("BATCH_JOB_COMPLETED")).length;
+  const cloudSyncs = metrics.filter((m) => m.event === "CloudSync").length;
+  const httpHookActions = metrics.filter((m) => m.event === "HttpHookAction").length;
+  const voiceCommands = metrics.filter((m) => m.event === "VoiceCommand").length;
+
+  const largeOutputBytes = metrics
+    .filter((m) => (m.reasonCodes || []).includes("CTX_LARGE_OUTPUT"))
+    .map((m) => Number(m.meta?.bytes || 0))
+    .filter((x) => Number.isFinite(x) && x > 0);
+
+  const outputBytesAvg = largeOutputBytes.length
+    ? Math.round(largeOutputBytes.reduce((a, b) => a + b, 0) / largeOutputBytes.length)
+    : 0;
+
+  const outputBytesP95 = percentile(largeOutputBytes, 95);
+
+  const mcpServerUsage = {};
+  metrics.forEach((m) => {
+    const tool = String(m.tool || "");
+    if (!tool.startsWith("mcp__")) return;
+    const server = tool.split("__")[1] || "unknown";
+    mcpServerUsage[server] = (mcpServerUsage[server] || 0) + 1;
+  });
+
+  const mcpServerCount = Object.keys(mcpServerUsage).length;
+  const compactPressureEvents = largeOutputsStored + failRetryGuards + Math.max(0, loopsInterrupted - precompactSnapshots);
+  const batchCandidates = Math.max(0, loopsInterrupted + postToolFailures - batchJobsCreated);
+
+  const rawSignals = {
+    toolCalls,
+    mcpToolCalls,
+    cliToolCalls,
+    loopsInterrupted,
+    riskyIntercepts,
+    largeOutputsStored,
+    suppressionEvents,
+    trustAlerts,
+    failRetryGuards,
+    scanSkips,
+    permissionRequests,
+    permissionAsks,
+    permissionDenies,
+    permissionFatigueAllows,
+    notificationsDeduped,
+    subagentStarts,
+    subagentStops,
+    subagentPressure,
+    stopSnapshots,
+    teammateIdleEvents,
+    taskCompletedEvents,
+    worktreeEvents,
+    precompactSnapshots,
+    promptLintInjects,
+    promptBypass,
+    remediationJobs,
+    postToolFailures,
+    outputBytesAvg,
+    outputBytesP95,
+    mcpServerUsage,
+    mcpServerCount,
+    compactPressureEvents,
+    batchCandidates,
+    batchJobsCreated,
+    batchJobsCompleted,
+    cloudSyncs,
+    httpHookActions,
+    voiceCommands,
+  };
+
+  const recommendationTraces = filterSlice1RecommendationTraces(buildRecommendationTraces(rawSignals, profile));
+
+  return {
+    ...rawSignals,
+    recommendationTraces,
+    recommendations: recommendationTraces.map((x) => x.text),
+  };
+}
+
+// SkillAudit aggregation — surfaces Skill Contract execution trust/proof signals.
+function buildSkillAuditSummary(metrics) {
+  const auditEvents = metrics.filter((m) => m.event === "SkillAudit");
+  const skillAuditCount = auditEvents.length;
+
+  if (skillAuditCount === 0) {
+    return {
+      skillAuditCount: 0,
+      totalSkillManualStepsSaved: 0,
+      allProofSatisfiedCount: 0,
+      proofStatusCounts: { missing: 0, partial: 0, satisfied: 0 },
+      selectedSkillCounts: {},
+      topSelectedSkills: [],
+    };
+  }
+
+  let totalSkillManualStepsSaved = 0;
+  let allProofSatisfiedCount = 0;
+  const proofStatusCounts = { missing: 0, partial: 0, satisfied: 0 };
+  const selectedSkillCounts = {};
+
+  for (const m of auditEvents) {
+    const meta = m.meta || {};
+
+    // totalManualStepsSaved — conservative, already capped at 3/skill in evidence.ts
+    const saved = Number(meta.totalManualStepsSaved);
+    if (Number.isFinite(saved) && saved > 0) {
+      totalSkillManualStepsSaved += saved;
+    }
+
+    // allProofSatisfied flag — only meaningful when skills were actually selected.
+    // Vacuous truth (selectedSkillIds: []) must not inflate the count.
+    if (
+      meta.allProofSatisfied === true &&
+      Array.isArray(meta.selectedSkillIds) &&
+      meta.selectedSkillIds.length > 0
+    ) {
+      allProofSatisfiedCount++;
+    }
+
+    // proofStatuses per-skill per-event
+    if (Array.isArray(meta.proofStatuses)) {
+      for (const ps of meta.proofStatuses) {
+        const status = String(ps.proofStatus || "");
+        if (status === "missing" || status === "partial" || status === "satisfied") {
+          proofStatusCounts[status]++;
+        }
+      }
+    }
+
+    // selected skill ids
+    if (Array.isArray(meta.selectedSkillIds)) {
+      for (const id of meta.selectedSkillIds) {
+        const key = String(id || "");
+        if (key) selectedSkillCounts[key] = (selectedSkillCounts[key] || 0) + 1;
+      }
+    }
+  }
+
+  const topSelectedSkills = Object.keys(selectedSkillCounts)
+    .sort((a, b) => selectedSkillCounts[b] - selectedSkillCounts[a])
+    .slice(0, 5);
+
+  return {
+    skillAuditCount,
+    totalSkillManualStepsSaved,
+    allProofSatisfiedCount,
+    proofStatusCounts,
+    selectedSkillCounts,
+    topSelectedSkills,
+  };
+}
+
+// Canonical savings heuristic for active CJS runtime surfaces.
+function buildSavingsFirstSummary(signals) {
+  const loopsDetected = Number(signals.loopsInterrupted || 0) + Number(signals.failRetryGuards || 0);
+  const loopsPrevented = Number(signals.loopsInterrupted || 0);
+  const outputsTrimmed = Number(signals.largeOutputsStored || 0);
+  const estimatedMinutesSaved = Math.max(0, loopsPrevented * 3 + outputsTrimmed);
+  const density = loopsPrevented + outputsTrimmed + Number(signals.riskyIntercepts || 0);
+  const confidenceLabel = density >= 6 ? "high" : density >= 2 ? "medium" : "low";
+
+  return {
+    loopsDetected,
+    loopsPrevented,
+    outputsTrimmed,
+    estimatedMinutesSaved,
+    confidenceLabel,
+  };
+}
+
+function buildSavingsSummaryFromMetrics(metrics, profile = "balanced") {
+  return buildSavingsFirstSummary(buildSignalSummary(metrics, profile));
+}
+
+function sessionSummaryFromMetrics(sessionId, metrics, profile) {
+  const signals = buildSignalSummary(metrics, profile);
+
+  const reasonCounts = {};
+  metrics.flatMap((m) => m.reasonCodes || []).forEach((r) => {
+    reasonCounts[r] = (reasonCounts[r] || 0) + 1;
+  });
+  const topReasonCodes = Object.keys(reasonCounts)
+    .sort((a, b) => reasonCounts[b] - reasonCounts[a])
+    .slice(0, 3);
+
+  const durationEstimateMin = Math.max(1, Math.round(metrics.length * 0.4));
+  const endTs =
+    metrics
+      .map((m) => Date.parse(m.ts || 0))
+      .filter((n) => Number.isFinite(n))
+      .sort((a, b) => b - a)[0] || 0;
+
+  return {
+    sessionId,
+    durationEstimateMin,
+    ...signals,
+    savingsFirstSummary: buildSavingsSummaryFromMetrics(metrics, profile),
+    skillAuditSummary: buildSkillAuditSummary(metrics),
+    topReasonCodes,
+    endTs,
+  };
+}
+
+function summarizeLastSessions(cwd, limit = 7, profile = "balanced") {
+  const all = readAllMetrics(cwd);
+  const bySession = new Map();
+  all.forEach((m) => {
+    const id = m.sessionId || "unknown";
+    if (!bySession.has(id)) bySession.set(id, []);
+    bySession.get(id).push(m);
+  });
+
+  return Array.from(bySession.entries())
+    .map(([sessionId, metrics]) => sessionSummaryFromMetrics(sessionId, metrics, profile))
+    .sort((a, b) => b.endTs - a.endTs)
+    .slice(0, limit);
+}
+
+function weeklyRollup(cwd, days = 7, profile = "balanced") {
+  const all = readAllMetrics(cwd);
+  const cutoff = Date.now() - days * 24 * 60 * 60 * 1000;
+  const recent = all.filter((m) => {
+    const ts = Date.parse(m.ts || 0);
+    return Number.isFinite(ts) && ts >= cutoff;
+  });
+
+  const sessions = new Set(recent.map((m) => m.sessionId || "unknown"));
+  const signals = buildSignalSummary(recent, profile);
+
+  const reasonCounts = {};
+  recent.flatMap((m) => m.reasonCodes || []).forEach((r) => {
+    reasonCounts[r] = (reasonCounts[r] || 0) + 1;
+  });
+  const topReasonCodes = Object.keys(reasonCounts)
+    .sort((a, b) => reasonCounts[b] - reasonCounts[a])
+    .slice(0, 5);
+
+  return {
+    periodDays: days,
+    sessions: sessions.size,
+    ...signals,
+    savingsFirstSummary: buildSavingsSummaryFromMetrics(recent, profile),
+    skillAuditSummary: buildSkillAuditSummary(recent),
+    topReasonCodes,
+  };
+}
+
+function teamSecurityRollup(cwd, days = 7) {
+  const weekly = weeklyRollup(cwd, days);
+  return {
+    periodDays: days,
+    riskyIntercepts: weekly.riskyIntercepts,
+    trustAlerts: weekly.trustAlerts,
+    suppressionEvents: weekly.suppressionEvents,
+    topReasonCodes: weekly.topReasonCodes.filter((c) => String(c).startsWith("SEC_")),
+  };
+}
+
+function recordToolCallAndDetectLoop(cwd, sessionId, toolName) {
+  const statePath = path.join(cwd, ".claude", "cco", "state", `toolbuf-${sessionId}.json`);
+  let buf = [];
+  try {
+    buf = JSON.parse(fs.readFileSync(statePath, "utf8"));
+  } catch {
+    buf = [];
+  }
+
+  buf.push({ ts: Date.now(), tool: toolName });
+  if (buf.length > 12) buf = buf.slice(-12);
+  fs.mkdirSync(path.dirname(statePath), { recursive: true });
+  fs.writeFileSync(statePath, JSON.stringify(buf, null, 2), "utf8");
+
+  if (buf.length >= 8) {
+    const a = buf.slice(-4).map((x) => x.tool).join("|");
+    const b = buf.slice(-8, -4).map((x) => x.tool).join("|");
+    if (a === b) return { shouldInterrupt: true };
+  }
+  return null;
+}
+
+function buildSessionReportMarkdown({ sessionId, reason, metrics, profile = "balanced", recommendationDecision = null, memorySummary = null }) {
+  const s = sessionSummaryFromMetrics(sessionId, metrics, profile);
+  const displayed = recommendationDecision?.displayedRecommendations || s.recommendationTraces.slice(0, 5);
+  const nextBestAction = recommendationDecision?.nextBestAction || displayed[0]?.text || "Run /cco-optimize for proactive quick wins.";
+
+  return [
+    "# ClaudeCode Optimizer - Session Summary",
+    "",
+    `Session: ${sessionId}`,
+    `End reason: ${reason}`,
+    "",
+    "## Savings-first summary",
+    `- Loops detected: ${s.savingsFirstSummary.loopsDetected}`,
+    `- Loops prevented: ${s.savingsFirstSummary.loopsPrevented}`,
+    `- Outputs trimmed: ${s.savingsFirstSummary.outputsTrimmed}`,
+    `- Estimated minutes saved: ~${s.savingsFirstSummary.estimatedMinutesSaved}`,
+    `- Confidence: ${s.savingsFirstSummary.confidenceLabel}`,
+    "",
+    "## What happened",
+    `- Tool calls observed: ${s.toolCalls}`,
+    `- Loop interruptions: ${s.loopsInterrupted}`,
+    `- Large outputs stored: ${s.largeOutputsStored}`,
+    `- Risky command intercepts: ${s.riskyIntercepts}`,
+    memorySummary ? `- Memory efficiency score: ${memorySummary.memoryScore}` : "",
+    "",
+    "## Top recommended fixes",
+    ...displayed.slice(0, 5).map((r) => `- ${r.text} [confidence=${r.confidence}; path=${r.actionPath}]`),
+    `- Next best action: ${nextBestAction}`,
+    "",
+    // Skill contracts section — only emitted when SkillAudit events are present.
+    ...(s.skillAuditSummary.skillAuditCount > 0
+      ? [
+          "## Skill contracts",
+          `- ${s.skillAuditSummary.skillAuditCount} skill-audited session${s.skillAuditSummary.skillAuditCount !== 1 ? "s" : ""}`,
+          `- ${s.skillAuditSummary.totalSkillManualStepsSaved} manual steps saved (estimate)`,
+          `- proof satisfied: ${s.skillAuditSummary.allProofSatisfiedCount}/${s.skillAuditSummary.skillAuditCount}`,
+          s.skillAuditSummary.topSelectedSkills.length > 0
+            ? `- top skills: ${s.skillAuditSummary.topSelectedSkills.join(", ")}`
+            : "",
+          "",
+        ]
+      : []),
+    "## Notes",
+    "- Works locally first. Team integrations can come later.",
+    "- Get value before you connect tools.",
+    "- Bypass prompt lint by prefixing prompts with [cco:raw].",
+    "",
+  ].filter(Boolean).join("\n");
+}
+module.exports = {
+  logMetric,
+  readAllMetrics,
+  readSessionMetrics,
+  summarizeLastSessions,
+  weeklyRollup,
+  teamSecurityRollup,
+  rankRecommendations,
+  buildRecommendationTraces,
+  buildSavingsSummaryFromMetrics,
+  buildSkillAuditSummary,
+  recordToolCallAndDetectLoop,
+  buildSessionReportMarkdown,
+  percentile,
+};
+
+
+
+
+
+
+
+
+
+