@selvakumaresra/specship 0.4.0 → 0.6.0

package/dist/server/ingest/impact-query.js

@@ -0,0 +1,343 @@
+/**
+ * computeSpecshipImpact — aggregate SpecShip token-impact metrics from
+ * claude_tool_calls + claude_sessions.
+ *
+ * Pure function of (db, opts) — no Fastify dependency, unit-testable.
+ * Called by GET /api/claude/specship-impact in routes/claude.ts.
+ *
+ * Algorithm (SQL fetch + JS reduction — no GROUP BY prompt_id/file SQL):
+ *   1. Fetch scoped rows joining claude_tool_calls ↔ claude_sessions.
+ *   2. Spend: ceil(Σ result_length / CHARS_PER_TOKEN) for is_specship=1.
+ *   3. Saved: per-prompt dedup — union displaced file paths across a prompt's
+ *      resolved calls, sum each distinct file's size ONCE, subtract the
+ *      prompt's specship spend chars, floor at 0.
+ *   4. Overhead: ceil(SPECSHIP_TOOLDEF_CHARS / CHARS_PER_TOKEN) ×
+ *      distinct session count with ≥1 specship call.
+ *   5. Cost: price spend/saved chars at input-token rate, grouped by model.
+ */
+import { normalizeModelId, resolvePricing } from './pricing.js';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Characters treated as one token (rough average for Claude). */
+const CHARS_PER_TOKEN = 4;
+/**
+ * JSON.stringify length of the SpecShip MCP tool definitions array.
+ * Measured: JSON.stringify(tools.filter(t => t.name.startsWith('specship_'))).length
+ * at 2026-06-24 — 12 tools in the registry at that time.
+ * See src/mcp/tools.ts; recheck after adding/removing tools.
+ */
+const SPECSHIP_TOOLDEF_CHARS = 10047;
+/** Overhead tokens charged per session (tool-definition context cost). */
+const OVERHEAD_TOKENS_PER_SESSION = Math.ceil(SPECSHIP_TOOLDEF_CHARS / CHARS_PER_TOKEN);
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function parseDisplacedFiles(raw) {
+    if (!raw)
+        return [];
+    try {
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed))
+            return [];
+        return parsed;
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Load pricing rows from the DB (returns [] if the table is empty or absent).
+ */
+function loadPricing(db) {
+    try {
+        return db
+            .prepare('SELECT model, input_per_mtok, output_per_mtok, cache_creation_per_mtok, cache_read_per_mtok FROM claude_pricing')
+            .all();
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Price a char count (already summed) as input tokens at the input rate for
+ * the given model. Returns 0 when model is unknown or pricing is unavailable.
+ */
+function priceChars(chars, model, pricingRows) {
+    if (!model || pricingRows.length === 0)
+        return 0;
+    const pricing = resolvePricing(model, pricingRows);
+    if (!pricing)
+        return 0;
+    const tokens = chars / CHARS_PER_TOKEN;
+    return (tokens * pricing.input_per_mtok) / 1_000_000;
+}
+/**
+ * Per-prompt dedup logic. Given the rows for ONE prompt:
+ *   - union displaced file paths from resolved rows (same file counted once)
+ *   - promptSavedChars = max(0, unionSize - promptSpendChars)
+ *
+ * Returns { savedChars, spendChars }.
+ */
+function computePromptSaved(rows) {
+    const spendChars = rows
+        .filter(r => r.is_specship === 1)
+        .reduce((s, r) => s + (r.result_length ?? 0), 0);
+    // Union displaced files across ALL resolved calls in this prompt.
+    const fileMap = new Map(); // path → size
+    for (const row of rows) {
+        if (row.is_specship !== 1 || row.resolution !== 'resolved')
+            continue;
+        for (const [path, size] of parseDisplacedFiles(row.displaced_files)) {
+            if (!fileMap.has(path)) {
+                fileMap.set(path, size);
+            }
+        }
+    }
+    const readEquivChars = Array.from(fileMap.values()).reduce((s, n) => s + n, 0);
+    const savedChars = Math.max(0, readEquivChars - spendChars);
+    return { savedChars, spendChars };
+}
+// ---------------------------------------------------------------------------
+// Main export
+// ---------------------------------------------------------------------------
+export function computeSpecshipImpact(db, opts) {
+    const { since, project, sessionId } = opts;
+    // 1. Fetch scoped rows.
+    const queryParts = [
+        `SELECT tc.prompt_id, tc.tool_name, tc.is_specship, tc.result_length,
+            tc.displaced_files, tc.resolution, tc.ts,
+            s.project_path, s.last_model
+     FROM claude_tool_calls tc
+     JOIN claude_sessions s ON s.id = tc.session_id
+     WHERE tc.ts >= ?`,
+    ];
+    const params = [since];
+    if (project) {
+        queryParts.push('AND s.project_path = ?');
+        params.push(project);
+    }
+    if (sessionId) {
+        queryParts.push('AND tc.session_id = ?');
+        params.push(sessionId);
+    }
+    const rows = db.prepare(queryParts.join(' ')).all(...params);
+    if (rows.length === 0) {
+        return {
+            spendTokens: 0,
+            spendCostUsd: 0,
+            savedTokens: 0,
+            savedCostUsd: 0,
+            overheadTokens: 0,
+            netTokens: 0,
+            netCostUsd: 0,
+            unresolvedCalls: 0,
+            totalSpecshipCalls: 0,
+            byTool: [],
+            byProject: [],
+            trend: [],
+        };
+    }
+    const pricingRows = loadPricing(db);
+    // ---------------------------------------------------------------------------
+    // 2. Group rows by prompt_id for per-prompt dedup.
+    // ---------------------------------------------------------------------------
+    const byPrompt = new Map();
+    for (const row of rows) {
+        const key = row.prompt_id ?? `__no_prompt_${row.ts}`;
+        const arr = byPrompt.get(key);
+        if (arr)
+            arr.push(row);
+        else
+            byPrompt.set(key, [row]);
+    }
+    // ---------------------------------------------------------------------------
+    // 3. Global spend / saved (with per-prompt dedup) + cost by model.
+    // ---------------------------------------------------------------------------
+    let totalSpendChars = 0;
+    let totalSavedChars = 0;
+    let totalSpecshipCalls = 0;
+    let unresolvedCalls = 0;
+    // For cost we need to track chars by model.
+    const spendCharsByModel = new Map();
+    const savedCharsByModel = new Map();
+    // Per-tool accumulators: spend is exact; saved is a per-tool APPROXIMATION.
+    // Exact per-tool saved attribution is ambiguous when two tools in the same
+    // prompt share a file. We approximate: a tool's saved chars = its own
+    // resolved displaced files (deduped within the tool, not globally within
+    // the prompt). This overestimates when tools share files but keeps
+    // individual tool savings intuitive. Spend is always exact.
+    const toolSpendChars = new Map();
+    const toolSavedChars = new Map();
+    const toolCalls = new Map();
+    // Per-project (only when no project filter).
+    const projectSpendChars = new Map();
+    const projectSavedChars = new Map();
+    // Trend: daily buckets.
+    const dayMs = 24 * 60 * 60 * 1000;
+    const trendSpend = new Map(); // dayBucket → chars
+    const trendSaved = new Map();
+    // Pass 1: global spend/saved via per-prompt dedup.
+    for (const [, promptRows] of byPrompt) {
+        const { savedChars, spendChars } = computePromptSaved(promptRows);
+        totalSpendChars += spendChars;
+        totalSavedChars += savedChars;
+        // Attribute spend/saved chars to the session's model.
+        // All rows in a prompt share the same session (same last_model).
+        const model = promptRows[0]?.last_model ?? null;
+        const normModel = model ? normalizeModelId(model) : null;
+        if (normModel) {
+            spendCharsByModel.set(normModel, (spendCharsByModel.get(normModel) ?? 0) + spendChars);
+            savedCharsByModel.set(normModel, (savedCharsByModel.get(normModel) ?? 0) + savedChars);
+        }
+        // Track per-day trend for this prompt's is_specship rows.
+        for (const row of promptRows) {
+            if (row.is_specship !== 1)
+                continue;
+            totalSpecshipCalls++;
+            if (row.resolution === 'unresolved')
+                unresolvedCalls++;
+            // Session tracking (for overhead).
+            // We need the session_id — it's not in our fetch. Derive from project+model
+            // won't work. We'll collect it via a separate map after this loop using rows.
+        }
+    }
+    // We need session_ids for overhead. Since we joined sessions but didn't select
+    // session_id, do a lightweight distinct-session count via a separate query.
+    const sessionCountQParts = [
+        `SELECT COUNT(DISTINCT tc.session_id) as cnt
+     FROM claude_tool_calls tc
+     JOIN claude_sessions s ON s.id = tc.session_id
+     WHERE tc.ts >= ? AND tc.is_specship = 1`,
+    ];
+    const sessionCountParams = [since];
+    if (project) {
+        sessionCountQParts.push('AND s.project_path = ?');
+        sessionCountParams.push(project);
+    }
+    if (sessionId) {
+        sessionCountQParts.push('AND tc.session_id = ?');
+        sessionCountParams.push(sessionId);
+    }
+    const sessionCountRow = db
+        .prepare(sessionCountQParts.join(' '))
+        .get(...sessionCountParams);
+    const specshipSessionCount = sessionCountRow?.cnt ?? 0;
+    // ---------------------------------------------------------------------------
+    // Pass 2: per-tool and trend (row-level, NOT requiring per-prompt dedup).
+    // ---------------------------------------------------------------------------
+    // Per-tool saved approximation: for each is_specship row with resolution=resolved,
+    // compute its own per-call "saved" as max(0, sum(displaced_file_sizes) - result_length).
+    // This is approximate because it ignores cross-call file sharing within a prompt,
+    // but it gives an intuitive per-tool estimate and spend is always exact.
+    for (const row of rows) {
+        const dayBucket = Math.floor(row.ts / dayMs) * dayMs;
+        if (row.is_specship !== 1)
+            continue;
+        const toolName = row.tool_name ?? 'unknown';
+        toolCalls.set(toolName, (toolCalls.get(toolName) ?? 0) + 1);
+        const spend = row.result_length ?? 0;
+        toolSpendChars.set(toolName, (toolSpendChars.get(toolName) ?? 0) + spend);
+        // Per-tool saved approximation: own displaced files minus own spend, ≥0.
+        const displaced = parseDisplacedFiles(row.displaced_files);
+        if (row.resolution === 'resolved' && displaced.length > 0) {
+            const fileUnion = new Map();
+            for (const [p, sz] of displaced)
+                if (!fileUnion.has(p))
+                    fileUnion.set(p, sz);
+            const readEquiv = Array.from(fileUnion.values()).reduce((s, n) => s + n, 0);
+            const toolSaved = Math.max(0, readEquiv - spend);
+            toolSavedChars.set(toolName, (toolSavedChars.get(toolName) ?? 0) + toolSaved);
+        }
+        // Trend.
+        trendSpend.set(dayBucket, (trendSpend.get(dayBucket) ?? 0) + spend);
+    }
+    // Per-prompt saved for trend and byProject (both need per-prompt dedup).
+    for (const [, promptRows] of byPrompt) {
+        const { savedChars } = computePromptSaved(promptRows);
+        const project_path = promptRows[0]?.project_path ?? '';
+        const dayBucket = Math.floor((promptRows[0]?.ts ?? 0) / dayMs) * dayMs;
+        // Trend saved.
+        if (savedChars > 0) {
+            trendSaved.set(dayBucket, (trendSaved.get(dayBucket) ?? 0) + savedChars);
+        }
+        // byProject accumulators.
+        if (!project) {
+            const spendChars = promptRows
+                .filter(r => r.is_specship === 1)
+                .reduce((s, r) => s + (r.result_length ?? 0), 0);
+            projectSpendChars.set(project_path, (projectSpendChars.get(project_path) ?? 0) + spendChars);
+            projectSavedChars.set(project_path, (projectSavedChars.get(project_path) ?? 0) + savedChars);
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // 4. Compute tokens + cost.
+    // ---------------------------------------------------------------------------
+    const spendTokens = Math.ceil(totalSpendChars / CHARS_PER_TOKEN);
+    const savedTokens = Math.ceil(totalSavedChars / CHARS_PER_TOKEN);
+    const overheadTokens = OVERHEAD_TOKENS_PER_SESSION * specshipSessionCount;
+    let spendCostUsd = 0;
+    let savedCostUsd = 0;
+    for (const [model, chars] of spendCharsByModel) {
+        spendCostUsd += priceChars(chars, model, pricingRows);
+    }
+    for (const [model, chars] of savedCharsByModel) {
+        savedCostUsd += priceChars(chars, model, pricingRows);
+    }
+    const netTokens = savedTokens - spendTokens - overheadTokens;
+    const netCostUsd = savedCostUsd - spendCostUsd;
+    // ---------------------------------------------------------------------------
+    // 5. byTool.
+    // ---------------------------------------------------------------------------
+    const byTool = Array.from(toolCalls.entries()).map(([tool, calls]) => ({
+        tool,
+        calls,
+        spendTokens: Math.ceil((toolSpendChars.get(tool) ?? 0) / CHARS_PER_TOKEN),
+        savedTokens: Math.ceil((toolSavedChars.get(tool) ?? 0) / CHARS_PER_TOKEN),
+    })).sort((a, b) => b.calls - a.calls);
+    // ---------------------------------------------------------------------------
+    // 6. byProject (only when no project filter).
+    // ---------------------------------------------------------------------------
+    // NOTE: per-project netTokens = saved − spend and intentionally does NOT
+    // subtract the tool-definition overhead. Overhead is a per-session constant
+    // and isn't attributed to individual projects, so the byProject rows will
+    // not sum to the headline netTokens (which does include overhead). The page
+    // methodology note discloses this.
+    const byProject = project
+        ? []
+        : Array.from(projectSpendChars.keys()).map((proj) => {
+            const spend = Math.ceil((projectSpendChars.get(proj) ?? 0) / CHARS_PER_TOKEN);
+            const saved = Math.ceil((projectSavedChars.get(proj) ?? 0) / CHARS_PER_TOKEN);
+            return {
+                project: proj,
+                spendTokens: spend,
+                savedTokens: saved,
+                netTokens: saved - spend, // overhead not allocated per-project — see note above
+            };
+        }).sort((a, b) => b.spendTokens - a.spendTokens);
+    // ---------------------------------------------------------------------------
+    // 7. trend.
+    // ---------------------------------------------------------------------------
+    const allDayBuckets = new Set([...trendSpend.keys(), ...trendSaved.keys()]);
+    const trend = Array.from(allDayBuckets)
+        .sort((a, b) => a - b)
+        .map((ts) => ({
+        ts,
+        spendTokens: Math.ceil((trendSpend.get(ts) ?? 0) / CHARS_PER_TOKEN),
+        savedTokens: Math.ceil((trendSaved.get(ts) ?? 0) / CHARS_PER_TOKEN),
+    }));
+    return {
+        spendTokens,
+        spendCostUsd,
+        savedTokens,
+        savedCostUsd,
+        overheadTokens,
+        netTokens,
+        netCostUsd,
+        unresolvedCalls,
+        totalSpecshipCalls,
+        byTool,
+        byProject,
+        trend,
+    };
+}

package/dist/server/ingest/index.js

@@ -12,7 +12,8 @@
  *   - `ingestAll(db)`     — one-shot pass, useful for CI / scripts.
  *   - `startWatcher(db)`  — live tail; runs ingestAll once + on each FS event.
  */
-export { ingestAll, listTranscriptFiles, decodeProjectSlug } from './ingestor.js';
+export { ingestAll, listTranscriptFiles, decodeProjectSlug, primaryProjectMatcher } from './ingestor.js';
 export { startWatcher } from './watcher.js';
 export { resolvePricing, computeCost, normalizeModelId } from './pricing.js';
 export { parseLine, summarizeToolInput, extractUserPrompt, toolResultLength } from './parser.js';
+export { backfillDisplaced } from './impact-backfill.js';

package/dist/server/ingest/ingestor.js

@@ -27,6 +27,7 @@ import * as os from 'os';
 import * as path from 'path';
 import { computeCost, resolvePricing } from './pricing.js';
 import { parseLine, toEpochMs, extractUserPrompt, summarizeToolInput, toolResultLength, } from './parser.js';
+import { classifyToolCall } from './specship-classify.js';
 /**
  * Convert Claude's slash-escaped project dir name back into a real path.
  * `~/.claude/projects/-Users-alice-projects-foo` → `/Users/alice/projects/foo`
@@ -34,6 +35,24 @@ import { parseLine, toEpochMs, extractUserPrompt, summarizeToolInput, toolResult
 export function decodeProjectSlug(slug) {
     return slug.startsWith('-') ? '/' + slug.slice(1).replace(/-/g, '/') : slug;
 }
+/**
+ * Build a predicate that tells whether a stored `project_path` belongs to the
+ * primary project, given the primary's REAL filesystem path.
+ *
+ * Why this isn't a plain `===`: `decodeProjectSlug` lossily turns every '-' in
+ * the slug into '/', so a real path like `/Users/a/dev/claude-projects/x` gets
+ * STORED as `/Users/a/dev/claude/projects/x`. The savings graph resolver only
+ * has the real primary path, so it never matched the mangled stored form and
+ * every call resolved to a null graph (savedTokens stuck at 0). We match BOTH
+ * the real path and its mangled form (computed by round-tripping the real path
+ * through the same encode→decode the storage used). No stored data is changed,
+ * so the (consistently-mangled) project filter is unaffected.
+ */
+export function primaryProjectMatcher(primaryRealPath) {
+    // encode: real path → slug form (every '/' → '-'); decode: slug → mangled path.
+    const mangled = decodeProjectSlug(primaryRealPath.replace(/\//g, '-'));
+    return (storedPath) => storedPath === primaryRealPath || storedPath === mangled;
+}
 /**
  * List every JSONL file inside `<claudeRoot>/<slug>/<sessionId>.jsonl`.
  * Returns the absolute file path + the decoded project path.
@@ -222,9 +241,22 @@ function ingestFile(db, filePath, projectPath, pricing, options) {
     VALUES (?, ?, ?, ?)
     ON CONFLICT(path) DO UPDATE SET last_seen = excluded.last_seen
   `).run(projectPath, projectName, now, now);
+    // Resolve the graph once per file (per project path) — avoids reopening the DB
+    // on every tool call. Returns null when no resolver is configured. The
+    // resolver can throw on a locked/corrupt index; that estimate is best-effort
+    // decoration and must NEVER abort transcript ingest, so degrade to null.
+    let graph = null;
+    if (options.resolveGraph) {
+        try {
+            graph = options.resolveGraph(projectPath);
+        }
+        catch {
+            graph = null;
+        }
+    }
     // Per-file ingest in a transaction.
     const txn = db.transaction(() => {
-        return processLines(db, filePath, projectPath, completeLines, pricing);
+        return processLines(db, filePath, projectPath, completeLines, pricing, graph);
     });
     const result = txn();
     // Persist new offset.
@@ -255,7 +287,7 @@ function ingestFile(db, filePath, projectPath, pricing, options) {
  * the next user entry) so result_length is captured. Maintain a map of
  * pending tool_use_id → { promptId, name, summary, ts } as we walk.
  */
-function processLines(db, filePath, projectPath, completeLines, pricing) {
+function processLines(db, filePath, projectPath, completeLines, pricing, graph) {
     const insSession = db.prepare(`
     INSERT INTO claude_sessions (id, project_path, source_file, started_at, ended_at, prompt_count, last_model)
     VALUES (?, ?, ?, ?, ?, 0, ?)
@@ -286,8 +318,8 @@ function processLines(db, filePath, projectPath, completeLines, pricing) {
       cost_usd = excluded.cost_usd
   `);
     const insToolCall = db.prepare(`
-    INSERT INTO claude_tool_calls (prompt_id, session_id, assistant_uuid, tool_use_id, tool_name, input_summary, input_json, result_length, ts)
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+    INSERT INTO claude_tool_calls (prompt_id, session_id, assistant_uuid, tool_use_id, tool_name, input_summary, input_json, result_length, ts, is_specship, displaced_files, resolution)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
   `);
     /**
      * Append the assistant's text + thinking blocks from one assistant turn
@@ -387,7 +419,8 @@ function processLines(db, filePath, projectPath, completeLines, pricing) {
                         const len = toolResultLength(block);
                         const pending = pendingTools.get(block.tool_use_id);
                         if (pending) {
-                            insToolCall.run(pending.promptId, pending.sessionId, pending.assistantUuid, block.tool_use_id, pending.toolName, pending.summary, pending.inputJson, len, pending.ts);
+                            const cls = classifyToolCall({ toolName: pending.toolName, inputJson: pending.inputJson, resultLength: len }, graph);
+                            insToolCall.run(pending.promptId, pending.sessionId, pending.assistantUuid, block.tool_use_id, pending.toolName, pending.summary, pending.inputJson, len, pending.ts, cls.isSpecship, cls.displacedFiles, cls.resolution);
                             toolCallsInserted++;
                             pendingTools.delete(block.tool_use_id);
                         }
@@ -492,7 +525,9 @@ function processLines(db, filePath, projectPath, completeLines, pricing) {
     // result_length=0 so the tool call still shows up in analytics (better to
     // show "0 tokens returned" than to omit the call).
     for (const [toolUseId, pending] of pendingTools) {
-        insToolCall.run(pending.promptId, pending.sessionId, pending.assistantUuid, toolUseId, pending.toolName, pending.summary, pending.inputJson, 0, pending.ts);
+        // result_length=0 for pending/unmatched tools → classifyToolCall returns 'n/a' for specship.
+        const cls = classifyToolCall({ toolName: pending.toolName, inputJson: pending.inputJson, resultLength: 0 }, graph);
+        insToolCall.run(pending.promptId, pending.sessionId, pending.assistantUuid, toolUseId, pending.toolName, pending.summary, pending.inputJson, 0, pending.ts, cls.isSpecship, cls.displacedFiles, cls.resolution);
         toolCallsInserted++;
     }
     return {

package/dist/server/ingest/specship-classify.js

@@ -0,0 +1,153 @@
+/**
+ * Pure classifiers and symbol-extraction helpers for SpecShip Token Impact.
+ *
+ * SERVER-LOCAL COPY. The lib has the canonical version at
+ * `src/analytics/specship-impact.ts`; this file is duplicated here on purpose
+ * so the server never carries a runtime `import … from '@selvakumaresra/specship'`
+ * — a bare-package value import does NOT resolve in bundled / different-cwd
+ * mode and silently drops the server back to a stale build (the same failure
+ * mode `server.ts`/`workflow.ts` already guard against). These functions are
+ * pure (no I/O, no deps), so duplication is cheap; `__tests__/specship-impact-parity.test.ts`
+ * asserts the two copies stay behaviourally identical.
+ */
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Prefix shared by every MCP tool routed through the specship server. */
+const MCP_SPECSHIP_PREFIX = 'mcp__specship__';
+/**
+ * Strip-prefix base names of SpecShip tools that return code-graph source.
+ * These are the tools a SpecShip call can displace a native Read/Grep with.
+ * Excluded: designer_*, specship_link_assert, specship_link_verify,
+ * specship_spec, specship_drifted, specship_status — they don't return
+ * indexed source symbols.
+ */
+const SOURCE_RETURNING_TOOLS = new Set([
+    'specship_explore',
+    'specship_node',
+    'specship_callers',
+    'specship_callees',
+    'specship_impact',
+    'specship_search',
+    'specship_files',
+]);
+/**
+ * Tools whose input carries a `symbol` key (single identifier string).
+ * Verified against src/mcp/tools.ts inputSchema `required: ['symbol']`.
+ */
+const SYMBOL_KEY_TOOLS = new Set([
+    'specship_node',
+    'specship_callers',
+    'specship_callees',
+    'specship_impact',
+]);
+/**
+ * Regex for a single valid identifier token (with optional Class.method
+ * qualifier).
+ */
+const SYMBOL_TOKEN_RE = /^[A-Za-z_$][\w$]*(\.[A-Za-z_$][\w$]*)?$/;
+/**
+ * Regex a token must match to be considered "code-ish" rather than prose.
+ * Real symbol names almost always contain an uppercase letter, underscore,
+ * dollar sign, digit, or a dot; pure lowercase words look like prose.
+ */
+const CODE_SIGNAL_RE = /[A-Z_$\d.]/;
+/** Cap on how many symbol-shaped tokens we pull from one query. */
+const MAX_SYMBOLS_PER_QUERY = 16;
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/** True iff `name` is routed through the SpecShip MCP server. */
+export function isSpecshipTool(name) {
+    return name.startsWith(MCP_SPECSHIP_PREFIX);
+}
+/** True iff the tool returns code-graph source that can displace a Read/Grep. */
+export function isSourceReturningTool(name) {
+    if (!name.startsWith(MCP_SPECSHIP_PREFIX))
+        return false;
+    const base = name.slice(MCP_SPECSHIP_PREFIX.length);
+    return SOURCE_RETURNING_TOOLS.has(base);
+}
+/**
+ * Extracts the symbol names a tool call asked about from its serialised input
+ * JSON. Returns `[]` when no symbols are resolvable (bad JSON, prose query,
+ * non-symbol tool).
+ */
+export function extractRequestedSymbols(toolName, inputJson) {
+    if (!inputJson)
+        return [];
+    let parsed;
+    try {
+        parsed = JSON.parse(inputJson);
+    }
+    catch {
+        return [];
+    }
+    if (parsed === null || typeof parsed !== 'object')
+        return [];
+    const args = parsed;
+    if (!toolName.startsWith(MCP_SPECSHIP_PREFIX))
+        return [];
+    const base = toolName.slice(MCP_SPECSHIP_PREFIX.length);
+    if (SYMBOL_KEY_TOOLS.has(base)) {
+        const sym = args['symbol'];
+        return typeof sym === 'string' && sym.length > 0 ? [sym] : [];
+    }
+    if (base === 'specship_explore' || base === 'specship_search') {
+        const q = args['query'];
+        if (typeof q !== 'string' || q.length === 0)
+            return [];
+        return symbolBagFromQuery(q);
+    }
+    return [];
+}
+/**
+ * Classify one tool call → the three ingest columns
+ * (`isSpecship`, `resolution`, `displacedFiles`). A graph-estimate failure
+ * degrades to 'unresolved' (it must NEVER break core transcript ingest).
+ */
+export function classifyToolCall(call, graph) {
+    const { toolName, inputJson, resultLength } = call;
+    if (!isSpecshipTool(toolName)) {
+        return { isSpecship: 0, resolution: null, displacedFiles: null };
+    }
+    if (isSourceReturningTool(toolName) && resultLength > 0) {
+        const symbols = extractRequestedSymbols(toolName, inputJson);
+        if (symbols.length === 0) {
+            return { isSpecship: 1, resolution: 'unresolved', displacedFiles: null };
+        }
+        if (graph === null) {
+            return { isSpecship: 1, resolution: 'unresolved', displacedFiles: null };
+        }
+        let files;
+        let resolved;
+        try {
+            ({ files, resolved } = graph.estimateReadEquivalent(symbols));
+        }
+        catch {
+            return { isSpecship: 1, resolution: 'unresolved', displacedFiles: null };
+        }
+        if (resolved) {
+            return {
+                isSpecship: 1,
+                resolution: 'resolved',
+                displacedFiles: JSON.stringify(files.map((f) => [f.path, f.size])),
+            };
+        }
+        return { isSpecship: 1, resolution: 'unresolved', displacedFiles: null };
+    }
+    return { isSpecship: 1, resolution: 'n/a', displacedFiles: null };
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+// Real explore/search queries are MIXED bags (symbol names + lowercase
+// keywords, often 10+ tokens). FILTER the symbol-shaped tokens out rather than
+// rejecting the whole query; pure prose yields []. Capped to bound graph work.
+function symbolBagFromQuery(query) {
+    const symbols = query
+        .trim()
+        .split(/\s+/)
+        .filter((t) => SYMBOL_TOKEN_RE.test(t) && CODE_SIGNAL_RE.test(t));
+    return symbols.slice(0, MAX_SYMBOLS_PER_QUERY);
+}

package/dist/server/routes/claude.js

@@ -13,9 +13,11 @@
  *   GET /api/claude/costs?range=             — cost rollup, timeseries, per-model
  *   GET /api/claude/compare                  — per-project cost comparison
  *   GET /api/claude/tips                     — rule-based tips engine output
+ *   GET /api/claude/specship-impact?range=&project= — SpecShip token-impact aggregation
  *   POST /api/claude/ingest                  — force a one-shot ingest pass
  */
 import { decodeProjectSlug } from '../ingest/index.js';
+import { computeSpecshipImpact } from '../ingest/impact-query.js';
 /**
  * Normalize a `?project=` filter value to the form stored in
  * claude_sessions.project_path. The Sessions page (and any other UI
@@ -346,6 +348,13 @@ export async function registerClaudeRoutes(app) {
         const durationMs = session.started_at && session.ended_at
             ? Math.max(0, session.ended_at - session.started_at)
             : 0;
+        // SpecShip token-impact rollup for this session.
+        const impact = computeSpecshipImpact(db, { since: 0, sessionId });
+        const specship = {
+            spendTokens: impact.spendTokens,
+            savedTokens: impact.savedTokens,
+            netTokens: impact.netTokens,
+        };
         return {
             sessionId,
             byTool,
@@ -354,6 +363,7 @@ export async function registerClaudeRoutes(app) {
             skills,
             filesTouched,
             durationMs,
+            specship,
         };
     });
     app.get('/api/claude/heatmap', async (req, reply) => {
@@ -855,6 +865,28 @@ export async function registerClaudeRoutes(app) {
         tips.sort((a, b) => (order[a.severity] ?? 9) - (order[b.severity] ?? 9));
         return { tips };
     });
+    /**
+     * GET /api/claude/specship-impact?range=&project=
+     *
+     * Aggregate SpecShip token-impact metrics: how many tokens specship calls
+     * spent vs. how many tokens' worth of Read calls they displaced (saved),
+     * with per-prompt dedup so a file referenced by two specship calls in the
+     * same prompt counts only once. See packages/server/src/ingest/impact-query.ts
+     * for the full algorithm.
+     *
+     * Query params:
+     *   range   — 'today' | 'week' (default) | 'month' | 'all'
+     *   project — project slug (decoded to path) or raw path; omit for all projects
+     */
+    app.get('/api/claude/specship-impact', async (req, reply) => {
+        const cg = requirePrimary(reply);
+        if (!cg)
+            return;
+        const db = getDb(cg);
+        const since = rangeStart(rangeKey(req.query.range));
+        const project = req.query.project ? normalizeProjectFilter(req.query.project) : undefined;
+        return computeSpecshipImpact(db, { since, project });
+    });
     /**
      * Force a one-shot ingest pass. Useful for "Refresh" button in the UI.
      */