sigmap 6.14.0 → 7.0.0

package/src/format/usage-guidance.js

@@ -0,0 +1,28 @@
+'use strict';
+
+/**
+ * Canonical "how to use SigMap" guidance block (v6.16/v7.0).
+ *
+ * Every adapter emits this one identical block so all generated context files
+ * (CLAUDE.md, AGENTS.md, .github/copilot-instructions.md, GEMINI.md, .cursorrules,
+ * …) carry the same, single usage section — instead of each adapter inventing
+ * its own wording (and codex emitting a redundant second JSON block).
+ */
+
+function usageBlock() {
+  return [
+    '## SigMap commands',
+    '',
+    '| When | Command |',
+    '|------|---------|',
+    '| Before answering a question about code | `sigmap ask "<your question>"` |',
+    '| To rank files by topic | `sigmap --query "<topic>"` |',
+    '| After changing config or source dirs | `sigmap validate` |',
+    '| To verify an AI answer is grounded | `sigmap judge --response <file>` |',
+    '',
+    'Always run `sigmap ask` (or `sigmap --query`) before searching for files relevant to a task.',
+    '',
+  ].join('\n');
+}
+
+module.exports = { usageBlock };

package/src/format/verify-report.js

@@ -0,0 +1,164 @@
+'use strict';
+
+/**
+ * Hallucination Guard report view (Surface A, v6.15.0).
+ *
+ * Turns the `verify-ai-output --json` result into a standalone, self-contained
+ * HTML report — red/amber/green per issue, with closest-match suggestions
+ * inline. The visual language deliberately mirrors the planned PR-comment
+ * styling so a single screenshot is reusable across docs and CI (plan proof #5).
+ *
+ * Zero dependencies, inline CSS/SVG, no external assets. Also exports a compact
+ * Markdown renderer for CI / PR comments that shares the same structure.
+ */
+
+const TYPE_META = {
+  'fake-file': { label: 'Fake file', tone: 'red', icon: '✕' },
+  'fake-test-file': { label: 'Fake test file', tone: 'red', icon: '✕' },
+  'fake-import': { label: 'Fake import', tone: 'red', icon: '✕' },
+  'fake-npm-script': { label: 'Fake npm script', tone: 'red', icon: '✕' },
+  'fake-symbol': { label: 'Fake symbol', tone: 'amber', icon: '!' },
+};
+
+function escapeHtml(value) {
+  return String(value == null ? '' : value)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+function toneFor(issue) {
+  const meta = TYPE_META[issue.type];
+  if (meta) return meta.tone;
+  return issue.confidence === 'high' ? 'red' : 'amber';
+}
+
+function labelFor(issue) {
+  return (TYPE_META[issue.type] && TYPE_META[issue.type].label) || issue.type;
+}
+
+/**
+ * Render the verify result to a full HTML document.
+ * @param {{ file?: string, issues: object[], summary: object }} result
+ * @param {object} [opts]
+ * @param {string} [opts.title]
+ * @returns {string} HTML
+ */
+function renderReportHtml(result, opts = {}) {
+  const issues = Array.isArray(result.issues) ? result.issues : [];
+  const summary = result.summary || { total: issues.length, byType: {}, clean: issues.length === 0 };
+  const file = result.file || opts.file || 'AI answer';
+  const title = opts.title || 'SigMap — Hallucination Guard report';
+  const clean = summary.clean || issues.length === 0;
+  const byType = summary.byType || {};
+
+  const chips = Object.keys(TYPE_META)
+    .filter((t) => byType[t])
+    .map((t) => `<span class="chip chip-${TYPE_META[t].tone}">${escapeHtml(TYPE_META[t].label)}: ${byType[t]}</span>`)
+    .join('');
+
+  const banner = clean
+    ? `<div class="banner banner-green"><span class="dot"></span> No hallucinations detected — ${escapeHtml(String(summary.symbolsIndexed || 0))} symbols indexed</div>`
+    : `<div class="banner banner-red"><span class="dot"></span> ${issues.length} issue${issues.length === 1 ? '' : 's'} found in <code>${escapeHtml(file)}</code></div>`;
+
+  const rows = issues.map((issue) => {
+    const tone = toneFor(issue);
+    const sugg = issue.suggestion
+      ? `<div class="suggestion">↳ ${escapeHtml(issue.suggestion)} <span class="conf">heuristic</span></div>`
+      : '';
+    return [
+      `<li class="issue issue-${tone}">`,
+      `  <div class="issue-head">`,
+      `    <span class="badge badge-${tone}">${escapeHtml(labelFor(issue))}</span>`,
+      `    <span class="loc">${escapeHtml(issue.location || ('L' + issue.line))}</span>`,
+      `    <span class="conf conf-${escapeHtml(issue.confidence || 'high')}">${escapeHtml(issue.confidence || 'high')} confidence</span>`,
+      `  </div>`,
+      `  <div class="msg">${escapeHtml(issue.message || issue.value)}</div>`,
+      `  ${sugg}`,
+      `</li>`,
+    ].join('\n');
+  }).join('\n');
+
+  const list = clean
+    ? '<p class="empty">Nothing to report — every file, import, symbol, and script in the answer resolves against the repository.</p>'
+    : `<ul class="issues">${rows}</ul>`;
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHtml(title)}</title>
+<style>
+  :root { color-scheme: light dark; }
+  * { box-sizing: border-box; }
+  body { font: 14px/1.5 -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; margin: 0; background: #0d1117; color: #e6edf3; }
+  .wrap { max-width: 880px; margin: 0 auto; padding: 32px 20px 64px; }
+  h1 { font-size: 20px; margin: 0 0 4px; }
+  .sub { color: #8b949e; margin: 0 0 20px; font-size: 13px; }
+  code { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; background: #161b22; padding: 1px 5px; border-radius: 4px; font-size: 12.5px; }
+  .banner { display: flex; align-items: center; gap: 8px; padding: 12px 16px; border-radius: 8px; font-weight: 600; margin-bottom: 16px; }
+  .banner-green { background: rgba(46,160,67,.15); border: 1px solid rgba(46,160,67,.4); color: #3fb950; }
+  .banner-red { background: rgba(248,81,73,.12); border: 1px solid rgba(248,81,73,.4); color: #f85149; }
+  .dot { width: 9px; height: 9px; border-radius: 50%; background: currentColor; }
+  .chips { display: flex; flex-wrap: wrap; gap: 6px; margin-bottom: 20px; }
+  .chip { font-size: 12px; padding: 3px 9px; border-radius: 999px; font-weight: 600; }
+  .chip-red { background: rgba(248,81,73,.15); color: #f85149; }
+  .chip-amber { background: rgba(210,153,34,.18); color: #d29922; }
+  ul.issues { list-style: none; margin: 0; padding: 0; display: flex; flex-direction: column; gap: 10px; }
+  .issue { border: 1px solid #30363d; border-left-width: 4px; border-radius: 8px; padding: 12px 14px; background: #0f141a; }
+  .issue-red { border-left-color: #f85149; }
+  .issue-amber { border-left-color: #d29922; }
+  .issue-head { display: flex; align-items: center; gap: 10px; flex-wrap: wrap; }
+  .badge { font-size: 11.5px; font-weight: 700; padding: 2px 8px; border-radius: 5px; text-transform: uppercase; letter-spacing: .03em; }
+  .badge-red { background: rgba(248,81,73,.18); color: #f85149; }
+  .badge-amber { background: rgba(210,153,34,.2); color: #d29922; }
+  .loc { font-family: ui-monospace, monospace; color: #8b949e; font-size: 12px; }
+  .conf { font-size: 11px; color: #8b949e; }
+  .conf-high { color: #f85149; }
+  .conf-medium { color: #d29922; }
+  .msg { margin-top: 7px; font-family: ui-monospace, monospace; font-size: 12.5px; color: #e6edf3; }
+  .suggestion { margin-top: 6px; font-size: 12.5px; color: #3fb950; }
+  .suggestion .conf { margin-left: 6px; }
+  .empty { color: #8b949e; }
+  footer { margin-top: 28px; color: #6e7681; font-size: 12px; }
+  a { color: #58a6ff; }
+</style>
+</head>
+<body>
+<div class="wrap">
+  <h1>Hallucination Guard report</h1>
+  <p class="sub">Deterministic verification of an AI answer against the real repository — <code>sigmap verify-ai-output</code></p>
+  ${banner}
+  ${chips ? `<div class="chips">${chips}</div>` : ''}
+  ${list}
+  <footer>Generated by <a href="https://github.com/manojmallick/sigmap">SigMap</a> · offline, no LLM · suggestions are heuristic (closest-match)</footer>
+</div>
+</body>
+</html>
+`;
+}
+
+/** Compact Markdown rendering of the same result (CI / PR comments). */
+function renderReportMarkdown(result) {
+  const issues = Array.isArray(result.issues) ? result.issues : [];
+  const summary = result.summary || {};
+  const file = result.file || 'AI answer';
+  if (summary.clean || issues.length === 0) {
+    return `### ✅ Hallucination Guard — clean\n\nNo fabricated files, imports, symbols, or scripts in \`${file}\`.`;
+  }
+  const lines = [
+    `### ❌ Hallucination Guard — ${issues.length} issue${issues.length === 1 ? '' : 's'} in \`${file}\``,
+    '',
+    '| Type | Location | Detail | Suggestion |',
+    '| --- | --- | --- | --- |',
+  ];
+  for (const i of issues) {
+    const sugg = i.suggestion ? i.suggestion.replace(/\|/g, '\\|') : '—';
+    lines.push(`| ${labelFor(i)} | ${i.location || ('L' + i.line)} | \`${String(i.value).replace(/\|/g, '\\|')}\` | ${sugg} |`);
+  }
+  return lines.join('\n');
+}
+
+module.exports = { renderReportHtml, renderReportMarkdown, escapeHtml };

package/src/mcp/handlers.js

@@ -505,4 +505,47 @@ function getLines(args, cwd) {
   ].join('\n');
 }
 
-module.exports = { readContext, searchSignatures, getMap, createCheckpoint, getRouting, explainFile, listModules, queryContext, getImpact, getLines };
+/**
+ * read_memory({ limit? }) → string
+ *
+ * Recall the cross-session decision log (notes) plus the last ranking-session
+ * focus, formatted for an agent to consume at the start of a task.
+ */
+function readMemory(args, cwd) {
+  let limit = parseInt(args && args.limit, 10);
+  if (!Number.isFinite(limit) || limit <= 0) limit = 10;
+  limit = Math.min(limit, 50);
+
+  const out = ['# SigMap memory'];
+
+  let notes = [];
+  try {
+    const { readNotes, formatNotes } = require('../session/notes');
+    notes = readNotes(cwd, limit);
+    out.push('');
+    out.push(`## Recent notes (${notes.length})`);
+    // Most recent first for quick scanning.
+    out.push(formatNotes(notes.slice().reverse()));
+  } catch (_) {
+    out.push('');
+    out.push('_No notes available._');
+  }
+
+  // Last ranking-session focus (if any) — extends src/session/memory.js.
+  try {
+    const { loadSession } = require('../session/memory');
+    const s = loadSession(cwd);
+    if (s && (s.lastQuery || (s.topFiles && s.topFiles.length))) {
+      out.push('');
+      out.push('## Last session');
+      if (s.lastQuery) out.push(`**Last query:** ${s.lastQuery}`);
+      if (s.topFiles && s.topFiles.length) {
+        out.push(`**Focus files:** ${s.topFiles.map((f) => f.file).slice(0, 5).join(', ')}`);
+      }
+    }
+  } catch (_) { /* session optional */ }
+
+  return out.join('\n');
+}
+
+module.exports = { readContext, searchSignatures, getMap, createCheckpoint, getRouting, explainFile, listModules, queryContext, getImpact, getLines, readMemory };

package/src/mcp/server.js

@@ -8,17 +8,17 @@
  *
  * Supported methods:
  *   initialize        → serverInfo + capabilities
- *   tools/list        → 10 tool definitions
+ *   tools/list        → 11 tool definitions
  *   tools/call        → dispatch to handler, return result
  */
 
 const readline = require('readline');
 const { TOOLS } = require('./tools');
-const { readContext, searchSignatures, getMap, createCheckpoint, getRouting, explainFile, listModules, queryContext, getImpact, getLines } = require('./handlers');
+const { readContext, searchSignatures, getMap, createCheckpoint, getRouting, explainFile, listModules, queryContext, getImpact, getLines, readMemory } = require('./handlers');
 
 const SERVER_INFO = {
   name: 'sigmap',
-  version: '6.14.0',
+  version: '7.0.0',
   description: 'SigMap MCP server — code signatures on demand',
 };
 
@@ -76,6 +76,7 @@ function dispatch(msg, cwd) {
       else if (name === 'query_context') text = queryContext(args, cwd);
       else if (name === 'get_impact') text = getImpact(args, cwd);
       else if (name === 'get_lines') text = getLines(args, cwd);
+      else if (name === 'read_memory') text = readMemory(args, cwd);
       else {
         respondError(id, -32601, `Unknown tool: ${name}`);
         return;

package/src/mcp/tools.js

@@ -1,9 +1,9 @@
 'use strict';
 
 /**
- * MCP tool definitions for SigMap (10 tools).
+ * MCP tool definitions for SigMap (11 tools).
  * read_context, search_signatures, get_map, create_checkpoint, get_routing,
- * explain_file, list_modules, query_context, get_impact, get_lines.
+ * explain_file, list_modules, query_context, get_impact, get_lines, read_memory.
  */
 
 const TOOLS = [
@@ -197,6 +197,24 @@ const TOOLS = [
       required: ['file', 'start', 'end'],
     },
   },
+  {
+    name: 'read_memory',
+    description:
+      'Recall the project decision log — recent notes left by humans or agents ' +
+      'across sessions (via `sigmap note`), plus the last ranking-session focus. ' +
+      'Call this at the start of a task to kill cold-start: it answers ' +
+      '"what were we doing and why" without re-reading the whole codebase.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        limit: {
+          type: 'number',
+          description: 'How many of the most recent notes to return (default: 10, max: 50).',
+        },
+      },
+      required: [],
+    },
+  },
 ];
 
 module.exports = { TOOLS };

package/src/nudge.js

@@ -0,0 +1,97 @@
+'use strict';
+
+/**
+ * Star nudge + usage tracking (v7.0.0).
+ *
+ * Records run counts in `.context/usage.json` and shows a one-time GitHub-star
+ * message after the tool has been genuinely useful (≥10 runs, ≥8 successes).
+ * Shown exactly once per machine — even under concurrent runs (an `wx` lock
+ * file makes the show race-safe). Wired into `ask` (and the `squeeze` path).
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const crypto = require('crypto');
+
+const RUN_THRESHOLD = 10;
+const SUCCESS_THRESHOLD = 8;
+
+function usagePath(cwd) { return path.join(cwd, '.context', 'usage.json'); }
+
+function defaultUsage() {
+  return {
+    totalRuns: 0, successfulRuns: 0, squeezeOffered: 0, squeezeAccepted: 0,
+    starNudgeShown: false, machineId: '', firstRunDate: null, lastRunDate: null,
+  };
+}
+
+function readUsage(cwd) {
+  try { return { ...defaultUsage(), ...JSON.parse(fs.readFileSync(usagePath(cwd), 'utf8')) }; }
+  catch (_) { return defaultUsage(); }
+}
+
+function writeUsageAtomic(cwd, usage) {
+  const p = usagePath(cwd);
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  const tmp = `${p}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(usage, null, 2));
+  fs.renameSync(tmp, p); // atomic on POSIX
+}
+
+const STAR_MESSAGE = [
+  '─────────────────────────────────────────────────────────',
+  '  SigMap has helped you 10 times now.',
+  '',
+  "  If it's been useful, a GitHub star takes 5 seconds and",
+  '  helps other developers find it:',
+  '  → github.com/manojmallick/sigmap',
+  '',
+  "  (Won't ask again. Press Enter to continue.)",
+  '─────────────────────────────────────────────────────────',
+].join('\n');
+
+function showStarNudge(write) {
+  (write || ((s) => process.stderr.write(s)))('\n' + STAR_MESSAGE + '\n');
+}
+
+/**
+ * Record one run and, when the thresholds are first met, show the star nudge.
+ * @param {string} cwd
+ * @param {boolean} runSuccess
+ * @param {object} [opts]
+ * @param {boolean} [opts.silent]   record only — never print
+ * @param {function} [opts.write]   sink for the message (default stderr)
+ * @param {string} [opts.today]     override date (testing)
+ * @param {object} [opts.bump]      counter deltas to merge (e.g. { squeezeAccepted: 1 })
+ * @returns {{ usage, nudged }}
+ */
+function checkStarNudge(cwd, runSuccess, opts = {}) {
+  const usage = readUsage(cwd);
+  usage.totalRuns += 1;
+  if (runSuccess) usage.successfulRuns += 1;
+  if (opts.bump) for (const k of Object.keys(opts.bump)) usage[k] = (usage[k] || 0) + opts.bump[k];
+
+  const today = opts.today || new Date().toISOString().slice(0, 10);
+  if (!usage.firstRunDate) usage.firstRunDate = today;
+  usage.lastRunDate = today;
+  if (!usage.machineId) {
+    try { usage.machineId = 'sha256-' + crypto.createHash('sha256').update(os.hostname()).digest('hex').slice(0, 16); } catch (_) {}
+  }
+
+  let nudged = false;
+  if (!usage.starNudgeShown && usage.totalRuns >= RUN_THRESHOLD && usage.successfulRuns >= SUCCESS_THRESHOLD) {
+    // Race-safe single-show: only the process that creates the lock prints.
+    let won = false;
+    try { fs.closeSync(fs.openSync(usagePath(cwd) + '.nudge.lock', 'wx')); won = true; }
+    catch (_) { won = false; }
+    if (won && !opts.silent) showStarNudge(opts.write);
+    nudged = won;
+    usage.starNudgeShown = true;
+  }
+
+  writeUsageAtomic(cwd, usage);
+  return { usage, nudged };
+}
+
+module.exports = { checkStarNudge, readUsage, usagePath, showStarNudge, RUN_THRESHOLD, SUCCESS_THRESHOLD };

package/src/session/notes.js

@@ -0,0 +1,99 @@
+'use strict';
+
+/**
+ * Decision-log notes (Memory, v6.15.0).
+ *
+ * A tiny append-only log of human/agent notes that survives across sessions,
+ * so an agent starting cold can recall "what were we doing / why". Stored as
+ * NDJSON under `.context/` to match the project's other state logs
+ * (usage.ndjson, benchmark-history.ndjson). Zero dependencies.
+ *
+ * Consumed by the `read_memory` MCP tool and the `sigmap note` / `sigmap status`
+ * commands. Complements `src/session/memory.js` (ranking session) rather than
+ * duplicating it.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+const NOTES_FILE = path.join('.context', 'notes.ndjson');
+const MAX_TEXT = 2000;
+
+function notesPath(cwd) {
+  return path.join(cwd, NOTES_FILE);
+}
+
+function _currentBranch(cwd) {
+  try {
+    return execSync('git rev-parse --abbrev-ref HEAD', {
+      cwd, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim() || null;
+  } catch (_) {
+    return null;
+  }
+}
+
+/**
+ * Append a note. Returns the stored entry.
+ * @param {string} cwd
+ * @param {string} text
+ * @param {object} [opts]
+ * @param {string|null} [opts.branch]  override branch (default: current git branch)
+ * @param {string} [opts.tag]          optional category tag
+ */
+function addNote(cwd, text, opts = {}) {
+  const clean = String(text == null ? '' : text).trim().slice(0, MAX_TEXT);
+  if (!clean) throw new Error('note text is empty');
+  const entry = {
+    ts: new Date().toISOString(),
+    text: clean,
+    branch: opts.branch !== undefined ? opts.branch : _currentBranch(cwd),
+  };
+  if (opts.tag) entry.tag = String(opts.tag).trim().slice(0, 40);
+  const p = notesPath(cwd);
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.appendFileSync(p, JSON.stringify(entry) + '\n');
+  return entry;
+}
+
+/**
+ * Read notes in chronological order (oldest first).
+ * @param {string} cwd
+ * @param {number} [limit=0]  keep only the most recent N (0 = all)
+ * @returns {object[]}
+ */
+function readNotes(cwd, limit = 0) {
+  let raw;
+  try { raw = fs.readFileSync(notesPath(cwd), 'utf8'); }
+  catch (_) { return []; }
+  const out = [];
+  for (const line of raw.split('\n')) {
+    const t = line.trim();
+    if (!t) continue;
+    try { out.push(JSON.parse(t)); } catch (_) { /* skip corrupt line */ }
+  }
+  if (limit > 0 && out.length > limit) return out.slice(out.length - limit);
+  return out;
+}
+
+/** Format notes as a Markdown list (pass already-ordered notes). */
+function formatNotes(notes) {
+  if (!notes || !notes.length) {
+    return 'No notes recorded yet. Add one with: sigmap note "<text>"';
+  }
+  return notes.map((n) => {
+    const when = String(n.ts || '').replace('T', ' ').slice(0, 16);
+    const br = n.branch ? ` (${n.branch})` : '';
+    const tag = n.tag ? ` #${n.tag}` : '';
+    return `- [${when}${br}]${tag} ${n.text}`;
+  }).join('\n');
+}
+
+/** Delete the notes log. Returns true if a file was removed. */
+function clearNotes(cwd) {
+  try { fs.unlinkSync(notesPath(cwd)); return true; }
+  catch (_) { return false; }
+}
+
+module.exports = { notesPath, addNote, readNotes, formatNotes, clearNotes };

package/src/squeeze/cilog.js

@@ -0,0 +1,71 @@
+'use strict';
+
+/**
+ * CI / build-log squeeze (v7.0.0).
+ *
+ * Strips timestamps, progress bars, and repeated noise; keeps every error line
+ * plus a small context window around it. Never returns empty — when there are
+ * no errors it falls back to a head/tail summary. Also reused by the stacktrace
+ * squeezer to clean noise surrounding a trace.
+ */
+
+const TS_PREFIX_RE = /^\s*(?:\[?\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}(?:[.,]\d+)?Z?\]?\s*|\[?\d{1,2}:\d{2}:\d{2}(?:[.,]\d+)?\]?\s*)+/;
+const PROGRESS_LINE_RE = /(?:^|\s)(?:\d{1,3}%|Downloading|Receiving objects|Resolving deltas|Compressing objects|npm (?:WARN|notice|http|sill|verb)|##\[(?:group|endgroup|command|section)\]|\[\d+\/\d+\]|ETA[: ]|█|━|▕|⣿)/;
+const ERROR_RE = /\b(?:error|err!|fail(?:ed|ure)?|exception|panic|fatal|traceback|ERR_|E[A-Z]{3,})\b|✗|❌/i;
+
+/** Remove a leading timestamp prefix from a single line. */
+function stripTimestamp(line) {
+  return line.replace(TS_PREFIX_RE, '');
+}
+
+/**
+ * @param {string} input
+ * @param {object} [opts]
+ * @param {number} [opts.context=2]  context lines kept around each error
+ * @returns {{ squeezed: string, kept: string[], stripped: string[] }}
+ */
+function squeezeCiLog(input, opts = {}) {
+  const ctx = opts.context != null ? opts.context : 2;
+  const lines = input.split('\n');
+  const keep = new Set();
+  const errorIdx = [];
+
+  for (let i = 0; i < lines.length; i++) {
+    if (ERROR_RE.test(lines[i])) {
+      errorIdx.push(i);
+      for (let j = Math.max(0, i - ctx); j <= Math.min(lines.length - 1, i + ctx); j++) keep.add(j);
+    }
+  }
+
+  let body;
+  let keptDesc;
+  if (errorIdx.length === 0) {
+    const head = lines.slice(0, 10).map(stripTimestamp);
+    const tail = lines.length > 20 ? lines.slice(-10).map(stripTimestamp) : [];
+    body = head.slice();
+    if (tail.length) body.push(`… (${lines.length - 20} lines omitted) …`, ...tail);
+    keptDesc = ['head/tail summary (no error lines found)'];
+  } else {
+    const sorted = [...keep].sort((a, b) => a - b);
+    body = [];
+    let prev = -2;
+    for (const idx of sorted) {
+      // Drop pure progress/noise lines unless they are themselves errors.
+      const line = stripTimestamp(lines[idx]);
+      if (PROGRESS_LINE_RE.test(line) && !ERROR_RE.test(line)) continue;
+      if (idx > prev + 1) body.push(`… (${idx - prev - 1} lines) …`);
+      body.push(line);
+      prev = idx;
+    }
+    if (body.length === 0) body = errorIdx.map((i) => stripTimestamp(lines[i])); // safety net
+    keptDesc = [`${errorIdx.length} error line(s) + ${ctx}-line context`];
+  }
+
+  return {
+    squeezed: body.join('\n'),
+    kept: keptDesc,
+    stripped: [`${Math.max(0, lines.length - body.length)} timestamp/progress/noise line(s)`],
+  };
+}
+
+module.exports = { squeezeCiLog, stripTimestamp, ERROR_RE };