auxilo-mcp 0.8.2 → 0.9.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "auxilo-mcp",
-  "version": "0.8.2",
-  "description": "MCP server for Auxilo — Agent Capability Discovery & Knowledge Marketplace",
+  "version": "0.9.0",
+  "description": "MCP server for Auxilo \u2014 Agent Capability Discovery & Knowledge Marketplace",
   "main": "mcp-server.js",
   "bin": {
     "auxilo-mcp": "mcp-server.js",
@@ -14,6 +14,7 @@
     "lib/review.js",
     "lib/sensitivity-filter.js",
     "scripts/runner.js",
+    "scripts/capture-core.js",
     "scripts/sources/",
     "scripts/hooks/auxilo-extract.sh",
     "README.md",
@@ -49,4 +50,4 @@
   "devDependencies": {
     "proxyquire": "^2.1.3"
   }
-}
+}

package/scripts/capture-core.js

@@ -0,0 +1,218 @@
+#!/usr/bin/env node
+
+/**
+ * scripts/capture-core.js — Shared hook capture core (UC-1)
+ *
+ * The single entry point invoked by every per-client generated hook shim:
+ *
+ *   <client session-end hook> | node capture-core.js --source <id>
+ *
+ * Reads the client's session-end JSON from stdin, extracts the transcript
+ * path tolerantly across hook dialects (Claude Code / Cursor / Gemini CLI
+ * send `transcript_path`; Antigravity sends `transcriptPath`; Windsurf nests
+ * it as `tool_info.transcript_path`; others use `transcript` or `chat_file`),
+ * enforces the same guards as the proven
+ * LW-12/LW-17 Claude Code hook script (lib/installer.js renderHookScript):
+ *
+ *   1. Consent sentinel  <home>/.auxilo/autonomous-enabled must exist
+ *   2. Recursion guard   AUXILO_EXTRACTING must not be "1" — and is NEVER
+ *                        exported into the spawned runner (P1-13 lesson:
+ *                        exporting it trips the runner's own guard and
+ *                        silently no-ops every run)
+ *   3. Transcript file must exist
+ *
+ * then spawns the extraction runner detached so the host client's session
+ * teardown is never blocked:
+ *
+ *   node <dir-of-this-file>/runner.js --transcript <path> --source <id>
+ *
+ * The runner path resolves relative to THIS file's __dirname (P1-13:
+ * installed copies under ~/.auxilo/bin/scripts/ must run the installed
+ * runner, never reach back into ~/Documents).
+ *
+ * stdout of the runner goes to /dev/null (LW-17: runner.js log() already
+ * appends every line to extract.log itself — redirecting stdout there too
+ * double-wrote each line and the daily digest double-counted). stderr is
+ * appended to <home>/.auxilo/extract.log to capture crashes.
+ *
+ * FAIL-SILENT CONTRACT: a broken hook must never break the host client.
+ * Every non-happy path exits 0 with no output. No exceptions escape main().
+ *
+ * Flags:
+ *   --source <id>    source type forwarded to the runner (default claude-code)
+ *   --home <dir>     home dir override (tests; default env HOME / os.homedir())
+ *   --runner <path>  runner script override (tests; default __dirname/runner.js)
+ *
+ * @module capture-core
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { spawn } = require('child_process');
+
+/**
+ * Flat transcript-path keys tried in order, covering known hook dialects.
+ * One NESTED dialect exists too: Windsurf wraps the path as
+ * `tool_info.transcript_path` — extractTranscriptPath probes it after
+ * `transcriptPath` and before `transcript` (UC-1).
+ */
+const TRANSCRIPT_KEYS = ['transcript_path', 'transcriptPath', 'transcript', 'chat_file'];
+
+/**
+ * GOV-3 M3: refuse to hand the runner anything implausibly large — the
+ * adapters read the whole file into memory, so an untrusted hook payload
+ * naming a multi-GB file is a trivial local OOM. Real transcripts top out
+ * in the single-digit MB.
+ */
+const MAX_TRANSCRIPT_BYTES = 25 * 1024 * 1024;
+
+/** GOV-3 M4: transcripts are text artifacts — gate on plausible extensions. */
+const TRANSCRIPT_EXTS = Object.freeze(['.jsonl', '.json', '.md', '.txt']);
+
+/**
+ * GOV-3 M4: the hook payload is UNTRUSTED third-party input, and this process
+ * will read+upload whatever file it names. Constrain the (symlink-resolved)
+ * path to known client transcript roots instead of "any file on disk" —
+ * otherwise a malicious payload exfiltrates arbitrary JSONL-shaped files and
+ * the only defenses left are the format probe and the scrubber (defense in
+ * depth, not a boundary).
+ */
+function transcriptRoots(homeDir) {
+  return [
+    path.join(homeDir, '.claude'),
+    path.join(homeDir, '.cursor'),
+    path.join(homeDir, '.gemini'),
+    path.join(homeDir, '.codex'),
+    path.join(homeDir, '.factory'),
+    path.join(homeDir, '.copilot'),
+    path.join(homeDir, '.codeium'),
+    path.join(homeDir, '.windsurf'),
+    path.join(homeDir, '.openclaw'),
+    path.join(homeDir, '.auxilo'),
+    path.join(homeDir, 'Library', 'Application Support'),
+  ];
+}
+
+/** True iff realPath sits under a known transcript root AND has a text extension.
+ *  Roots are symlink-resolved too, so the comparison is realpath-vs-realpath
+ *  (macOS /var → /private/var would otherwise defeat a correct path). */
+function transcriptPathAllowed(realPath, homeDir) {
+  if (!TRANSCRIPT_EXTS.includes(path.extname(realPath).toLowerCase())) return false;
+  return transcriptRoots(homeDir).some((root) => {
+    let realRoot = root;
+    try { realRoot = fs.realpathSync(root); } catch { /* root may not exist yet */ }
+    return realPath === realRoot || realPath.startsWith(realRoot + path.sep);
+  });
+}
+
+function parseArgs(argv) {
+  const args = { source: 'claude-code', home: null, runner: null };
+  for (let i = 2; i < argv.length; i++) {
+    if (argv[i] === '--source' && argv[i + 1]) args.source = argv[++i];
+    else if (argv[i] === '--home' && argv[i + 1]) args.home = argv[++i];
+    else if (argv[i] === '--runner' && argv[i + 1]) args.runner = argv[++i];
+  }
+  return args;
+}
+
+/** Extract a transcript path from a parsed hook payload. Returns null if absent. */
+function extractTranscriptPath(payload) {
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) return null;
+  const nested = payload.tool_info && typeof payload.tool_info === 'object' &&
+    !Array.isArray(payload.tool_info) ? payload.tool_info.transcript_path : undefined;
+  const candidates = [
+    payload.transcript_path,
+    payload.transcriptPath,
+    nested, // Windsurf nests it under tool_info (UC-1)
+    payload.transcript,
+    payload.chat_file,
+  ];
+  for (const v of candidates) {
+    if (typeof v === 'string' && v.trim().length > 0) return v.trim();
+  }
+  return null;
+}
+
+function readStdin() {
+  return new Promise((resolve) => {
+    let data = '';
+    process.stdin.setEncoding('utf-8');
+    process.stdin.on('data', (c) => { data += c; });
+    process.stdin.on('end', () => resolve(data));
+    process.stdin.on('error', () => resolve(data));
+  });
+}
+
+async function main() {
+  const args = parseArgs(process.argv);
+  const homeDir = args.home || process.env.HOME || os.homedir();
+  const auxiloDir = path.join(homeDir, '.auxilo');
+
+  // 1. Consent sentinel — kill-switch shared by every capture class (UC §6).
+  if (!fs.existsSync(path.join(auxiloDir, 'autonomous-enabled'))) return;
+
+  // 2. Recursion guard — bail if we're already inside an extraction chain.
+  if (process.env.AUXILO_EXTRACTING === '1') return;
+
+  // 3. Hook payload → transcript path (tolerant across dialects).
+  const raw = await readStdin();
+  let payload;
+  try { payload = JSON.parse(raw); } catch { return; }
+  const namedPath = extractTranscriptPath(payload);
+  if (!namedPath) return;
+
+  // GOV-3 M4: resolve symlinks BEFORE validating, and use the resolved path
+  // from here on — a symlink under an allowed root must not reach outside it.
+  let transcriptPath;
+  try { transcriptPath = fs.realpathSync(namedPath); } catch { return; }
+  if (!transcriptPathAllowed(transcriptPath, homeDir)) return;
+
+  let stat;
+  try { stat = fs.statSync(transcriptPath); } catch { return; }
+  if (!stat.isFile()) return;
+  if (stat.size > MAX_TRANSCRIPT_BYTES) return; // GOV-3 M3: local-OOM guard
+
+  // 4. Runner resolution — relative to OUR location (P1-13).
+  const runnerPath = args.runner || path.join(__dirname, 'runner.js');
+  if (!fs.existsSync(runnerPath)) return;
+
+  // 5. Spawn detached. stdout → /dev/null (LW-17 double-write), stderr →
+  //    extract.log for crash capture. Never export AUXILO_EXTRACTING.
+  const env = { ...process.env };
+  delete env.AUXILO_EXTRACTING;
+  if (args.home) env.HOME = args.home; // keep test homes hermetic
+
+  let stderrFd = 'ignore';
+  try {
+    fs.mkdirSync(auxiloDir, { recursive: true });
+    stderrFd = fs.openSync(path.join(auxiloDir, 'extract.log'), 'a');
+  } catch { /* fall back to ignore — fail-silent */ }
+
+  const child = spawn(process.execPath,
+    [runnerPath, '--transcript', transcriptPath, '--source', args.source],
+    { detached: true, stdio: ['ignore', 'ignore', stderrFd], env });
+  child.on('error', () => { /* fail-silent */ });
+  child.unref();
+
+  if (typeof stderrFd === 'number') {
+    try { fs.closeSync(stderrFd); } catch { /* already closed */ }
+  }
+}
+
+module.exports = {
+  parseArgs,
+  extractTranscriptPath,
+  transcriptPathAllowed,
+  transcriptRoots,
+  TRANSCRIPT_KEYS,
+  TRANSCRIPT_EXTS,
+  MAX_TRANSCRIPT_BYTES,
+};
+
+if (require.main === module) {
+  // Fail-silent: exit 0 on every path, swallow everything.
+  main().then(() => process.exit(0)).catch(() => process.exit(0));
+}

package/scripts/runner.js

@@ -39,6 +39,9 @@ const crypto = require('crypto');
 const { scanText, SENSITIVITY_FILTER_VERSION } = require('../lib/sensitivity-filter.js');
 const { ClaudeCodeSource } = require('./sources/claude-code.js');
 const { OpenClawSource } = require('./sources/openclaw.js');
+const { GeminiCliSource } = require('./sources/gemini-cli.js');
+const { AntigravitySource } = require('./sources/antigravity.js');
+const { GenericJsonlSource } = require('./sources/generic-jsonl.js');
 
 // ─── Constants ──────────────────────────────────────────────────────────────
 
@@ -89,6 +92,8 @@ const LOG_PATH = path.join(AUXILO_DIR, 'extract.log');
 const SOURCES = [
   ClaudeCodeSource,
   OpenClawSource,
+  GeminiCliSource,
+  AntigravitySource,
 ];
 
 async function enumerateActiveSources(filter) {
@@ -615,16 +620,21 @@ async function main() {
       process.exit(1);
     }
 
-    // Pick the right source adapter based on file location — default to
-    // claude-code since it can parse either JSONL or plain text, and
-    // works for most hook-fired single-file invocations.
+    // Pick the right source adapter — capture-core forwards the client id
+    // via --source (UC-1). Default to claude-code since it can parse either
+    // JSONL or plain text. Unknown ids (cursor, windsurf, codex, copilot,
+    // factory, ...) fall back to the generic Claude-style JSONL normalizer,
+    // which tags uploads with the actual client id and refuses (fail-silent)
+    // anything that doesn't probe as JSONL.
     const sourceType = args.source || 'claude-code';
     const SourceClass = SOURCES.find(S => S.id === sourceType);
-    if (!SourceClass) {
-      log(`[runner] Unknown source type: ${sourceType}`);
-      process.exit(1);
+    let source;
+    if (SourceClass) {
+      source = new SourceClass();
+    } else {
+      log(`[runner] No dedicated adapter for source "${sourceType}" — using generic-jsonl fallback`);
+      source = new GenericJsonlSource({ id: sourceType });
     }
-    const source = new SourceClass();
     const sessionId = path.basename(transcriptPath, path.extname(transcriptPath));
     const stat = fs.statSync(transcriptPath);
     const sessionRef = {
@@ -649,6 +659,14 @@ async function main() {
       }
     }
 
+    // UC-1 format-probe refusal: adapters return null (never throw) when a
+    // file doesn't match their expected shape. Skip — do NOT fall back to
+    // raw text, that would mis-parse garbage into a transcript (UC §5).
+    if (!transcriptData || typeof transcriptData.transcript !== 'string') {
+      log(`[runner] Format probe refused ${transcriptPath} (source=${source.type}). Exiting.`);
+      process.exit(0);
+    }
+
     let transcript = transcriptData.transcript;
     if (transcript.length < MIN_CHARS) {
       log(`[runner] Too short (${transcript.length} chars, min ${MIN_CHARS}). Exiting.`);
@@ -668,6 +686,23 @@ async function main() {
       log(`[runner] Scrubbed ${report.patterns_matched.length} sensitive pattern(s): ${[...new Set(report.patterns_matched)].join(', ')} ${DIGEST_ACCOUNT}`);
     }
 
+    // GOV-3 M2: content-sha ledger dedup for single-file mode. Some clients
+    // fire their capture hook PER RESPONSE / PER TURN, not at session end
+    // (Windsurf post_cascade_response_with_transcript; Codex/Antigravity
+    // Stop). Without this, each firing re-uploads the whole transcript-so-far
+    // as a fresh extraction (new idempotency key per call), burning rate
+    // limit and re-running the LLM on growing partials. Keyed on the cleaned
+    // content sha so identical/already-seen content is skipped. --force
+    // bypasses (targeted re-test).
+    const contentSha = crypto.createHash('sha256').update(cleaned).digest('hex');
+    if (!args.force) {
+      const ledger = loadLedger();
+      if (ledgerHas(ledger, sourceType, sessionId, contentSha)) {
+        log(`[runner] Already uploaded this content (source=${sourceType} session=${sessionId}). Skipping.`);
+        process.exit(0);
+      }
+    }
+
     if (args.dryRun) {
       log(`[runner] [DRY RUN] Would upload ${cleaned.length} chars to ${BASE_URL}/extract`);
       process.exit(0);
@@ -676,6 +711,10 @@ async function main() {
     try {
       const result = await postExtract(cleaned, sessionId, sourceType, report);
       log(`[runner] ✓ published=${result.learnings_published || 0} rejected=${result.learnings_rejected || 0} ${DIGEST_ACCOUNT} (extraction: ${result.extraction_id})`);
+      // Mark only after a successful upload so a failed POST can be retried.
+      const ledger = loadLedger();
+      ledgerMark(ledger, sourceType, sessionId, contentSha, sessionRef.mtime);
+      saveLedger(ledger);
       process.exit(0);
     } catch (err) {
       log(`[runner] ✗ Upload failed: ${err.message}`);
@@ -751,6 +790,14 @@ async function main() {
         continue;
       }
 
+      // UC-1 format-probe refusal: null = skip silently (not a failure).
+      if (!transcriptData || typeof transcriptData.transcript !== 'string') {
+        log(`[runner]   Skipped — format probe refused (source=${source.type})`);
+        totalSkipped++;
+        ledgerMark(ledger, source.type, sessionRef.sessionId, 'probe-refused', sessionRef.mtime);
+        continue;
+      }
+
       let transcript = transcriptData.transcript;
 
       // Size check

package/scripts/sources/antigravity.js

@@ -0,0 +1,131 @@
+/**
+ * scripts/sources/antigravity.js — Antigravity Transcript Source (UC-1)
+ *
+ * Discovers and reads Antigravity per-conversation JSONL transcript logs.
+ * Default location:
+ *   ~/.gemini/antigravity/brain/<conversation-id>/.system_generated/logs/*.jsonl
+ *
+ * Expected line shape: Claude-style JSONL dialect — one JSON object per line
+ * carrying `role`/`content`, `message.role`/`message.content`, or
+ * `sender`/`content`. Tool/function-call internals are skipped.
+ *
+ * GROUND-TRUTH NOTE (verified on this machine, 2026-06-12): the local
+ * Antigravity install stores conversations as binary protobuf
+ * (~/.gemini/antigravity/conversations/*.pb) and its brain dirs contained NO
+ * .system_generated/logs/*.jsonl — only click_feedback PNGs and inter-agent
+ * messages/*.json ({id, recipient, sender, priority, timestamp, hideFromUser,
+ * content}). The logs/*.jsonl path comes from the UC research pass (hook
+ * payloads hand a `transcriptPath` pointing there on hook-enabled builds).
+ * The strict JSONL probe + fail-silent contract means that if the real format
+ * differs, this adapter degrades to "skipped with one log line" — it never
+ * mis-parses (UC §5 risk rule).
+ *
+ * @module sources/antigravity
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { TranscriptSource } = require('./source.interface');
+const { normalizeJsonlLines, probeJsonl } = require('./generic-jsonl');
+
+class AntigravitySource extends TranscriptSource {
+  static id = 'antigravity';
+  static displayName = 'Antigravity (Google)';
+  static version = '1.0.0';
+
+  constructor(config = {}) {
+    super(config);
+    /** @type {string} Root brain dir holding per-conversation artifacts */
+    this.dataDir = config.dataDir || path.join(os.homedir(), '.gemini', 'antigravity', 'brain');
+  }
+
+  /** Detect: the brain directory exists and is readable. */
+  async detect() {
+    try {
+      return fs.statSync(this.dataDir).isDirectory();
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Discover transcript logs under
+   * <dataDir>/<conversation-id>/.system_generated/logs/*.jsonl
+   * modified after `since`.
+   */
+  async discoverSessions({ since } = {}) {
+    const results = [];
+    const sinceMs = since ? new Date(since).getTime() : 0;
+
+    let conversations;
+    try {
+      conversations = fs.readdirSync(this.dataDir).filter(c => {
+        try { return fs.statSync(path.join(this.dataDir, c)).isDirectory(); }
+        catch { return false; }
+      });
+    } catch {
+      return results;
+    }
+
+    for (const conv of conversations) {
+      const logsDir = path.join(this.dataDir, conv, '.system_generated', 'logs');
+      let files;
+      try { files = fs.readdirSync(logsDir).filter(f => f.endsWith('.jsonl')); }
+      catch { continue; } // most brain dirs have no logs — fine
+
+      for (const file of files) {
+        const filePath = path.join(logsDir, file);
+        try {
+          const stat = fs.statSync(filePath);
+          if (!stat.isFile()) continue;
+          if (stat.mtimeMs <= sinceMs) continue;
+          results.push({
+            sessionId: `${conv}-${path.basename(file, '.jsonl')}`,
+            path: filePath,
+            mtime: stat.mtime.toISOString(),
+            bytes: stat.size,
+          });
+        } catch { /* skip unreadable files */ }
+      }
+    }
+
+    return results;
+  }
+
+  /**
+   * Read + normalize one JSONL transcript. Returns null (single stderr log
+   * line) when the format probe refuses — never throws on bad format.
+   */
+  async readSession(sessionRef) {
+    const filePath = sessionRef.path;
+    if (!filePath || !fs.existsSync(filePath)) {
+      throw new Error(`Transcript file not found: ${filePath}`);
+    }
+
+    const content = fs.readFileSync(filePath, 'utf-8');
+    const lines = content.split('\n').filter(l => l.trim());
+
+    if (!probeJsonl(lines)) {
+      process.stderr.write(`[antigravity] format probe refused ${filePath} — skipping\n`);
+      return null;
+    }
+
+    return {
+      transcript: normalizeJsonlLines(lines),
+      metadata: {
+        sessionId: sessionRef.sessionId,
+        source: 'antigravity',
+        mtime: sessionRef.mtime,
+        bytes: sessionRef.bytes,
+      },
+    };
+  }
+
+  /** Hook wiring (Antigravity hooks.json, Stop event) is the installer's job. */
+  async registerSessionEndHook(cb) { return null; }
+}
+
+module.exports = { AntigravitySource };

package/scripts/sources/gemini-cli.js

@@ -0,0 +1,178 @@
+/**
+ * scripts/sources/gemini-cli.js — Gemini CLI Transcript Source (UC-1)
+ *
+ * Discovers and reads auto-saved Gemini CLI session JSON files.
+ * Default location: ~/.gemini/tmp/<project_hash>/chats/*.json
+ *
+ * KNOWN SHAPES (format probe accepts exactly these, refuses everything else):
+ *
+ *   A. Session auto-save object:
+ *        { sessionId?, startTime?, lastUpdated?,
+ *          messages: [ { id?, type: "user"|"gemini", content: string, ... } ] }
+ *
+ *   B. Checkpoint (`/chat save`) — Gemini API Content list, either bare or
+ *      wrapped:
+ *        [ { role: "user"|"model", parts: [ {text} | {functionCall} | {functionResponse} ] } ]
+ *        { history: [ ...same... ] }
+ *
+ *   NOTE (2026-06-12): built from the documented Gemini CLI session formats.
+ *   No ~/.gemini/tmp data existed on the build machine to verify against —
+ *   only Antigravity uses ~/.gemini here. The strict probe + fail-silent
+ *   contract means a drifted real-world format degrades to "skipped with one
+ *   log line", never a mis-parse (UC §5 risk rule).
+ *
+ * Normalization: user/model turns concatenated as `[user]:` / `[assistant]:`
+ * blocks (same convention as the claude-code adapter). Tool/function-call
+ * internals and thinking parts are skipped.
+ *
+ * @module sources/gemini-cli
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { TranscriptSource } = require('./source.interface');
+const { normalizeRole } = require('./generic-jsonl');
+
+/** Extract user-visible text from a Gemini Content `parts` array. */
+function textFromParts(parts) {
+  if (!Array.isArray(parts)) return '';
+  return parts
+    .filter(p => p && typeof p.text === 'string' && !p.thought) // skip functionCall/functionResponse/thought parts
+    .map(p => p.text)
+    .filter(Boolean)
+    .join('\n');
+}
+
+class GeminiCliSource extends TranscriptSource {
+  static id = 'gemini-cli';
+  static displayName = 'Gemini CLI (Google)';
+  static version = '1.0.0';
+
+  constructor(config = {}) {
+    super(config);
+    /** @type {string} Root dir for Gemini CLI per-project temp data */
+    this.dataDir = config.dataDir || path.join(os.homedir(), '.gemini', 'tmp');
+  }
+
+  /** Detect: ~/.gemini/tmp exists and is a readable directory. */
+  async detect() {
+    try {
+      return fs.statSync(this.dataDir).isDirectory();
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Discover session JSON files under <dataDir>/<project_hash>/chats/*.json
+   * modified after `since`.
+   */
+  async discoverSessions({ since } = {}) {
+    const results = [];
+    const sinceMs = since ? new Date(since).getTime() : 0;
+
+    let hashes;
+    try {
+      hashes = fs.readdirSync(this.dataDir).filter(h => {
+        try { return fs.statSync(path.join(this.dataDir, h)).isDirectory(); }
+        catch { return false; }
+      });
+    } catch {
+      return results;
+    }
+
+    for (const hash of hashes) {
+      const chatsDir = path.join(this.dataDir, hash, 'chats');
+      let files;
+      try { files = fs.readdirSync(chatsDir).filter(f => f.endsWith('.json')); }
+      catch { continue; } // no chats dir for this project — fine
+
+      for (const file of files) {
+        const filePath = path.join(chatsDir, file);
+        try {
+          const stat = fs.statSync(filePath);
+          if (!stat.isFile()) continue;
+          if (stat.mtimeMs <= sinceMs) continue;
+          results.push({
+            sessionId: `${hash}-${path.basename(file, '.json')}`,
+            path: filePath,
+            mtime: stat.mtime.toISOString(),
+            bytes: stat.size,
+          });
+        } catch { /* skip unreadable files */ }
+      }
+    }
+
+    return results;
+  }
+
+  /**
+   * Read + normalize one session file. Returns null (single stderr log line)
+   * when the format probe refuses — never throws on bad format, never
+   * mis-parses garbage into a transcript.
+   */
+  async readSession(sessionRef) {
+    const filePath = sessionRef.path;
+    if (!filePath || !fs.existsSync(filePath)) {
+      throw new Error(`Transcript file not found: ${filePath}`);
+    }
+
+    let parsed;
+    try {
+      parsed = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+    } catch {
+      return this._refuse(filePath, 'not valid JSON');
+    }
+
+    const turns = [];
+
+    if (parsed && !Array.isArray(parsed) && Array.isArray(parsed.messages)) {
+      // Shape A: session auto-save { messages: [{ type, content }] }
+      for (const m of parsed.messages) {
+        if (!m || typeof m !== 'object') continue;
+        const role = normalizeRole(m.type ?? m.role);
+        if (!role) continue; // tool/info/error entries — skip
+        const text = typeof m.content === 'string' ? m.content : textFromParts(m.content);
+        if (text && text.trim().length > 0) turns.push(`[${role}]: ${text}`);
+      }
+    } else {
+      // Shape B: checkpoint Content list — bare array or { history: [...] }
+      const history = Array.isArray(parsed) ? parsed
+        : (parsed && Array.isArray(parsed.history)) ? parsed.history
+        : null;
+      if (!history) return this._refuse(filePath, 'no messages/history array');
+
+      for (const c of history) {
+        if (!c || typeof c !== 'object') continue;
+        const role = normalizeRole(c.role);
+        if (!role) continue;
+        const text = textFromParts(c.parts);
+        if (text && text.trim().length > 0) turns.push(`[${role}]: ${text}`);
+      }
+    }
+
+    return {
+      transcript: turns.join('\n\n'),
+      metadata: {
+        sessionId: sessionRef.sessionId,
+        source: 'gemini-cli',
+        mtime: sessionRef.mtime,
+        bytes: sessionRef.bytes,
+      },
+    };
+  }
+
+  /** Single log line + null per the UC §5 fail-silent rule. */
+  _refuse(filePath, reason) {
+    process.stderr.write(`[gemini-cli] format probe refused ${filePath} (${reason}) — skipping\n`);
+    return null;
+  }
+
+  /** Hook wiring (Gemini settings.json hooks) is the installer's job. */
+  async registerSessionEndHook(cb) { return null; }
+}
+
+module.exports = { GeminiCliSource };