avorelo 0.3.8 → 0.4.0-rc.2

package/scripts/lib/claude-session-evidence/index.js

@@ -0,0 +1,1027 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const { redactString } = require("../support-redaction");
+
+// --- Constants ---
+
+const CLAUDE_HOME = path.join(os.homedir(), ".claude");
+const SESSIONS_DIR = path.join(CLAUDE_HOME, "sessions");
+const PROJECTS_DIR = path.join(CLAUDE_HOME, "projects");
+
+const SECRET_PATTERNS = [
+  { re: /ghp_[A-Za-z0-9]{20,}/, code: "SEC_GH_TOKEN" },
+  { re: /gho_[A-Za-z0-9]{20,}/, code: "SEC_GH_OAUTH" },
+  { re: /github_pat_[A-Za-z0-9_]{20,}/, code: "SEC_GH_PAT" },
+  { re: /xoxb-[A-Za-z0-9\-]{20,}/, code: "SEC_SLACK_TOKEN" },
+  { re: /xoxp-[A-Za-z0-9\-]{20,}/, code: "SEC_SLACK_USER_TOKEN" },
+  { re: /AKIA[0-9A-Z]{16}/, code: "SEC_AWS_KEY" },
+  { re: /sk-[A-Za-z0-9]{20,}/, code: "SEC_OPENAI_KEY" },
+  { re: /sk-ant-[A-Za-z0-9\-]{20,}/, code: "SEC_ANTHROPIC_KEY" },
+  { re: /BEGIN (?:RSA |EC |DSA |OPENSSH )?PRIVATE KEY/, code: "SEC_PRIVATE_KEY" },
+  { re: /eyJ[A-Za-z0-9_-]{30,}\.[A-Za-z0-9_-]{30,}/, code: "SEC_JWT" },
+  { re: /(?:password|passwd|pwd)\s*[:=]\s*["'][^"']{4,}/i, code: "SEC_PASSWORD_LITERAL" },
+  { re: /(?:api[_-]?key|apikey)\s*[:=]\s*["'][^"']{8,}/i, code: "SEC_API_KEY_LITERAL" },
+];
+
+const FILE_TOUCHING_TOOLS = new Set(["Read", "Write", "Edit", "NotebookEdit"]);
+const COMMAND_TOOLS = new Set(["Bash", "PowerShell"]);
+const VALIDATION_COMMANDS = [
+  /\btest\b/i, /\bvitest\b/i, /\bjest\b/i, /\bpytest\b/i,
+  /\bnpm\s+test\b/i, /\bnpm\s+run\s+test/i, /\bnode\s+--test\b/i,
+  /\btsc\b/, /\btypecheck\b/i, /\blint\b/i, /\beslint\b/i,
+  /\bcheck\b/i, /\bverify\b/i, /\bvalidate\b/i,
+];
+const ERROR_PATTERNS = [
+  /error/i, /failed/i, /exception/i, /exit code [1-9]/i,
+  /ENOENT/i, /EPERM/i, /EACCES/i, /TypeError/i, /SyntaxError/i,
+];
+
+// --- Path redaction ---
+
+function redactHomePath(filePath) {
+  if (!filePath || typeof filePath !== "string") return filePath;
+  const home = os.homedir().replace(/\\/g, "/");
+  const normalized = filePath.replace(/\\/g, "/");
+  if (normalized.startsWith(home + "/") || normalized.startsWith(home + "\\")) {
+    return "~" + normalized.slice(home.length);
+  }
+  const homeWin = os.homedir();
+  if (filePath.startsWith(homeWin + "\\") || filePath.startsWith(homeWin + "/")) {
+    return "~" + filePath.slice(homeWin.length).replace(/\\/g, "/");
+  }
+  return filePath;
+}
+
+// --- JSONL Parser (defensive) ---
+
+function parseJsonlFile(filePath) {
+  const events = [];
+  let raw;
+  try {
+    raw = fs.readFileSync(filePath, "utf8");
+  } catch {
+    return events;
+  }
+  for (const line of raw.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      events.push(JSON.parse(trimmed));
+    } catch {
+      // malformed line — skip silently
+    }
+  }
+  return events;
+}
+
+// --- Discovery ---
+
+function discoverClaudeHome() {
+  const exists = fs.existsSync(CLAUDE_HOME);
+  const sessionsExist = fs.existsSync(SESSIONS_DIR);
+  const projectsExist = fs.existsSync(PROJECTS_DIR);
+  return { claudeHome: CLAUDE_HOME, exists, sessionsExist, projectsExist };
+}
+
+function discoverProjectKeys() {
+  if (!fs.existsSync(PROJECTS_DIR)) return [];
+  try {
+    return fs.readdirSync(PROJECTS_DIR).filter((name) => {
+      const full = path.join(PROJECTS_DIR, name);
+      return fs.statSync(full).isDirectory() || name.endsWith(".jsonl");
+    });
+  } catch {
+    return [];
+  }
+}
+
+function discoverSessionFiles(projectKey) {
+  const projectDir = path.join(PROJECTS_DIR, projectKey);
+  if (!fs.existsSync(projectDir)) return [];
+  try {
+    const entries = fs.readdirSync(projectDir);
+    return entries
+      .filter((e) => e.endsWith(".jsonl"))
+      .map((e) => ({
+        sessionId: e.replace(".jsonl", ""),
+        filePath: path.join(projectDir, e),
+        sizeBytes: fs.statSync(path.join(projectDir, e)).size,
+        mtimeMs: fs.statSync(path.join(projectDir, e)).mtimeMs,
+      }))
+      .sort((a, b) => b.mtimeMs - a.mtimeMs);
+  } catch {
+    return [];
+  }
+}
+
+function discoverActiveSessions() {
+  if (!fs.existsSync(SESSIONS_DIR)) return [];
+  try {
+    return fs.readdirSync(SESSIONS_DIR)
+      .filter((f) => f.endsWith(".json"))
+      .map((f) => {
+        try {
+          const data = JSON.parse(fs.readFileSync(path.join(SESSIONS_DIR, f), "utf8"));
+          return { pid: data.pid, sessionId: data.sessionId, cwd: data.cwd, startedAt: data.startedAt, version: data.version, entrypoint: data.entrypoint };
+        } catch {
+          return null;
+        }
+      })
+      .filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+// --- Secret scanning ---
+
+function scanForSecrets(text) {
+  if (!text || typeof text !== "string") return [];
+  const hits = [];
+  for (const { re, code } of SECRET_PATTERNS) {
+    if (re.test(text)) hits.push(code);
+  }
+  return hits;
+}
+
+function redactSecrets(text) {
+  if (!text || typeof text !== "string") return text;
+  let result = text;
+  for (const { re } of SECRET_PATTERNS) {
+    result = result.replace(new RegExp(re.source, re.flags + "g"), "[REDACTED]");
+  }
+  return result;
+}
+
+// --- Event normalization ---
+
+function normalizeEvents(rawEvents) {
+  const normalized = {
+    sessionId: null,
+    title: null,
+    model: null,
+    mode: null,
+    startTime: null,
+    endTime: null,
+    userMessages: 0,
+    assistantMessages: 0,
+    toolUses: [],
+    filesTouched: new Set(),
+    commandsRun: [],
+    validationAttempts: [],
+    errorSignals: [],
+    secretHits: [],
+    totalInputTokens: 0,
+    totalOutputTokens: 0,
+    totalCacheCreationTokens: 0,
+    totalCacheReadTokens: 0,
+    prLinks: [],
+    entrypoint: null,
+    version: null,
+  };
+
+  for (const evt of rawEvents) {
+    try {
+      // session id
+      if (evt.sessionId && !normalized.sessionId) {
+        normalized.sessionId = evt.sessionId;
+      }
+
+      // title
+      if (evt.type === "ai-title" && evt.aiTitle) {
+        normalized.title = evt.aiTitle;
+      }
+
+      // mode
+      if (evt.type === "mode" && evt.mode) {
+        normalized.mode = evt.mode;
+      }
+
+      // PR links
+      if (evt.type === "pr-link") {
+        normalized.prLinks.push({
+          prNumber: evt.prNumber,
+          prUrl: evt.prUrl,
+          repository: evt.prRepository,
+        });
+      }
+
+      // timestamps
+      if (evt.timestamp) {
+        const ts = typeof evt.timestamp === "string" ? new Date(evt.timestamp).getTime() : evt.timestamp;
+        if (!isNaN(ts)) {
+          if (!normalized.startTime || ts < normalized.startTime) normalized.startTime = ts;
+          if (!normalized.endTime || ts > normalized.endTime) normalized.endTime = ts;
+        }
+      }
+
+      // user messages
+      if (evt.type === "user" || evt.message?.role === "user") {
+        normalized.userMessages++;
+      }
+
+      // assistant messages with tool use and usage
+      if (evt.type === "assistant" || evt.message?.role === "assistant") {
+        normalized.assistantMessages++;
+        const msg = evt.message || {};
+        if (!normalized.model && msg.model) normalized.model = msg.model;
+
+        // usage
+        const usage = msg.usage;
+        if (usage) {
+          normalized.totalInputTokens += usage.input_tokens || 0;
+          normalized.totalOutputTokens += usage.output_tokens || 0;
+          normalized.totalCacheCreationTokens += usage.cache_creation_input_tokens || 0;
+          normalized.totalCacheReadTokens += usage.cache_read_input_tokens || 0;
+        }
+
+        // tool use blocks
+        const content = msg.content || [];
+        for (const block of content) {
+          if (block.type === "tool_use") {
+            const toolName = block.name || "unknown";
+            normalized.toolUses.push(toolName);
+
+            // file touches
+            if (FILE_TOUCHING_TOOLS.has(toolName)) {
+              const fp = block.input?.file_path || block.input?.path;
+              if (fp) normalized.filesTouched.add(fp);
+            }
+
+            // commands
+            if (COMMAND_TOOLS.has(toolName)) {
+              const cmd = block.input?.command || "";
+              const shortCmd = cmd.length > 120 ? cmd.slice(0, 120) + "..." : cmd;
+              normalized.commandsRun.push({ tool: toolName, command: redactSecrets(shortCmd) });
+
+              // check for validation commands
+              for (const pat of VALIDATION_COMMANDS) {
+                if (pat.test(cmd)) {
+                  normalized.validationAttempts.push({ tool: toolName, command: redactSecrets(shortCmd) });
+                  break;
+                }
+              }
+
+              // scan command text for secrets
+              const hits = scanForSecrets(cmd);
+              if (hits.length) normalized.secretHits.push(...hits);
+            }
+
+            // scan tool input stringified for secrets (shallow)
+            if (block.input) {
+              const inputStr = typeof block.input === "string" ? block.input : JSON.stringify(block.input);
+              const hits = scanForSecrets(inputStr);
+              if (hits.length) normalized.secretHits.push(...hits);
+            }
+          }
+
+          // scan text blocks for secrets
+          if (block.type === "text" && block.text) {
+            const hits = scanForSecrets(block.text);
+            if (hits.length) normalized.secretHits.push(...hits);
+          }
+        }
+      }
+
+      // system events — check for errors
+      if (evt.type === "system") {
+        if (evt.hookErrors?.length) {
+          for (const err of evt.hookErrors) {
+            normalized.errorSignals.push({ source: "hook", detail: redactSecrets(String(err).slice(0, 200)) });
+          }
+        }
+      }
+    } catch {
+      // tolerate any parsing error on individual events
+    }
+  }
+
+  // deduplicate secret hits
+  normalized.secretHits = [...new Set(normalized.secretHits)];
+  // convert filesTouched to array
+  normalized.filesTouched = [...normalized.filesTouched];
+
+  return normalized;
+}
+
+// --- Error/loop detection from tool sequences ---
+
+function detectErrorLoops(toolUses, windowSize = 4) {
+  const loops = [];
+  if (toolUses.length < windowSize * 2) return loops;
+  for (let i = windowSize * 2; i <= toolUses.length; i++) {
+    const a = toolUses.slice(i - windowSize, i).join("|");
+    const b = toolUses.slice(i - windowSize * 2, i - windowSize).join("|");
+    if (a === b) {
+      loops.push({ index: i, sequence: toolUses.slice(i - windowSize, i) });
+    }
+  }
+  // deduplicate consecutive identical loops
+  const deduped = [];
+  for (const loop of loops) {
+    const lastSeq = deduped.length ? deduped[deduped.length - 1].sequence.join("|") : "";
+    if (loop.sequence.join("|") !== lastSeq) deduped.push(loop);
+  }
+  return deduped;
+}
+
+function detectErrorBursts(commandsRun) {
+  let burst = 0;
+  let maxBurst = 0;
+  for (const cmd of commandsRun) {
+    const hasError = ERROR_PATTERNS.some((p) => p.test(cmd.command));
+    if (hasError) {
+      burst++;
+      if (burst > maxBurst) maxBurst = burst;
+    } else {
+      burst = 0;
+    }
+  }
+  return maxBurst;
+}
+
+// --- Session summary (privacy-safe) ---
+
+function buildSessionSummary(normalized) {
+  const durationMs = normalized.endTime && normalized.startTime
+    ? normalized.endTime - normalized.startTime
+    : null;
+
+  const toolLoops = detectErrorLoops(normalized.toolUses);
+  const errorBurst = detectErrorBursts(normalized.commandsRun);
+  const hasValidation = normalized.validationAttempts.length > 0;
+  const hasErrors = normalized.errorSignals.length > 0 || errorBurst >= 3;
+
+  return {
+    sessionId: normalized.sessionId,
+    title: normalized.title,
+    model: normalized.model,
+    durationMs,
+    durationMinutes: durationMs ? Math.round(durationMs / 60000) : null,
+    userMessages: normalized.userMessages,
+    assistantMessages: normalized.assistantMessages,
+    totalToolUses: normalized.toolUses.length,
+    uniqueToolsUsed: [...new Set(normalized.toolUses)],
+    filesTouchedCount: normalized.filesTouched.length,
+    filesTouched: normalized.filesTouched.map((f) => redactHomePath(redactSecrets(f))),
+    commandsRunCount: normalized.commandsRun.length,
+    validationAttempts: normalized.validationAttempts.length,
+    hasValidation,
+    errorSignals: normalized.errorSignals.length,
+    hasErrors,
+    toolLoopsDetected: toolLoops.length,
+    toolLoops: toolLoops.map((l) => ({ sequence: l.sequence })),
+    errorBurstMax: errorBurst,
+    secretHits: normalized.secretHits,
+    hasSecretRisk: normalized.secretHits.length > 0,
+    tokenSummary: {
+      inputTokens: normalized.totalInputTokens,
+      outputTokens: normalized.totalOutputTokens,
+      cacheCreationTokens: normalized.totalCacheCreationTokens,
+      cacheReadTokens: normalized.totalCacheReadTokens,
+      totalTokens: normalized.totalInputTokens + normalized.totalOutputTokens,
+    },
+    prLinks: normalized.prLinks,
+  };
+}
+
+// --- Resume packet ---
+
+function buildResumePacket(summary, normalized) {
+  const touchedAreas = normalized.filesTouched.map((f) => {
+    const parts = f.replace(/\\/g, "/").split("/");
+    return parts.length > 2 ? parts.slice(-3).join("/") : parts.join("/");
+  });
+
+  const uniqueAreas = [...new Set(touchedAreas.map((a) => {
+    const parts = a.split("/");
+    return parts.length > 1 ? parts.slice(0, -1).join("/") : a;
+  }))].slice(0, 10);
+
+  const risks = [];
+  if (!summary.hasValidation) risks.push("No validation commands detected — consider running tests");
+  if (summary.toolLoopsDetected > 0) risks.push(`${summary.toolLoopsDetected} repeated tool loop(s) detected — may indicate stuck work`);
+  if (summary.hasErrors) risks.push("Error signals detected — check for unresolved failures");
+  if (summary.hasSecretRisk) risks.push(`Possible secret exposure: ${summary.secretHits.join(", ")}`);
+  if (summary.errorBurstMax >= 3) risks.push(`Error burst of ${summary.errorBurstMax} consecutive commands — possible debugging loop`);
+
+  const nextSteps = [];
+  if (!summary.hasValidation) nextSteps.push("Run the project test suite to validate changes");
+  if (summary.toolLoopsDetected > 0) nextSteps.push("Review the repeated tool sequences for stuck patterns");
+  if (summary.hasSecretRisk) nextSteps.push("Audit touched files for accidental secret commits");
+  if (summary.prLinks.length > 0) nextSteps.push(`Review open PR(s): ${summary.prLinks.map((p) => p.prUrl).join(", ")}`);
+  if (nextSteps.length === 0) nextSteps.push("Continue from where the session left off");
+
+  return {
+    generatedAt: new Date().toISOString(),
+    sessionId: summary.sessionId,
+    title: summary.title || "(untitled session)",
+    model: summary.model,
+    durationMinutes: summary.durationMinutes,
+    touchedAreas: uniqueAreas,
+    filesTouchedCount: summary.filesTouchedCount,
+    toolsUsed: summary.uniqueToolsUsed,
+    validationStatus: summary.hasValidation ? "partial" : "none",
+    proofStatus: summary.hasValidation && !summary.hasErrors ? "partial" : "unverified",
+    risks,
+    nextSteps,
+    tokenSummary: summary.tokenSummary,
+  };
+}
+
+// --- Improvement suggestions ---
+
+function buildImprovementSuggestions(summaries) {
+  const suggestions = [];
+
+  const noValidationCount = summaries.filter((s) => !s.hasValidation).length;
+  if (noValidationCount >= 2) {
+    suggestions.push({
+      type: "claude_md",
+      suggestion: "Add a project validation command to CLAUDE.md (e.g., 'After changes, run: npm test')",
+      evidence: `${noValidationCount}/${summaries.length} recent sessions had no detected validation step`,
+    });
+  }
+
+  const loopSessions = summaries.filter((s) => s.toolLoopsDetected > 0).length;
+  if (loopSessions >= 2) {
+    suggestions.push({
+      type: "workflow",
+      suggestion: "Consider creating a debug/fix skill to break out of repeated tool loops faster",
+      evidence: `${loopSessions} sessions had repeated tool sequence loops`,
+    });
+  }
+
+  const secretSessions = summaries.filter((s) => s.hasSecretRisk).length;
+  if (secretSessions >= 1) {
+    suggestions.push({
+      type: "security",
+      suggestion: "Add pre-commit secret scanning or .gitignore rules for sensitive files",
+      evidence: `${secretSessions} session(s) had possible secret patterns in tool activity`,
+    });
+  }
+
+  // repeated file patterns
+  const fileCounts = {};
+  for (const s of summaries) {
+    for (const f of s.filesTouched) {
+      fileCounts[f] = (fileCounts[f] || 0) + 1;
+    }
+  }
+  const hotFiles = Object.entries(fileCounts)
+    .filter(([, c]) => c >= 3)
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, 5);
+  if (hotFiles.length > 0) {
+    suggestions.push({
+      type: "attention",
+      suggestion: `Frequently touched files across sessions: ${hotFiles.map(([f, c]) => `${path.basename(f)} (${c}x)`).join(", ")}`,
+      evidence: "Files edited in 3+ sessions may benefit from dedicated tests or review",
+    });
+  }
+
+  return suggestions;
+}
+
+// --- Proof gap classification ---
+
+function classifyProofGap(summary) {
+  const hasFiles = summary.filesTouchedCount > 0;
+  const hasValidation = summary.hasValidation;
+  const hasErrors = summary.hasErrors;
+  const hasLoops = summary.toolLoopsDetected > 0;
+  const hasSecrets = summary.hasSecretRisk;
+
+  if (!hasFiles) return { status: "no_changes", label: "No file activity observed", basis: "observed" };
+  if (hasValidation && !hasErrors) return { status: "proved", label: "Validation observed, no errors detected", basis: "observed" };
+  if (hasValidation && hasErrors) return { status: "partial", label: "Validation observed, errors remain", basis: "observed" };
+  if (hasLoops) return { status: "stuck", label: "Repeated tool loops detected — may need manual review", basis: "inferred" };
+  if (hasSecrets) return { status: "risk", label: "Possible secret exposure — audit required", basis: "inferred" };
+  return { status: "unproved", label: "File activity observed without validation evidence", basis: "observed" };
+}
+
+// --- Receipt persistence ---
+
+const SESSION_EVIDENCE_CONTRACT = "avorelo.sessionEvidence.v1";
+const SESSION_EVIDENCE_RECEIPT_REL = ".claude/cco/orchestration/session-evidence/latest-receipt.json";
+const SESSION_EVIDENCE_EVENT_REL = ".claude/cco/events/session-evidence.jsonl";
+const RESUME_PACKET_REL = ".claude/cco/state/session-resume-packet.json";
+
+function persistScanReceipt(cwd, result) {
+  const { ensureCcoDirs, safeWriteJson, nowIso } = require("../fsx");
+  ensureCcoDirs(cwd);
+
+  const proofGaps = (result.summaries || []).map((s) => ({
+    sessionId: s.sessionId,
+    title: s.title,
+    ...classifyProofGap(s),
+  }));
+
+  const proved = proofGaps.filter((g) => g.status === "proved").length;
+  const unproved = proofGaps.filter((g) => g.status === "unproved" || g.status === "partial" || g.status === "stuck").length;
+
+  const receipt = {
+    contract: SESSION_EVIDENCE_CONTRACT,
+    schemaVersion: 1,
+    generatedAt: nowIso(),
+    source: "claude-code",
+    privacy: {
+      localOnly: true,
+      cloudUploaded: false,
+      rawTranscriptStored: false,
+      secretsRedacted: (result.summaries || []).some((s) => s.hasSecretRisk),
+      pathMode: "relative-or-redacted",
+    },
+    sessionsScanned: result.sessionsScanned,
+    proofSummary: { proved, unproved, total: proofGaps.length },
+    proofGaps,
+    resumePacket: result.resumePacket,
+    suggestions: result.suggestions,
+    attentionItems: result.attentionItems || [],
+  };
+
+  safeWriteJson(cwd, SESSION_EVIDENCE_RECEIPT_REL, receipt);
+
+  if (result.resumePacket) {
+    safeWriteJson(cwd, RESUME_PACKET_REL, result.resumePacket);
+  }
+
+  const eventLine = JSON.stringify({ ts: nowIso(), event: "scan_completed", sessionsScanned: result.sessionsScanned, proved, unproved }) + "\n";
+  const eventPath = path.join(cwd, SESSION_EVIDENCE_EVENT_REL);
+  fs.mkdirSync(path.dirname(eventPath), { recursive: true });
+  fs.appendFileSync(eventPath, eventLine, "utf8");
+
+  return { receiptPath: SESSION_EVIDENCE_RECEIPT_REL, resumePacketPath: result.resumePacket ? RESUME_PACKET_REL : null };
+}
+
+// --- Value ledger integration ---
+
+function emitValueEvents(cwd, result) {
+  let ValueLedger;
+  try {
+    ValueLedger = require("../value-ledger").ValueLedger;
+  } catch {
+    return [];
+  }
+  const ledger = new ValueLedger(cwd);
+  const events = [];
+
+  const proofGaps = (result.summaries || []).map((s) => classifyProofGap(s));
+  const proved = proofGaps.filter((g) => g.status === "proved").length;
+  const unproved = proofGaps.filter((g) => g.status === "unproved").length;
+
+  if (proved > 0) {
+    events.push(ledger.append({
+      bucket: "proof_completed",
+      label: `Validation observed in ${proved} session(s)`,
+      notes: "Observed: validation commands detected in Claude Code session transcripts",
+      artifactRef: SESSION_EVIDENCE_RECEIPT_REL,
+      meta: { valueClaimLevel: "observed", source: "claude-code" },
+    }));
+  }
+
+  if (unproved > 0) {
+    events.push(ledger.append({
+      bucket: "proof_completed",
+      label: `Proof gap detected: ${unproved} session(s) with file activity but no validation observed`,
+      notes: "Detected: file activity observed without validation evidence — surfaced for attention, not claimed as avoided",
+      artifactRef: SESSION_EVIDENCE_RECEIPT_REL,
+      meta: { valueClaimLevel: "detected", source: "claude-code" },
+    }));
+  }
+
+  const secretSessions = (result.summaries || []).filter((s) => s.hasSecretRisk).length;
+  if (secretSessions > 0) {
+    events.push(ledger.append({
+      bucket: "proof_completed",
+      label: `Secret-like patterns detected and redacted in ${secretSessions} session(s)`,
+      notes: "Detected: possible secret patterns found in tool activity metadata — redacted in output, surfaced for audit",
+      artifactRef: SESSION_EVIDENCE_RECEIPT_REL,
+      meta: { valueClaimLevel: "detected", source: "claude-code" },
+    }));
+  }
+
+  return events.filter(Boolean);
+}
+
+// --- CLI rendering (Avorelo style) ---
+
+function formatScanText(result) {
+  const lines = [];
+  lines.push("Avorelo — Claude Code Session Evidence");
+  lines.push("");
+
+  if (!result.discovery.exists) {
+    lines.push("Found: No Claude Code local data directory detected.");
+    lines.push("Next: Install or run Claude Code in this project first.");
+    return lines.join("\n");
+  }
+
+  if (result.summaries.length === 0) {
+    lines.push("Found: Claude Code installed, but no session transcripts for this project.");
+    lines.push("Next: Run a Claude Code session in this workspace, then re-scan.");
+    return lines.join("\n");
+  }
+
+  // --- What Avorelo found ---
+  const totalFiles = new Set(result.summaries.flatMap((s) => s.filesTouched)).size;
+  const totalTokens = result.summaries.reduce((n, s) => n + s.tokenSummary.totalTokens, 0);
+  lines.push(`Found: ${result.sessionsScanned} session(s), ${totalFiles} files touched, ${totalTokens.toLocaleString()} tokens (metadata only — raw transcripts not stored)`);
+
+  const recent = result.summaries.slice(0, 5);
+  for (const s of recent) {
+    const dur = s.durationMinutes != null ? `${s.durationMinutes}m` : "?m";
+    const title = s.title || "(untitled)";
+    const gap = classifyProofGap(s);
+    lines.push(`  ${s.sessionId.slice(0, 8)}  ${dur}  ${title.slice(0, 50)}  [${gap.status}]`);
+  }
+  lines.push("");
+
+  // --- What was proved ---
+  const proofGaps = result.summaries.map((s) => ({ sessionId: s.sessionId, title: s.title, ...classifyProofGap(s) }));
+  const proved = proofGaps.filter((g) => g.status === "proved");
+  const partial = proofGaps.filter((g) => g.status === "partial");
+  const unproved = proofGaps.filter((g) => g.status === "unproved");
+  const stuck = proofGaps.filter((g) => g.status === "stuck");
+  const risks = proofGaps.filter((g) => g.status === "risk");
+
+  if (proved.length > 0) {
+    lines.push(`Proved: ${proved.length} session(s) — validation observed, no errors detected`);
+  }
+  if (partial.length > 0) {
+    lines.push(`Partial: ${partial.length} session(s) — validation observed, errors remain`);
+  }
+
+  // --- What was NOT proved ---
+  if (unproved.length > 0) {
+    lines.push(`Not proved: ${unproved.length} session(s) — file activity observed, validation not observed`);
+  }
+  if (stuck.length > 0) {
+    lines.push(`Stuck: ${stuck.length} session(s) — repeated tool loops detected (inferred)`);
+  }
+  if (risks.length > 0) {
+    lines.push(`Risk: ${risks.length} session(s) — possible secret exposure detected (inferred)`);
+  }
+  lines.push("");
+
+  // --- What needs attention ---
+  const attentionItems = [];
+  if (unproved.length > 0) attentionItems.push(`${unproved.length} session(s) changed files without detected validation`);
+  const loopSessions = result.summaries.filter((s) => s.toolLoopsDetected > 0).length;
+  if (loopSessions > 0) attentionItems.push(`${loopSessions} repeated error/tool loop(s) detected`);
+  const secretSessions = result.summaries.filter((s) => s.hasSecretRisk).length;
+  if (secretSessions > 0) attentionItems.push(`${secretSessions} possible secret-like value(s) redacted`);
+  const errorSessions = result.summaries.filter((s) => s.hasErrors).length;
+  if (errorSessions > 0) attentionItems.push(`${errorSessions} session(s) had error signals`);
+
+  if (attentionItems.length) {
+    lines.push("Attention:");
+    for (const item of attentionItems) lines.push(`  - ${item}`);
+    lines.push("");
+  }
+
+  // --- What was safely saved ---
+  if (result.persisted) {
+    lines.push("Saved:");
+    lines.push(`  Receipt: ${result.persisted.receiptPath}`);
+    if (result.persisted.resumePacketPath) {
+      lines.push(`  Resume packet: ${result.persisted.resumePacketPath}`);
+    }
+    if (result.persisted.valueEventsCount > 0) {
+      lines.push(`  Value events: ${result.persisted.valueEventsCount} logged`);
+    }
+    lines.push("");
+  }
+
+  // --- What to do next ---
+  if (result.resumePacket) {
+    lines.push("Next:");
+    for (const s of result.resumePacket.nextSteps) lines.push(`  - ${s}`);
+    lines.push("");
+  }
+
+  // --- Suggested improvements ---
+  if (result.suggestions.length) {
+    lines.push("Improve:");
+    for (const s of result.suggestions) {
+      lines.push(`  - ${s.suggestion}`);
+      lines.push(`    (${s.evidence})`);
+    }
+    lines.push("");
+  }
+
+  // --- Privacy ---
+  lines.push("Privacy:");
+  lines.push("  Local only — no data uploaded");
+  lines.push("  Metadata only — raw transcripts not stored");
+  const secretCount = result.summaries.filter((s) => s.hasSecretRisk).length;
+  if (secretCount > 0) {
+    lines.push(`  ${secretCount} secret-like value(s) redacted`);
+  }
+
+  return lines.join("\n");
+}
+
+function formatScanJson(result) {
+  const safe = { ...result };
+  if (safe.discovery) {
+    safe.discovery = { ...safe.discovery, claudeHome: redactHomePath(safe.discovery.claudeHome) };
+  }
+  return JSON.stringify(safe, null, 2);
+}
+
+// --- Resume packet retrieval ---
+
+function readLatestResumePacket(cwd) {
+  const abs = path.join(cwd, RESUME_PACKET_REL);
+  try {
+    return JSON.parse(fs.readFileSync(abs, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function formatResumeText(packet) {
+  if (!packet) {
+    return "No resume packet found for this project.\nNext: Run `avorelo scan claude` after a Claude Code session.";
+  }
+  const lines = [];
+  lines.push("Avorelo — Resume Packet");
+  lines.push("");
+  lines.push(`Session: ${packet.title || "(untitled)"}`);
+  lines.push(`Model: ${packet.model || "unknown"}`);
+  lines.push(`Duration: ${packet.durationMinutes || "?"}m`);
+  lines.push(`Files touched: ${packet.filesTouchedCount || 0}`);
+  lines.push(`Validation: ${packet.validationStatus || "unknown"}`);
+  lines.push(`Proof: ${packet.proofStatus || "unknown"}`);
+  if (packet.touchedAreas?.length) {
+    lines.push(`Areas: ${packet.touchedAreas.join(", ")}`);
+  }
+  if (packet.risks?.length) {
+    lines.push("");
+    lines.push("Risks:");
+    for (const r of packet.risks) lines.push(`  - ${r}`);
+  }
+  if (packet.nextSteps?.length) {
+    lines.push("");
+    lines.push("Next:");
+    for (const s of packet.nextSteps) lines.push(`  - ${s}`);
+  }
+  lines.push("");
+  lines.push("Privacy: Local only — metadata only — raw transcripts not stored");
+  return lines.join("\n");
+}
+
+function formatResumeJson(packet) {
+  return JSON.stringify(packet, null, 2);
+}
+
+// --- Doctor helper ---
+
+function buildDoctorCheck(cwd) {
+  const receiptPath = path.join(cwd, SESSION_EVIDENCE_RECEIPT_REL);
+  const resumePath = path.join(cwd, RESUME_PACKET_REL);
+  const hasReceipt = fs.existsSync(receiptPath);
+  const hasResume = fs.existsSync(resumePath);
+
+  if (!hasReceipt && !hasResume) {
+    return {
+      id: "claude_evidence",
+      label: "Claude Code evidence",
+      severity: "recommended",
+      passed: false,
+      details: "Not found for this project — run `avorelo scan claude` after using Claude Code",
+    };
+  }
+
+  let proofGapCount = 0;
+  try {
+    const receipt = JSON.parse(fs.readFileSync(receiptPath, "utf8"));
+    proofGapCount = receipt.proofSummary?.unproved || 0;
+  } catch {}
+
+  const parts = [];
+  if (hasReceipt) parts.push("receipt ready");
+  if (hasResume) parts.push("resume packet ready");
+  if (proofGapCount > 0) parts.push(`${proofGapCount} proof gap(s)`);
+  parts.push("local only, metadata only");
+
+  return {
+    id: "claude_evidence",
+    label: "Claude Code evidence",
+    severity: "recommended",
+    passed: true,
+    details: parts.join(", "),
+  };
+}
+
+// --- Local manifest for open/control center ---
+
+function buildLocalManifest(cwd) {
+  const receiptPath = path.join(cwd, SESSION_EVIDENCE_RECEIPT_REL);
+  const resumePath = path.join(cwd, RESUME_PACKET_REL);
+  const hasReceipt = fs.existsSync(receiptPath);
+  const hasResume = fs.existsSync(resumePath);
+
+  let proofGapCount = 0;
+  let nextAction = null;
+  try {
+    const receipt = JSON.parse(fs.readFileSync(receiptPath, "utf8"));
+    proofGapCount = receipt.proofSummary?.unproved || 0;
+  } catch {}
+  try {
+    const packet = JSON.parse(fs.readFileSync(resumePath, "utf8"));
+    nextAction = packet.nextSteps?.[0] || null;
+  } catch {}
+
+  return {
+    schemaVersion: 1,
+    source: "claude-code",
+    latestReceiptPath: hasReceipt ? SESSION_EVIDENCE_RECEIPT_REL : null,
+    latestResumePacketPath: hasResume ? RESUME_PACKET_REL : null,
+    proofGapCount,
+    privacyStatus: "metadata-only-redacted",
+    nextAction,
+    rawTranscriptStored: false,
+    cloudUploaded: false,
+  };
+}
+
+// --- Main scan function ---
+
+function cwdToProjectKey(p) {
+  return p.replace(/[:\\/. ]/g, "-").replace(/^-+/, "").replace(/-+/g, "-");
+}
+
+function matchProjectKey(projectKeys, cwd) {
+  const key1 = cwdToProjectKey(cwd);
+  const exact = projectKeys.find((k) => k === key1);
+  if (exact) return exact;
+
+  const key2 = cwd.replace(/[:\\/]/g, "-").replace(/^-+/, "");
+  const exact2 = projectKeys.find((k) => k === key2);
+  if (exact2) return exact2;
+
+  const segments = cwd.replace(/\\/g, "/").split("/").filter(Boolean);
+  if (segments.length >= 2) {
+    const tail2 = segments.slice(-2).join("-").replace(/\./g, "-");
+    const match = projectKeys.find((k) => k.endsWith(tail2) && !k.endsWith("-" + tail2 + "-"));
+    if (match) return match;
+  }
+
+  return null;
+}
+
+function scanClaudeSessions(options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const maxSessions = options.maxSessions || 20;
+  const persist = options.persist !== false;
+
+  const discovery = discoverClaudeHome();
+  if (!discovery.exists) {
+    return {
+      discovery,
+      projectKeys: [],
+      sessionsScanned: 0,
+      summaries: [],
+      resumePacket: null,
+      suggestions: [],
+      proofGaps: [],
+      persisted: null,
+    };
+  }
+
+  const projectKeys = discoverProjectKeys();
+  const bestKey = matchProjectKey(projectKeys, cwd);
+
+  let sessionFiles = [];
+  if (bestKey) {
+    sessionFiles = discoverSessionFiles(bestKey);
+  }
+
+  const limited = sessionFiles.slice(0, maxSessions);
+
+  const summaries = [];
+  for (const sf of limited) {
+    const rawEvents = parseJsonlFile(sf.filePath);
+    if (rawEvents.length === 0) continue;
+    const normalized = normalizeEvents(rawEvents);
+    const summary = buildSessionSummary(normalized);
+    summary._normalized = normalized;
+    summaries.push(summary);
+  }
+
+  let resumePacket = null;
+  if (summaries.length > 0) {
+    const mostRecent = summaries[0];
+    resumePacket = buildResumePacket(mostRecent, mostRecent._normalized);
+  }
+
+  for (const s of summaries) delete s._normalized;
+
+  const suggestions = buildImprovementSuggestions(summaries);
+  const proofGaps = summaries.map((s) => ({
+    sessionId: s.sessionId,
+    title: s.title,
+    ...classifyProofGap(s),
+  }));
+
+  const result = {
+    discovery,
+    projectKeys: projectKeys.slice(0, 20),
+    sessionsScanned: summaries.length,
+    summaries,
+    resumePacket,
+    suggestions,
+    proofGaps,
+    persisted: null,
+  };
+
+  if (persist && summaries.length > 0) {
+    try {
+      const paths = persistScanReceipt(cwd, result);
+      const valueEvents = emitValueEvents(cwd, result);
+      result.persisted = { ...paths, valueEventsCount: valueEvents.length };
+    } catch {
+      result.persisted = null;
+    }
+  }
+
+  return result;
+}
+
+// --- Exports ---
+
+module.exports = {
+  // discovery
+  discoverClaudeHome,
+  discoverProjectKeys,
+  discoverSessionFiles,
+  discoverActiveSessions,
+  CLAUDE_HOME,
+  SESSIONS_DIR,
+  PROJECTS_DIR,
+
+  // parsing
+  parseJsonlFile,
+
+  // normalization
+  normalizeEvents,
+  buildSessionSummary,
+
+  // security
+  scanForSecrets,
+  redactSecrets,
+  SECRET_PATTERNS,
+
+  // detection
+  detectErrorLoops,
+  detectErrorBursts,
+  FILE_TOUCHING_TOOLS,
+  COMMAND_TOOLS,
+
+  // proof gaps
+  classifyProofGap,
+
+  // resume packet
+  buildResumePacket,
+
+  // persistence
+  persistScanReceipt,
+  emitValueEvents,
+  SESSION_EVIDENCE_CONTRACT,
+  SESSION_EVIDENCE_RECEIPT_REL,
+  SESSION_EVIDENCE_EVENT_REL,
+  RESUME_PACKET_REL,
+
+  // suggestions
+  buildImprovementSuggestions,
+
+  // project key matching
+  cwdToProjectKey,
+  matchProjectKey,
+
+  // resume
+  readLatestResumePacket,
+  formatResumeText,
+  formatResumeJson,
+
+  // doctor
+  buildDoctorCheck,
+
+  // local manifest
+  buildLocalManifest,
+
+  // path redaction
+  redactHomePath,
+
+  // main scan
+  scanClaudeSessions,
+
+  // formatting
+  formatScanText,
+  formatScanJson,
+};