specmem-hardwicksoftware 3.7.35 → 3.7.36

package/dist/mcp/compactionProxyDaemon.js

@@ -3,7 +3,7 @@
  * Compaction Proxy Daemon — Standalone Persistent Process
  * ========================================================
  *
- * Survives MCP server restarts. Self-terminates when Claude is gone.
+ * Survives MCP server restarts. Self-terminates when parent is gone.
  *
  * Spawned by startCompactionProxy() in compactionProxy.js.
  * Imports the core handleRequest and all compression logic — zero duplication.
@@ -12,7 +12,8 @@
  *   1. MCP starts → startCompactionProxy() spawns this daemon (detached)
  *   2. MCP dies/restarts → daemon stays alive, port file persists
  *   3. Next MCP start → detects running daemon via PID file, skips spawn
- *   4. Claude exits → KYS watchdog self-terminates after 2 min idle
+ *   4. Parent exits → orphan watchdog detects dead parent PID, starts idle countdown
+ *   5. No requests for ORPHAN_IDLE_TIMEOUT → graceful self-termination
  *
  * @author hardwicksoftwareservices
  * @website https://justcalljon.pro
@@ -20,7 +21,6 @@
 
 import { createServer } from 'http';
 import { writeFileSync, unlinkSync, existsSync, mkdirSync } from 'fs';
-import { execSync } from 'child_process';
 import { createConnection } from 'net';
 import {
   handleRequest,
@@ -34,6 +34,7 @@ import {
   PID_FILE,
   DISABLED_FILE,
   CLAUDE_DIR,
+  getLastRequestTime,
 } from './compactionProxy.js';
 
 // ============================================================================
@@ -68,28 +69,66 @@ function cleanup() {
 }
 
 // ============================================================================
-// KYS Watchdog — self-terminate when Claude is gone
+// Orphan Detection & KYS Watchdog
 // ============================================================================
+//
+// Three-layer orphan detection:
+//   1. Parent PID monitoring — process.kill(ppid, 0) every 30s
+//   2. Socket activity timeout — no requests for N min after parent death
+//   3. Live project registry — hasLiveProjects() as secondary signal
+//
+// Parent alive + idle = fine (Claude may just be thinking).
+// Parent dead + active requests = keep serving (another MCP may have connected).
+// Parent dead + idle + no projects = self-terminate after grace period.
 
-const KYS_INTERVAL = 30000;         // Check every 30s
-const KYS_IDLE_THRESHOLD = 120000;  // 2 minutes without Claude → exit
-const KYS_GRACE_PERIOD = 60000;     // 60s grace after startup
+const KYS_INTERVAL = 30000;                    // Check every 30s
+const ORPHAN_IDLE_TIMEOUT = 10 * 60 * 1000;    // 10 min idle after parent death → exit
+const ORPHAN_GRACE_PERIOD = 60000;              // 60s grace — no kill within first 60s of orphan
+const STARTUP_GRACE_PERIOD = 60000;             // 60s grace after daemon startup
 
-function isClaudeAlive() {
-  // Check registry first — much cheaper than pgrep
-  if (hasLiveProjects()) return true;
-  // Fallback to pgrep for cases where MCP didn't register (old versions)
+// Capture parent PID at module load — this is the spawner (MCP server / bootstrap)
+const _parentPid = process.ppid;
+
+let _orphanDetectedAt = 0;  // 0 = not orphaned
+
+/**
+ * Check if parent process (MCP server / bootstrap) is still alive.
+ * Uses process.kill(pid, 0) — throws ESRCH if process doesn't exist.
+ * Much more reliable than pgrep, and doesn't match unrelated "claude" processes.
+ */
+function isParentAlive() {
+  if (!_parentPid || _parentPid <= 0) return false;
+  // If we've been reparented to init (PID 1), parent is definitely dead
+  if (process.ppid === 1 && _parentPid !== 1) return false;
   try {
-    const result = execSync(
-      'pgrep -f "claude" 2>/dev/null',
-      { encoding: 'utf8', timeout: 5000 }
-    ).trim();
-    return !!result;
-  } catch {
-    return false;
+    process.kill(_parentPid, 0);
+    return true;
+  } catch (e) {
+    // ESRCH = no such process → dead
+    // EPERM = process exists but no permission to signal → still alive
+    return e.code === 'EPERM';
+  }
+}
+
+/**
+ * Touch activity timestamp. Called on every incoming request.
+ */
+function touchActivity() {
+  // If we got a request while orphaned, someone is still using us — reset countdown
+  if (_orphanDetectedAt > 0) {
+    log('info', `ORPHAN-WATCHDOG: request received while orphaned — resetting idle countdown`);
+    _orphanDetectedAt = 0;
   }
 }
 
+/**
+ * Wrapped handleRequest that tracks activity for orphan detection.
+ */
+function wrappedHandleRequest(req, res) {
+  touchActivity();
+  return handleRequest(req, res);
+}
+
 // ============================================================================
 // Main
 // ============================================================================
@@ -107,12 +146,13 @@ async function main() {
     mkdirSync(CLAUDE_DIR, { recursive: true });
   }
 
-  // Write PID file: pid:timestamp
-  const pidData = `${process.pid}:${Date.now()}`;
+  // Write PID file: pid:timestamp:parentPid
+  const pidData = `${process.pid}:${Date.now()}:${_parentPid}`;
   writeFileSync(PID_FILE, pidData, { mode: 0o644 });
+  log('info', `Daemon: wrote PID file (pid=${process.pid}, parent=${_parentPid})`);
 
-  // Create HTTP server using the shared handleRequest from compactionProxy.js
-  const server = createServer(handleRequest);
+  // Create HTTP server using wrapped handleRequest for activity tracking
+  const server = createServer(wrappedHandleRequest);
   server.keepAliveTimeout = 300000;
   server.headersTimeout = 310000;
 
@@ -131,9 +171,9 @@ async function main() {
     // If disabled flag existed at startup, start in passthrough mode
     if (startPaused) {
       setPaused(true);
-      log('info', `Daemon started in PASSTHROUGH mode (disabled flag): PID=${process.pid} port=${PROXY_PORT}`);
+      log('info', `Daemon started in PASSTHROUGH mode (disabled flag): PID=${process.pid} port=${PROXY_PORT} parent=${_parentPid}`);
     } else {
-      log('info', `Daemon started: PID=${process.pid} port=${PROXY_PORT}`);
+      log('info', `Daemon started: PID=${process.pid} port=${PROXY_PORT} parent=${_parentPid}`);
     }
     // Start the stale project reaper
     startReaper();
@@ -162,27 +202,62 @@ async function main() {
     log('info', `Daemon: SIGUSR1 → proxy ${paused ? 'PAUSED' : 'RESUMED'}`);
   });
 
-  // --- KYS Watchdog ---
+  // --- Orphan Detection & KYS Watchdog ---
   const startedAt = Date.now();
-  let lastClaudeSeen = Date.now();
+
+  function gracefulShutdown(reason) {
+    log('warn', `ORPHAN-WATCHDOG: ${reason}`);
+    cleanup();
+    server.close(() => process.exit(0));
+    // Force exit after 5s if server.close() hangs
+    setTimeout(() => process.exit(0), 5000).unref();
+  }
 
   const kysTimer = setInterval(() => {
-    // Grace period — don't kill right after startup
-    if (Date.now() - startedAt < KYS_GRACE_PERIOD) return;
+    // Startup grace period — don't kill right after spawn
+    if (Date.now() - startedAt < STARTUP_GRACE_PERIOD) return;
+
+    const parentAlive = isParentAlive();
+    const idleMs = Date.now() - getLastRequestTime();
+    const hasProjects = hasLiveProjects();
 
-    if (isClaudeAlive()) {
-      lastClaudeSeen = Date.now();
+    if (parentAlive) {
+      // Parent alive — everything is fine, reset orphan state if needed
+      if (_orphanDetectedAt > 0) {
+        log('info', 'ORPHAN-WATCHDOG: parent alive again (re-adopted?) — clearing orphan state');
+        _orphanDetectedAt = 0;
+      }
       return;
     }
 
-    const idleMs = Date.now() - lastClaudeSeen;
-    if (idleMs >= KYS_IDLE_THRESHOLD) {
-      log('info', `Daemon: No Claude for ${(idleMs / 1000).toFixed(0)}s — self-terminating`);
-      cleanup();
-      server.close(() => process.exit(0));
-      // Force exit after 5s if server.close() hangs
-      setTimeout(() => process.exit(0), 5000).unref();
+    // --- Parent is dead ---
+
+    if (_orphanDetectedAt === 0) {
+      // First detection of orphan state
+      _orphanDetectedAt = Date.now();
+      log('warn', `ORPHAN-WATCHDOG: parent PID ${_parentPid} is dead — idle=${Math.round(idleMs / 1000)}s, projects=${hasProjects}`);
+    }
+
+    const orphanDuration = Date.now() - _orphanDetectedAt;
+
+    // Case 1: Parent dead + idle for ORPHAN_IDLE_TIMEOUT → definitely a zombie
+    if (idleMs >= ORPHAN_IDLE_TIMEOUT) {
+      gracefulShutdown(
+        `parent dead + no requests for ${Math.round(idleMs / 1000)}s — self-terminating`
+      );
+      return;
     }
+
+    // Case 2: Parent dead + no live projects + grace period elapsed → nothing to serve
+    if (!hasProjects && orphanDuration >= ORPHAN_GRACE_PERIOD) {
+      gracefulShutdown(
+        `parent dead + no live projects for ${Math.round(orphanDuration / 1000)}s — self-terminating`
+      );
+      return;
+    }
+
+    // Case 3: Parent dead but still getting requests or has live projects — keep serving
+    // (Another MCP server may have connected, or requests still flowing)
   }, KYS_INTERVAL);
   kysTimer.unref();
 }

package/dist/mcp/contextVault.js

@@ -0,0 +1,439 @@
+/**
+ * Context Vault — stash house for thicc tool outputs
+ * ===================================================
+ *
+ * when tool results are bussin a little TOO hard (>5KB),
+ * we chunk em, index with tsvector, and hand back a receipt.
+ * claude can dig for specifics later without burning tokens.
+ *
+ * 315KB tool result → ~800 byte receipt = 99.7% token reduction. it slaps.
+ *
+ * inspired by claude-context-mode, rebuilt from scratch on postgres.
+ * no sqlite, no cap.
+ *
+ * @author hardwicksoftwareservices
+ * @website https://justcalljon.pro
+ */
+
+import { createHash } from 'crypto';
+import { logger } from '../utils/logger.js';
+
+// --- Config ---
+const VAULT_THRESHOLD = 5000;         // chars — auto-stash anything bigger
+const CHUNK_TARGET_SIZE = 1500;       // chars per chunk (target, not hard limit)
+const CHUNK_MAX_SIZE = 4000;          // hard cap — code blocks can be big
+const CHUNK_MIN_SIZE = 100;           // merge anything smaller
+const VAULT_TTL_HOURS = 24;           // auto-expire after 24h
+const MAX_VOCAB_TERMS = 30;           // vocabulary terms in the receipt
+const PREVIEW_CHARS = 300;            // preview length in receipt
+
+// tools that should NEVER get auto-vaulted (prevent recursion)
+const VAULT_SKIP_TOOLS = new Set([
+  'stash_the_goods',
+  'dig_in_the_vault',
+]);
+
+// english stopwords — filtered from vocabulary extraction
+const STOPWORDS = new Set([
+  'the','be','to','of','and','a','in','that','have','i','it','for','not','on',
+  'with','he','as','you','do','at','this','but','his','by','from','they','we',
+  'say','her','she','or','an','will','my','one','all','would','there','their',
+  'what','so','up','out','if','about','who','get','which','go','me','when',
+  'make','can','like','time','no','just','him','know','take','people','into',
+  'year','your','good','some','could','them','see','other','than','then','now',
+  'look','only','come','its','over','think','also','back','after','use','two',
+  'how','our','work','first','well','way','even','new','want','because','any',
+  'these','give','day','most','us','is','are','was','were','been','has','had',
+  'did','does','done','may','might','shall','should','must','need','could',
+  'would','will','true','false','null','undefined','function','return','const',
+  'let','var','import','export','from','class','async','await','try','catch',
+  'throw','typeof','instanceof','void','this','super','extends',
+  'type','string','number','boolean','object','array',
+]);
+
+let _pool = null;
+let _tableReady = false;
+let _projectPath = '/';
+
+// --- Init ---
+export function initContextVault(pool, projectPath) {
+  _pool = pool;
+  _projectPath = projectPath || '/';
+}
+
+export function setVaultProjectPath(p) { _projectPath = p || '/'; }
+
+export { VAULT_THRESHOLD, VAULT_SKIP_TOOLS };
+
+// --- Table creation (fallback if migration 38 hasn't run yet) ---
+async function ensureTable() {
+  if (_tableReady || !_pool) return;
+  try {
+    await _pool.query(`
+      CREATE TABLE IF NOT EXISTS context_vault (
+        id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+        vault_id VARCHAR(16) NOT NULL,
+        chunk_idx INTEGER NOT NULL DEFAULT 0,
+        content TEXT NOT NULL,
+        content_tsv TSVECTOR GENERATED ALWAYS AS (to_tsvector('english', content)) STORED,
+        source_tool VARCHAR(128),
+        source_size INTEGER DEFAULT 0,
+        metadata JSONB DEFAULT '{}',
+        project_path VARCHAR(500) DEFAULT '/',
+        stashed_at TIMESTAMPTZ DEFAULT NOW(),
+        expires_at TIMESTAMPTZ DEFAULT (NOW() + INTERVAL '24 hours'),
+        UNIQUE(vault_id, chunk_idx)
+      );
+      CREATE INDEX IF NOT EXISTS idx_ctx_vault_tsv ON context_vault USING GIN(content_tsv);
+      CREATE INDEX IF NOT EXISTS idx_ctx_vault_id ON context_vault(vault_id);
+      CREATE INDEX IF NOT EXISTS idx_ctx_vault_expires ON context_vault(expires_at);
+      CREATE INDEX IF NOT EXISTS idx_ctx_vault_project ON context_vault(project_path);
+    `);
+    _tableReady = true;
+  } catch (err) {
+    // table might already exist from migration 38 — that's fine
+    if (err.message?.includes('already exists') || err.code === '42P07') {
+      _tableReady = true;
+    } else {
+      logger.warn({ error: err.message }, 'context_vault ensureTable failed');
+    }
+  }
+}
+
+// =============================================================================
+// Chunking — split content by natural boundaries, keep code blocks intact
+// =============================================================================
+
+function chunkContent(content) {
+  if (content.length <= CHUNK_TARGET_SIZE) return [content];
+
+  // Phase 1: protect code blocks from splitting
+  const codeBlocks = [];
+  const withPlaceholders = content.replace(/```[\s\S]*?```/g, (match) => {
+    const idx = codeBlocks.length;
+    codeBlocks.push(match);
+    return `\n__CB${idx}__\n`;
+  });
+
+  // Phase 2: split by markdown headings first, then paragraphs
+  const rawParts = withPlaceholders.split(/(?=^#{1,4}\s)/m);
+
+  const expandedParts = [];
+  for (const part of rawParts) {
+    if (part.length <= CHUNK_TARGET_SIZE) {
+      expandedParts.push(part);
+    } else {
+      // long section — split by paragraphs
+      const paragraphs = part.split(/\n{2,}/);
+      expandedParts.push(...paragraphs);
+    }
+  }
+
+  // Phase 3: merge small parts, split oversized ones
+  const chunks = [];
+  let buffer = '';
+
+  for (let raw of expandedParts) {
+    // restore code blocks in this part
+    raw = raw.replace(/__CB(\d+)__/g, (_, idx) => codeBlocks[parseInt(idx)] || '');
+
+    if (!raw.trim()) continue;
+
+    if (buffer.length + raw.length + 2 <= CHUNK_TARGET_SIZE) {
+      buffer += (buffer ? '\n\n' : '') + raw;
+    } else {
+      if (buffer.trim()) chunks.push(buffer.trim());
+
+      if (raw.length > CHUNK_MAX_SIZE) {
+        // split oversized by sentences
+        const sentences = raw.match(/[^.!?\n]+[.!?\n]+/g) || [raw];
+        let sentBuf = '';
+        for (const sent of sentences) {
+          if (sentBuf.length + sent.length > CHUNK_TARGET_SIZE && sentBuf) {
+            chunks.push(sentBuf.trim());
+            sentBuf = '';
+          }
+          sentBuf += sent;
+        }
+        buffer = sentBuf;
+      } else {
+        buffer = raw;
+      }
+    }
+  }
+  if (buffer.trim()) chunks.push(buffer.trim());
+
+  // Phase 4: merge tiny chunks into neighbors
+  const merged = [];
+  let mergeBuffer = '';
+  for (const chunk of chunks) {
+    if (chunk.length < CHUNK_MIN_SIZE && mergeBuffer.length + chunk.length < CHUNK_TARGET_SIZE) {
+      mergeBuffer += (mergeBuffer ? '\n\n' : '') + chunk;
+    } else {
+      if (mergeBuffer) {
+        if (mergeBuffer.length < CHUNK_MIN_SIZE && merged.length > 0) {
+          merged[merged.length - 1] += '\n\n' + mergeBuffer;
+        } else {
+          merged.push(mergeBuffer);
+        }
+        mergeBuffer = '';
+      }
+      merged.push(chunk);
+    }
+  }
+  if (mergeBuffer) {
+    if (merged.length > 0) {
+      merged[merged.length - 1] += '\n\n' + mergeBuffer;
+    } else {
+      merged.push(mergeBuffer);
+    }
+  }
+
+  return merged.filter(c => c.length > 0);
+}
+
+// =============================================================================
+// Vocabulary extraction — top N terms by frequency, excluding stopwords
+// =============================================================================
+
+function extractVocabulary(content) {
+  const words = content
+    .toLowerCase()
+    .replace(/[^a-z0-9_\s-]/g, ' ')
+    .split(/\s+/)
+    .filter(w => w.length > 2 && w.length < 30 && !STOPWORDS.has(w));
+
+  const freq = {};
+  for (const w of words) {
+    freq[w] = (freq[w] || 0) + 1;
+  }
+
+  return Object.entries(freq)
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, MAX_VOCAB_TERMS)
+    .map(([word]) => word);
+}
+
+// =============================================================================
+// Stash — chunk + index + store
+// =============================================================================
+
+export async function stashTheGoods(content, metadata = {}) {
+  if (!_pool) throw new Error('context vault not initialized — call initContextVault first');
+  await ensureTable();
+
+  // Reap expired stashes (piggyback on stash calls — no separate timer needed)
+  reapExpired().catch(() => {});
+
+  // vault_id from content hash — idempotent, same content = same ID = no dupes
+  const vaultId = createHash('sha256').update(content).digest('hex').slice(0, 12);
+
+  // Check if already stashed (idempotent dedup)
+  try {
+    const existing = await _pool.query(
+      'SELECT COUNT(*)::int as cnt FROM context_vault WHERE vault_id = $1',
+      [vaultId]
+    );
+    if (existing.rows[0]?.cnt > 0) {
+      const vocab = extractVocabulary(content);
+      return {
+        vaultId,
+        chunks: existing.rows[0].cnt,
+        totalChars: content.length,
+        preview: content.slice(0, PREVIEW_CHARS),
+        vocabulary: vocab,
+        deduplicated: true,
+      };
+    }
+  } catch (checkErr) {
+    // table might not exist yet — ensureTable should have handled it
+    logger.warn({ error: checkErr.message }, 'vault dedup check failed');
+  }
+
+  // Chunk the content
+  const chunks = chunkContent(content);
+  const vocab = extractVocabulary(content);
+
+  // Batch insert chunks
+  for (let i = 0; i < chunks.length; i++) {
+    try {
+      await _pool.query(
+        `INSERT INTO context_vault (vault_id, chunk_idx, content, source_tool, source_size, metadata, project_path, expires_at)
+         VALUES ($1, $2, $3, $4, $5, $6::jsonb, $7, NOW() + make_interval(hours => $8))
+         ON CONFLICT (vault_id, chunk_idx) DO NOTHING`,
+        [
+          vaultId,
+          i,
+          chunks[i],
+          metadata.tool || 'unknown',
+          content.length,
+          JSON.stringify(metadata),
+          _projectPath,
+          VAULT_TTL_HOURS,
+        ]
+      );
+    } catch (insertErr) {
+      logger.warn({ error: insertErr.message, chunk: i }, 'vault chunk insert failed');
+    }
+  }
+
+  logger.info({
+    vaultId,
+    chunks: chunks.length,
+    totalChars: content.length,
+    tool: metadata.tool,
+  }, `vault: stashed ${chunks.length} chunks (${content.length} chars)`);
+
+  return {
+    vaultId,
+    chunks: chunks.length,
+    totalChars: content.length,
+    preview: content.slice(0, PREVIEW_CHARS),
+    vocabulary: vocab,
+    deduplicated: false,
+  };
+}
+
+// =============================================================================
+// Search — BM25-ranked retrieval via tsvector
+// =============================================================================
+
+export async function digInTheVault(query, vaultId = null, limit = 10) {
+  if (!_pool) throw new Error('context vault not initialized');
+  await ensureTable();
+
+  let sql, params;
+
+  if (vaultId) {
+    // Search within a specific stash
+    sql = `
+      SELECT vault_id, chunk_idx, content,
+             ts_rank(content_tsv, plainto_tsquery('english', $1)) as rank
+      FROM context_vault
+      WHERE vault_id = $2
+        AND content_tsv @@ plainto_tsquery('english', $1)
+        AND expires_at > NOW()
+      ORDER BY rank DESC
+      LIMIT $3
+    `;
+    params = [query, vaultId, limit];
+  } else {
+    // Search across all stashes for this project
+    sql = `
+      SELECT vault_id, chunk_idx, content,
+             ts_rank(content_tsv, plainto_tsquery('english', $1)) as rank
+      FROM context_vault
+      WHERE content_tsv @@ plainto_tsquery('english', $1)
+        AND project_path = $2
+        AND expires_at > NOW()
+      ORDER BY rank DESC
+      LIMIT $3
+    `;
+    params = [query, _projectPath, limit];
+  }
+
+  const { rows } = await _pool.query(sql, params);
+
+  // If tsvector found nothing and we have a vault_id, fall back to ILIKE
+  if (rows.length === 0 && vaultId) {
+    const fallback = await _pool.query(
+      `SELECT vault_id, chunk_idx, content, 0.0::float as rank
+       FROM context_vault
+       WHERE vault_id = $1 AND content ILIKE '%' || $2 || '%' AND expires_at > NOW()
+       ORDER BY chunk_idx ASC LIMIT $3`,
+      [vaultId, query, limit]
+    );
+    return fallback.rows;
+  }
+
+  return rows;
+}
+
+// =============================================================================
+// Get full stash — all chunks ordered for complete retrieval
+// =============================================================================
+
+export async function getFullStash(vaultId) {
+  if (!_pool) throw new Error('context vault not initialized');
+  await ensureTable();
+
+  const { rows } = await _pool.query(
+    `SELECT chunk_idx, content FROM context_vault
+     WHERE vault_id = $1 AND expires_at > NOW()
+     ORDER BY chunk_idx ASC`,
+    [vaultId]
+  );
+
+  if (rows.length === 0) return null;
+  return rows.map(r => r.content).join('\n\n');
+}
+
+// =============================================================================
+// Stats — what's in the vault right now
+// =============================================================================
+
+export async function getVaultStats() {
+  if (!_pool) return { totalStashes: 0, totalChunks: 0, totalChars: 0 };
+  await ensureTable();
+
+  try {
+    const { rows } = await _pool.query(`
+      SELECT
+        COUNT(DISTINCT vault_id)::int as stash_count,
+        COUNT(*)::int as chunk_count,
+        COALESCE(SUM(LENGTH(content)), 0)::int as total_chars,
+        MIN(stashed_at) as oldest
+      FROM context_vault
+      WHERE project_path = $1 AND expires_at > NOW()
+    `, [_projectPath]);
+
+    return {
+      totalStashes: rows[0]?.stash_count || 0,
+      totalChunks: rows[0]?.chunk_count || 0,
+      totalChars: rows[0]?.total_chars || 0,
+      oldestStash: rows[0]?.oldest || null,
+    };
+  } catch (err) {
+    return { totalStashes: 0, totalChunks: 0, totalChars: 0, error: err.message };
+  }
+}
+
+// =============================================================================
+// Reaper — clean expired stashes (runs piggyback on stash operations)
+// =============================================================================
+
+async function reapExpired() {
+  if (!_pool) return;
+  try {
+    const result = await _pool.query('DELETE FROM context_vault WHERE expires_at < NOW()');
+    if (result.rowCount > 0) {
+      logger.info({ reaped: result.rowCount }, 'vault: reaped expired stashes');
+    }
+  } catch {
+    // non-fatal, swallow
+  }
+}
+
+// =============================================================================
+// Receipt formatter — compact reference that replaces the full output
+// =============================================================================
+
+export function formatVaultReceipt(stashResult) {
+  const { vaultId, chunks, totalChars, preview, vocabulary, deduplicated } = stashResult;
+  const receiptSize = PREVIEW_CHARS + 200 + (vocabulary.length * 8);
+  const savings = ((1 - (receiptSize / totalChars)) * 100).toFixed(1);
+
+  return [
+    `<vault_receipt id="${vaultId}" chunks="${chunks}" total_chars="${totalChars}" savings="${savings}%"${deduplicated ? ' dedup="true"' : ''}>`,
+    `Content stashed (${totalChars.toLocaleString()} chars chunked into ${chunks} searchable blocks)`,
+    ``,
+    `Preview:`,
+    preview + (totalChars > PREVIEW_CHARS ? '...' : ''),
+    ``,
+    `Key terms: ${vocabulary.join(', ')}`,
+    ``,
+    `Retrieve: dig_in_the_vault(query: "search terms", vault_id: "${vaultId}")`,
+    `Full dump: dig_in_the_vault(vault_id: "${vaultId}", get_all: true)`,
+    `</vault_receipt>`,
+  ].join('\n');
+}