@unerr-ai/unerr 0.1.0 → 0.1.2

package/dist/timeline/intent-detector.js

@@ -0,0 +1,263 @@
+/**
+ * Intent Detector (ST-4) — cross-session task stitching.
+ *
+ * Walks closed turns + recorded session_files + markers in timeline.db and
+ * groups sessions into `intents`. A session attaches to an intent if EITHER:
+ *
+ *   a) it emitted a `mark_intent` whose text matches an existing intent's
+ *      title (anchored stitch, source="agent_marker"); OR
+ *   b) its file set has Jaccard overlap > 0.4 with an intent's file_set AND
+ *      the intent was last active within the freshness window (default 14 d).
+ *
+ * Otherwise a new intent is created with source="file_jaccard". After each
+ * run, intents inactive for > 21 d move to "dormant".
+ *
+ * Pure functions are exported for testing; the orchestrator `runIntentStitch`
+ * does the I/O against CozoTimelineStore.
+ */
+import { randomUUID } from "node:crypto";
+const DEFAULT_JACCARD = 0.4;
+const DEFAULT_FRESHNESS_MS = 14 * 24 * 60 * 60_000;
+const DEFAULT_DORMANT_MS = 21 * 24 * 60 * 60_000;
+export function jaccard(a, b) {
+    if (a.size === 0 && b.size === 0)
+        return 0;
+    let intersection = 0;
+    const [small, big] = a.size <= b.size ? [a, b] : [b, a];
+    for (const v of small)
+        if (big.has(v))
+            intersection += 1;
+    const union = a.size + b.size - intersection;
+    return union === 0 ? 0 : intersection / union;
+}
+export function hashFileSet(files) {
+    const sorted = [...new Set(files)].sort();
+    // Tiny deterministic hash — enough to dedupe identical file sets without
+    // hauling in a crypto dep. Stable across processes since it's data-only.
+    let h = 0;
+    for (const f of sorted) {
+        for (let i = 0; i < f.length; i++) {
+            h = (h * 31 + f.charCodeAt(i)) | 0;
+        }
+        h = (h * 31 + 0x5f) | 0;
+    }
+    return `${sorted.length}-${(h >>> 0).toString(36)}`;
+}
+/**
+ * Pure stitch — given session summaries + existing intents (with their session
+ * lists), return updated intents + new attachments. Does NOT call the DB.
+ */
+export function stitchIntents(sessions, existingIntents, existingAttachments, opts = {}) {
+    const jaccardThreshold = opts.jaccardThreshold ?? DEFAULT_JACCARD;
+    const freshnessMs = opts.freshnessMs ?? DEFAULT_FRESHNESS_MS;
+    const dormantAfterMs = opts.dormantAfterMs ?? DEFAULT_DORMANT_MS;
+    const now = opts.nowMs ?? Date.now();
+    const attachedSessions = new Set(existingAttachments.map((a) => a.session_id));
+    const titleIndex = new Map();
+    for (const i of existingIntents) {
+        if (i.title.length > 0)
+            titleIndex.set(i.title.toLowerCase(), i);
+    }
+    // Working copy of intents; we mutate file_set + last_active_at.
+    const intents = new Map();
+    for (const i of existingIntents) {
+        let files = [];
+        try {
+            const parsed = JSON.parse(i.file_set || "[]");
+            if (Array.isArray(parsed))
+                files = parsed.map((x) => String(x));
+        }
+        catch {
+            files = [];
+        }
+        intents.set(i.intent_id, { ...i, _filesSet: new Set(files) });
+    }
+    const newAttachments = [];
+    // Stitch each session, oldest-first so deterministic merge order.
+    const ordered = [...sessions].sort((a, b) => a.started_at - b.started_at);
+    for (const s of ordered) {
+        if (attachedSessions.has(s.session_id))
+            continue;
+        // 1) marker anchor
+        if (s.intent_text && s.intent_text.length > 0) {
+            const existing = titleIndex.get(s.intent_text.toLowerCase());
+            if (existing) {
+                attachSession(intents.get(existing.intent_id), s);
+                newAttachments.push({
+                    intent_id: existing.intent_id,
+                    session_id: s.session_id,
+                });
+                attachedSessions.add(s.session_id);
+                continue;
+            }
+            const created = createIntent(s, s.intent_text, "agent_marker");
+            intents.set(created.intent_id, created);
+            titleIndex.set(s.intent_text.toLowerCase(), created);
+            newAttachments.push({
+                intent_id: created.intent_id,
+                session_id: s.session_id,
+            });
+            attachedSessions.add(s.session_id);
+            continue;
+        }
+        // 2) Jaccard
+        let best = null;
+        for (const i of intents.values()) {
+            if (s.started_at - i.last_active_at > freshnessMs)
+                continue;
+            const score = jaccard(s.files, i._filesSet);
+            if (score >= jaccardThreshold && (best === null || score > best.score)) {
+                best = { intent: i, score };
+            }
+        }
+        if (best) {
+            attachSession(best.intent, s);
+            newAttachments.push({
+                intent_id: best.intent.intent_id,
+                session_id: s.session_id,
+            });
+            attachedSessions.add(s.session_id);
+            continue;
+        }
+        // 3) Create fresh
+        const created = createIntent(s, deriveTitle(s.files), "file_jaccard");
+        intents.set(created.intent_id, created);
+        if (created.title.length > 0)
+            titleIndex.set(created.title.toLowerCase(), created);
+        newAttachments.push({
+            intent_id: created.intent_id,
+            session_id: s.session_id,
+        });
+        attachedSessions.add(s.session_id);
+    }
+    // Pass — dormant transitions
+    const dormantTransitions = [];
+    for (const i of intents.values()) {
+        if (i.status === "active" && now - i.last_active_at > dormantAfterMs) {
+            i.status = "dormant";
+            dormantTransitions.push(i.intent_id);
+        }
+    }
+    return {
+        intents: [...intents.values()].map((i) => stripWorkingFields(i)),
+        attachments: newAttachments,
+        dormantTransitions,
+    };
+}
+function attachSession(intent, session) {
+    for (const f of session.files)
+        intent._filesSet.add(f);
+    intent.last_active_at = Math.max(intent.last_active_at, session.last_active_at);
+    intent.confidence = Math.min(1, intent.confidence + 0.05);
+    intent.file_set = JSON.stringify([...intent._filesSet].sort());
+    intent.file_set_hash = hashFileSet(intent._filesSet);
+}
+function createIntent(session, title, source) {
+    const filesSorted = [...session.files].sort();
+    return {
+        intent_id: randomUUID(),
+        title,
+        started_at: session.started_at,
+        last_active_at: session.last_active_at,
+        file_set: JSON.stringify(filesSorted),
+        file_set_hash: hashFileSet(filesSorted),
+        status: "active",
+        confidence: source === "agent_marker" ? 0.8 : 0.5,
+        source,
+        _filesSet: new Set(session.files),
+    };
+}
+function stripWorkingFields(i) {
+    const { _filesSet, ...row } = i;
+    void _filesSet;
+    return row;
+}
+function deriveTitle(files) {
+    if (files.size === 0)
+        return "Misc";
+    // Pick the most common directory prefix as a title hint.
+    const dirCounts = new Map();
+    for (const f of files) {
+        const dir = f.split("/").slice(0, -1).join("/") || "/";
+        dirCounts.set(dir, (dirCounts.get(dir) ?? 0) + 1);
+    }
+    let bestDir = "";
+    let bestCount = -1;
+    for (const [d, c] of dirCounts) {
+        if (c > bestCount) {
+            bestDir = d;
+            bestCount = c;
+        }
+    }
+    return bestDir ? `Work in ${bestDir}` : "Misc";
+}
+/**
+ * Build session summaries from turns + markers fetched from the store.
+ */
+export function buildSessionSummaries(turns, markers, filesBySession) {
+    const intentBySession = new Map();
+    for (const m of markers) {
+        if (m.type === "mark_intent" && !intentBySession.has(m.session_id)) {
+            intentBySession.set(m.session_id, m.text);
+        }
+    }
+    const byId = new Map();
+    for (const t of turns) {
+        let s = byId.get(t.session_id);
+        if (!s) {
+            s = {
+                session_id: t.session_id,
+                started_at: t.started_at,
+                last_active_at: t.ended_at,
+                files: filesBySession.get(t.session_id) ?? new Set(),
+                intent_text: intentBySession.get(t.session_id),
+            };
+            byId.set(t.session_id, s);
+        }
+        else {
+            s.started_at = Math.min(s.started_at, t.started_at);
+            s.last_active_at = Math.max(s.last_active_at, t.ended_at);
+        }
+    }
+    return [...byId.values()];
+}
+/**
+ * IO orchestrator — fetches state from the store, runs stitchIntents, writes
+ * back. Safe to call repeatedly (idempotent: previously-attached sessions are
+ * skipped).
+ */
+export async function runIntentStitch(store, opts = {}) {
+    const turns = await store.listTurns({ limit: 500 });
+    const markers = await store.listMarkers({ limit: 1000 });
+    const sessionIds = new Set(turns.map((t) => t.session_id));
+    const filesBySession = new Map();
+    for (const sid of sessionIds) {
+        const files = await store.getSessionFiles(sid);
+        filesBySession.set(sid, new Set(files));
+    }
+    const summaries = buildSessionSummaries(turns, markers, filesBySession);
+    const existingIntents = await store.listIntents({ limit: 500 });
+    const existingAttachments = [];
+    for (const i of existingIntents) {
+        const sessions = await store.listIntentSessions(i.intent_id);
+        for (const sid of sessions) {
+            existingAttachments.push({ intent_id: i.intent_id, session_id: sid });
+        }
+    }
+    const result = stitchIntents(summaries, existingIntents, existingAttachments, opts);
+    let created = 0;
+    const existingIds = new Set(existingIntents.map((i) => i.intent_id));
+    for (const i of result.intents) {
+        await store.upsertIntent(i);
+        if (!existingIds.has(i.intent_id))
+            created += 1;
+    }
+    for (const a of result.attachments) {
+        await store.attachSession(a.intent_id, a.session_id);
+    }
+    return {
+        created,
+        attached: result.attachments.length,
+        dormant: result.dormantTransitions.length,
+    };
+}

package/dist/timeline/loop-miner.js

@@ -0,0 +1,140 @@
+/**
+ * Loop Miner (ST-3a).
+ *
+ * Pure functions over shadow-ledger entries. Surfaces two confusion shapes:
+ *   1. File-read loops — same file read ≥5 times within a 10-minute window
+ *      with no edit in between. Signal that the agent is rereading instead of
+ *      progressing.
+ *   2. Query-search loops — same `search_code` query issued ≥3 times within
+ *      a 20-minute window. Signal of a gap in the agent's mental model (the
+ *      function was renamed, the symbol doesn't exist, etc.).
+ *
+ * Read-only: never writes anything. Callers (the dashboard route, the future
+ * insights panel) pass in entries from `ShadowLedger.getRecentEntries()`.
+ */
+const READ_TOOLS = new Set(["file_read", "file_outline", "get_file", "Read"]);
+const EDIT_TOOLS = new Set([
+    "Edit",
+    "Write",
+    "MultiEdit",
+    "NotebookEdit",
+    "edit_file",
+    "write_file",
+]);
+const DEFAULT_READ_WINDOW_MS = 10 * 60_000;
+const DEFAULT_QUERY_WINDOW_MS = 20 * 60_000;
+const DEFAULT_READ_THRESHOLD = 5;
+const DEFAULT_QUERY_THRESHOLD = 3;
+function entryFilePath(entry) {
+    const fp = entry.args_summary?.file_path ??
+        entry.args_summary?.path;
+    return typeof fp === "string" && fp.length > 0 ? fp : null;
+}
+function entryTsMs(entry) {
+    return Date.parse(entry.ts);
+}
+export function detectFileReadLoops(entries, opts = {}) {
+    const window = opts.readWindowMs ?? DEFAULT_READ_WINDOW_MS;
+    const threshold = opts.readThreshold ?? DEFAULT_READ_THRESHOLD;
+    const now = opts.nowMs ?? maxTs(entries) ?? Date.now();
+    const cutoff = now - window;
+    const grouped = new Map();
+    for (const e of entries) {
+        const ts = entryTsMs(e);
+        if (!Number.isFinite(ts) || ts < cutoff)
+            continue;
+        const fp = entryFilePath(e);
+        if (!fp)
+            continue;
+        const key = `${e.session_id}::${fp}`;
+        let bucket = grouped.get(key);
+        if (!bucket) {
+            bucket = { reads: [], lastEditTs: 0, session_id: e.session_id };
+            grouped.set(key, bucket);
+        }
+        if (EDIT_TOOLS.has(e.tool)) {
+            // Edit clears the read run — only reads AFTER the last edit count.
+            bucket.reads = [];
+            bucket.lastEditTs = ts;
+            continue;
+        }
+        if (READ_TOOLS.has(e.tool)) {
+            bucket.reads.push(e);
+        }
+    }
+    const out = [];
+    for (const [key, bucket] of grouped) {
+        if (bucket.reads.length < threshold)
+            continue;
+        const fp = key.split("::").slice(1).join("::");
+        const first = bucket.reads[0];
+        const last = bucket.reads[bucket.reads.length - 1];
+        out.push({
+            kind: "file_reread",
+            file_path: fp,
+            count: bucket.reads.length,
+            first_ts: first.ts,
+            last_ts: last.ts,
+            session_id: bucket.session_id,
+        });
+    }
+    return out.sort((a, b) => b.count - a.count);
+}
+export function detectQueryLoops(entries, opts = {}) {
+    const window = opts.queryWindowMs ?? DEFAULT_QUERY_WINDOW_MS;
+    const threshold = opts.queryThreshold ?? DEFAULT_QUERY_THRESHOLD;
+    const now = opts.nowMs ?? maxTs(entries) ?? Date.now();
+    const cutoff = now - window;
+    const grouped = new Map();
+    for (const e of entries) {
+        if (e.tool !== "search_code")
+            continue;
+        const ts = entryTsMs(e);
+        if (!Number.isFinite(ts) || ts < cutoff)
+            continue;
+        const q = e.args_summary?.query;
+        if (typeof q !== "string" || q.length === 0)
+            continue;
+        const key = `${e.session_id}::${q}`;
+        const bucket = grouped.get(key) ?? [];
+        bucket.push(e);
+        grouped.set(key, bucket);
+    }
+    const out = [];
+    for (const [key, bucket] of grouped) {
+        if (bucket.length < threshold)
+            continue;
+        const query = key.split("::").slice(1).join("::");
+        const first = bucket[0];
+        const last = bucket[bucket.length - 1];
+        out.push({
+            kind: "search_repeat",
+            query,
+            count: bucket.length,
+            first_ts: first.ts,
+            last_ts: last.ts,
+            session_id: first.session_id,
+        });
+    }
+    return out.sort((a, b) => b.count - a.count);
+}
+/**
+ * Convenience aggregator — runs both detectors and returns the union sorted by
+ * recency.
+ */
+export function detectLoops(entries, opts = {}) {
+    const all = [
+        ...detectFileReadLoops(entries, opts),
+        ...detectQueryLoops(entries, opts),
+    ];
+    return all.sort((a, b) => Date.parse(b.last_ts) - Date.parse(a.last_ts));
+}
+function maxTs(entries) {
+    let max = Number.NEGATIVE_INFINITY;
+    for (const e of entries) {
+        const t = entryTsMs(e);
+        if (Number.isFinite(t) && t > max)
+            max = t;
+    }
+    return Number.isFinite(max) ? max : null;
+}

package/dist/timeline/open-threads.js

@@ -0,0 +1,49 @@
+/**
+ * Open Threads (ST-3a).
+ *
+ * Reads markers from timeline.db and returns mark_blocker rows that do not yet
+ * have a matching mark_resolution (matched by blocker_ref → marker_id).
+ * Resume strip + insights panel use this to surface unfinished work.
+ *
+ * Read-only: never writes anything.
+ */
+/**
+ * Compute open threads from a pre-fetched list of markers. Pure — testable
+ * without a database. Resolutions whose blocker_ref points at a blocker outside
+ * this list are still counted (lookup by id, not membership).
+ */
+export function computeOpenThreads(markers) {
+    const resolvedRefs = new Set();
+    for (const m of markers) {
+        if (m.type === "mark_resolution" && m.blocker_ref.length > 0) {
+            resolvedRefs.add(m.blocker_ref);
+        }
+    }
+    const out = [];
+    for (const m of markers) {
+        if (m.type !== "mark_blocker")
+            continue;
+        if (resolvedRefs.has(m.marker_id))
+            continue;
+        out.push({
+            marker_id: m.marker_id,
+            text: m.text,
+            session_id: m.session_id,
+            turn_id: m.turn_id,
+            ts: m.ts,
+            file_path: m.file_path,
+        });
+    }
+    return out.sort((a, b) => b.ts - a.ts);
+}
+/**
+ * Async convenience wrapper: pulls markers from the store, then runs
+ * computeOpenThreads. Limit caps the underlying marker fetch (default 500).
+ */
+export async function getOpenThreads(store, opts = {}) {
+    const markers = await store.listMarkers({
+        sessionId: opts.sessionId,
+        limit: opts.limit ?? 500,
+    });
+    return computeOpenThreads(markers);
+}

package/dist/timeline/signal-reinforcer.js

@@ -0,0 +1,62 @@
+/**
+ * Signal Reinforcer (ST-5).
+ *
+ * Reinforce / contradict derived timeline signals (hot files, loops, co-changes,
+ * conventions) in `timeline.db`. Never touches `facts.db` — Layer 9 reinforcement
+ * stays on its own path.
+ *
+ * Confidence clamps to [0, 1]. Reinforcement history is unbounded in storage but
+ * the API + UI surface only the most recent 10 events. Stale signals (no
+ * reinforcement in `staleAfterMs`) are evicted by `pruneStaleSignals`.
+ */
+import { randomUUID } from "node:crypto";
+const DEFAULT_STALE_MS = 14 * 24 * 60 * 60_000;
+/**
+ * Reinforce (or contradict) a signal. Identity is either an explicit
+ * `signal_id` or a `(type, scope)` natural key — the function upserts a row
+ * if it doesn't exist yet, then appends a reinforcement event.
+ */
+export async function reinforceSignal(store, identity, delta, source, opts = {}) {
+    const now = opts.nowMs ?? Date.now();
+    const signal = await resolveSignal(store, identity);
+    if (!signal) {
+        const created = {
+            signal_id: "signal_id" in identity ? identity.signal_id : randomUUID(),
+            type: "type" in identity ? identity.type : "unknown",
+            scope: "scope" in identity ? identity.scope : "",
+            content: "type" in identity ? (identity.content ?? "") : "",
+            confidence: clamp01(0.5 + delta),
+            first_seen_at: now,
+            last_seen_at: now,
+        };
+        await store.upsertSignal(created);
+        await store.appendReinforcement(created.signal_id, now, delta, source);
+        return created;
+    }
+    signal.confidence = clamp01(signal.confidence + delta);
+    signal.last_seen_at = now;
+    await store.upsertSignal(signal);
+    await store.appendReinforcement(signal.signal_id, now, delta, source);
+    return signal;
+}
+async function resolveSignal(store, identity) {
+    if ("signal_id" in identity) {
+        return store.getSignal(identity.signal_id);
+    }
+    const all = await store.listSignals({ type: identity.type, limit: 500 });
+    return all.find((s) => s.scope === identity.scope) ?? null;
+}
+export async function pruneStaleSignals(store, opts = {}) {
+    const now = opts.nowMs ?? Date.now();
+    const cutoff = now - (opts.staleAfterMs ?? DEFAULT_STALE_MS);
+    return store.deleteSignalsBefore(cutoff);
+}
+function clamp01(v) {
+    if (!Number.isFinite(v))
+        return 0;
+    if (v < 0)
+        return 0;
+    if (v > 1)
+        return 1;
+    return v;
+}

package/dist/timeline/timeline-bootstrap.js

@@ -0,0 +1,151 @@
+/**
+ * Timeline subsystem bootstrap.
+ *
+ * Wires together the three pieces of the Timeline Layer:
+ *   1. CozoTimelineStore (timeline.db)
+ *   2. The TurnSegmenter embedded in the active ShadowLedger
+ *   3. A turn-close listener that computes a rollup and upserts it into turns
+ *
+ * Kill-switch: `UNERR_TIMELINE_V2=0` short-circuits everything — no db is
+ * opened, no listener attaches, the existing proxy/mcp-server code paths are
+ * unaffected. Same is true if startup throws — the bootstrap swallows errors
+ * after logging so the host process never crashes on timeline issues.
+ *
+ * No reads or writes to graph.db / facts.db. No edits to the shadow ledger.
+ */
+import { CozoTimelineStore } from "./timeline-store.js";
+const EDIT_TOOLS = new Set([
+    "Edit",
+    "Write",
+    "MultiEdit",
+    "NotebookEdit",
+    "edit_file",
+    "write_file",
+]);
+function defaultLog(level, msg) {
+    process.stderr.write(`[unerr:timeline] ${level.toUpperCase()}: ${msg}\n`);
+}
+/**
+ * Start the timeline subsystem. Returns null when disabled via env, or when
+ * initialisation fails (after logging the error). Callers should treat null
+ * as "timeline is off" and continue normally.
+ */
+export async function startTimelineBootstrap(opts) {
+    if (process.env.UNERR_TIMELINE_V2 === "0")
+        return null;
+    const log = opts.log ?? defaultLog;
+    let store;
+    try {
+        store = await CozoTimelineStore.create(opts.projectRoot);
+    }
+    catch (err) {
+        log("warn", `init failed: ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+    }
+    const segmenter = opts.ledger.getTurnSegmenter();
+    const unsubscribe = segmenter.onTurnClose((event) => {
+        const entries = opts.ledger
+            .getRecentEntries(100)
+            .filter((e) => e.turn_id === event.turn_id);
+        const rollup = computeTurnRollup(event, entries);
+        store.upsertTurn(rollup).catch((err) => {
+            log("warn", `upsertTurn failed for ${rollup.turn_id}: ${err instanceof Error ? err.message : String(err)}`);
+        });
+        // ST-4: persist distinct files touched in this turn so the intent stitcher
+        // has a file set to Jaccard against.
+        const files = collectFilePaths(entries);
+        if (files.length > 0) {
+            store
+                .recordSessionFiles(event.session_id, files)
+                .catch((err) => {
+                log("warn", `recordSessionFiles failed for ${event.session_id}: ${err instanceof Error ? err.message : String(err)}`);
+            });
+        }
+        // UX-2: best-effort agent name capture. Lazy resolver so late identity
+        // (after MCP `initialize`) still gets recorded.
+        const agentName = opts.getAgentName?.();
+        if (agentName) {
+            store
+                .setSessionAgent(event.session_id, agentName)
+                .catch((err) => {
+                log("warn", `setSessionAgent failed for ${event.session_id}: ${err instanceof Error ? err.message : String(err)}`);
+            });
+        }
+    });
+    log("info", `active (db ${store.dbPath})`);
+    return {
+        store,
+        stop: () => {
+            unsubscribe();
+            store.close();
+        },
+    };
+}
+/**
+ * Build a turn rollup from a close event + the entries that belong to it.
+ * Exported for testing.
+ */
+export function computeTurnRollup(event, entries) {
+    const tsValues = entries
+        .map((e) => Date.parse(e.ts))
+        .filter((n) => Number.isFinite(n));
+    const started_at = tsValues.length > 0 ? Math.min(...tsValues) : event.closed_at;
+    const filePaths = new Set();
+    let edit_count = 0;
+    let intentText;
+    const opened_by = entries[0]?.turn_confidence ?? "first_call";
+    for (const e of entries) {
+        const fp = e.args_summary?.file_path ??
+            e.args_summary?.path;
+        if (typeof fp === "string" && fp.length > 0)
+            filePaths.add(fp);
+        if (EDIT_TOOLS.has(e.tool))
+            edit_count += 1;
+        if (!intentText &&
+            e.tool === "mark_intent" &&
+            typeof e.args_summary?.text === "string") {
+            intentText = e.args_summary.text;
+        }
+    }
+    const title = intentText ?? deriveTitleFromFiles(filePaths);
+    return {
+        turn_id: event.turn_id,
+        session_id: event.session_id,
+        started_at,
+        ended_at: event.closed_at,
+        opened_by,
+        closed_reason: event.reason,
+        tool_count: entries.length,
+        file_count: filePaths.size,
+        edit_count,
+        title,
+        outcome: "unknown",
+    };
+}
+/** Extract distinct file paths touched by these entries. */
+export function collectFilePaths(entries) {
+    const set = new Set();
+    for (const e of entries) {
+        const fp = e.args_summary?.file_path ??
+            e.args_summary?.path;
+        if (typeof fp === "string" && fp.length > 0)
+            set.add(fp);
+    }
+    return [...set];
+}
+function deriveTitleFromFiles(paths) {
+    if (paths.size === 0)
+        return "";
+    // Pick the shortest path as a rough proxy for "most important file" (entry
+    // points, index files, top-level modules tend to be shorter). Cheap heuristic
+    // until ST-3 adds a smarter title miner.
+    let shortest = null;
+    for (const p of paths) {
+        if (shortest === null || p.length < shortest.length)
+            shortest = p;
+    }
+    if (!shortest)
+        return "";
+    const base = shortest.split("/").pop() ?? shortest;
+    return base;
+}