fleetlens 0.15.7 → 0.16.0

package/app/apps/web/lib/agent/run.ts

@@ -0,0 +1,426 @@
+/**
+ * Detached agent runs. A run is a claude subprocess whose lifetime is
+ * NOT tied to any HTTP request: events stream into the chat file (so a
+ * closed tab loses nothing) and to any live SSE subscribers. The registry
+ * lives on globalThis — see the note in index-store.ts.
+ */
+
+import { spawn } from "node:child_process";
+import { appendFileSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { cclensPath } from "@claude-lens/parser/fs";
+import { applyRunEvent, writeChat, type Chat, type RunEvent, type RunEventBody, type StoredMessage } from "./chat-store";
+import { agentSystemPrompt, buildUserPrompt, type ChatMessage } from "./prompt";
+
+export const MAX_CONCURRENT_RUNS = 3;
+const HARD_TIMEOUT_MS = 5 * 60_000;
+const MCP_CONNECT_ATTEMPTS = 3;
+const MCP_RETRY_DELAY_MS = 750;
+const DELTA_FLUSH_MS = 750;
+const TOOL_INPUT_PREVIEW_MAX = 300;
+
+type RunListener = (event: RunEvent) => void;
+
+type ActiveRun = {
+  chatId: string;
+  events: RunEvent[];
+  subscribers: Set<RunListener>;
+  stoppedByUser: boolean;
+  /** Chat was deleted while running: never write its file again. */
+  discarded: boolean;
+  kill: () => void;
+};
+
+type Registry = { runs: Map<string, ActiveRun> };
+const registry: Registry = ((globalThis as Record<string, unknown>).__fleetlensAgentRuns ??= {
+  runs: new Map<string, ActiveRun>(),
+}) as Registry;
+
+export function getRun(chatId: string): ActiveRun | undefined {
+  return registry.runs.get(chatId);
+}
+
+export function activeRunCount(): number {
+  return registry.runs.size;
+}
+
+export function killRun(chatId: string): void {
+  const run = registry.runs.get(chatId);
+  if (!run) return;
+  run.stoppedByUser = true;
+  run.kill();
+}
+
+/** Kill + forget: for chat deletion. The close handler must not re-persist
+ *  the file (that would resurrect the deleted chat), and the concurrency
+ *  slot frees immediately rather than when the subprocess finishes dying. */
+export function discardRun(chatId: string): void {
+  const run = registry.runs.get(chatId);
+  if (!run) return;
+  run.stoppedByUser = true;
+  run.discarded = true;
+  registry.runs.delete(chatId);
+  run.kill();
+}
+
+/** A chat file that says "running" with no live run is a zombie (server
+ *  restarted mid-run, or a crash beat the final flush). Repair on read. */
+export function reconcileChat(chat: Chat): Chat {
+  if (chat.status !== "running" || registry.runs.has(chat.id)) return chat;
+  const repaired = applyRunEvent(chat, {
+    seq: chat.lastSeq + 1,
+    type: "error",
+    message: "run interrupted — the server restarted while it was working",
+  });
+  try {
+    writeChat(repaired);
+  } catch {
+    /* read-only repair still returned */
+  }
+  return repaired;
+}
+
+/** Same trace format as llm-runner.ts so agent runs show up on /runs
+ *  and a misbehaving run (e.g. fabricated tool output) leaves a raw stream
+ *  to diagnose. */
+function newTrace(model: string, userPromptChars: number, systemPrompt: string, userPrompt: string) {
+  const runsDir = cclensPath("llm-runs");
+  const runId = `${new Date().toISOString().replace(/[:.]/g, "-")}_agent_chat_${randomUUID().slice(0, 8)}`;
+  const path = join(runsDir, `${runId}.jsonl`);
+  const write = (record: unknown, first = false) => {
+    try {
+      const line = JSON.stringify(record) + "\n";
+      if (first) {
+        mkdirSync(runsDir, { recursive: true });
+        writeFileSync(path, line);
+      } else {
+        appendFileSync(path, line);
+      }
+    } catch {
+      /* never block the run on a trace write */
+    }
+  };
+  write(
+    {
+      _meta: {
+        type: "start",
+        run_id: runId,
+        kind: "agent_chat",
+        model,
+        ts: new Date().toISOString(),
+        runtime: "detached",
+        user_prompt_chars: userPromptChars,
+      },
+    },
+    true,
+  );
+  write({ _meta: { type: "payload", run_id: runId, system_prompt: systemPrompt, user_prompt: userPrompt } });
+  return {
+    line: (raw: string) => {
+      try {
+        appendFileSync(path, raw + "\n");
+      } catch {}
+    },
+    end: (fields: Record<string, unknown>) =>
+      write({ _meta: { type: "end", run_id: runId, ts: new Date().toISOString(), ...fields } }),
+  };
+}
+
+function pruneInput(input: unknown): unknown {
+  const s = JSON.stringify(input) ?? "{}";
+  if (s.length <= TOOL_INPUT_PREVIEW_MAX) return input;
+  return { _truncated: s.slice(0, TOOL_INPUT_PREVIEW_MAX) + "…" };
+}
+
+/** Human line for a tool result: our own tools return JSON, so peek inside. */
+function briefResult(text: string): string {
+  try {
+    const obj = JSON.parse(text) as Record<string, unknown>;
+    if (typeof obj.total_matches === "number") return `${obj.total_matches} matching sessions`;
+    if (Array.isArray(obj.sessions)) return `${(obj.total as number) ?? obj.sessions.length} sessions`;
+    if (Array.isArray(obj.projects)) return `${obj.projects.length} projects`;
+  } catch {
+    /* not JSON — fall through */
+  }
+  return `${text.length.toLocaleString()} chars`;
+}
+
+function toChatMessages(messages: StoredMessage[]): ChatMessage[] {
+  return messages
+    .map((m): ChatMessage => {
+      if (m.role === "user") return { role: "user", text: m.text };
+      const text = m.segments
+        .filter((s): s is Extract<typeof s, { kind: "text" }> => s.kind === "text")
+        .map((s) => s.text)
+        .join("");
+      return { role: "assistant", text };
+    })
+    .filter((m) => m.text.trim());
+}
+
+/** Start a detached run for `chat` (already persisted with the trailing
+ *  user message + empty assistant message, status "running"). */
+export function startRun(chat: Chat, opts: { model: string; mcpUrl: string }): void {
+  if (registry.runs.has(chat.id)) throw new Error("run already active for this chat");
+
+  let seq = chat.lastSeq;
+  let state = chat;
+  let lastFlushMs = 0;
+
+  const run: ActiveRun = {
+    chatId: chat.id,
+    events: [],
+    subscribers: new Set(),
+    stoppedByUser: false,
+    discarded: false,
+    kill: () => {}, // rebound to the live subprocess by each launch()
+  };
+  registry.runs.set(chat.id, run);
+
+  const persist = (force: boolean) => {
+    if (run.discarded) return; // deleted mid-run — don't resurrect the file
+    const now = Date.now();
+    if (!force && now - lastFlushMs < DELTA_FLUSH_MS) return;
+    lastFlushMs = now;
+    try {
+      writeChat(state);
+    } catch {
+      /* a failed flush is recovered by the next one */
+    }
+  };
+
+  const emit = (e: RunEventBody) => {
+    const event = { seq: ++seq, ...e } as RunEvent;
+    run.events.push(event);
+    state = applyRunEvent(state, event);
+    // Deltas flush on a timer; structural events flush immediately so the
+    // file never shows a tool call without its eventual result for long.
+    persist(event.type !== "delta");
+    for (const fn of run.subscribers) {
+      try {
+        fn(event);
+      } catch {
+        /* a broken subscriber must not stall the run */
+      }
+    }
+  };
+
+  const args = [
+    "-p",
+    "--output-format", "stream-json",
+    "--verbose",
+    "--include-partial-messages",
+    "--model", opts.model,
+    // Built-in tools off; the session-history MCP tools are the whole surface.
+    "--tools", "",
+    "--disable-slash-commands",
+    "--no-session-persistence",
+    "--setting-sources", "",
+    "--strict-mcp-config",
+    "--mcp-config", JSON.stringify({ mcpServers: { fleetlens: { type: "http", url: opts.mcpUrl } } }),
+    "--allowedTools",
+    "mcp__fleetlens__search_sessions",
+    "mcp__fleetlens__get_session",
+    "mcp__fleetlens__list_sessions",
+    "mcp__fleetlens__list_projects",
+    "--effort", "medium",
+    "--append-system-prompt", agentSystemPrompt(),
+  ];
+
+  // Neutral cwd: spawned from inside a repo, Claude Code would load that
+  // project's CLAUDE.md and auto-memory into context — the model then
+  // cites memory files as if they were linkable pages.
+  const runtimeDir = cclensPath("agent-runtime");
+  mkdirSync(runtimeDir, { recursive: true });
+  const userPrompt = buildUserPrompt(toChatMessages(chat.messages));
+
+  const killTimer = setTimeout(() => {
+    emit({ type: "error", message: `timed out after ${HARD_TIMEOUT_MS / 60000} minutes` });
+    run.kill();
+  }, HARD_TIMEOUT_MS);
+
+  const finish = () => {
+    clearTimeout(killTimer);
+    persist(true);
+    registry.runs.delete(chat.id);
+  };
+
+  const launch = (attempt: number) => {
+    if (run.stoppedByUser || state.status !== "running") {
+      if (run.stoppedByUser && state.status === "running") emit({ type: "error", message: "stopped by user" });
+      finish();
+      return;
+    }
+
+    const trace = newTrace(opts.model, userPrompt.length, agentSystemPrompt(), userPrompt);
+    const startMs = Date.now();
+    const proc = spawn("claude", args, {
+      stdio: ["pipe", "pipe", "pipe"],
+      env: { ...process.env },
+      cwd: runtimeDir,
+    });
+    run.kill = () => {
+      try {
+        proc.kill("SIGTERM");
+      } catch {}
+    };
+    proc.stdin.write(userPrompt);
+    proc.stdin.end();
+
+    /** This attempt was superseded by a retry — swallow everything else it produces. */
+    let abandoned = false;
+    let stderr = "";
+    let lineBuf = "";
+    let sawTerminal = false;
+    let usage: { input_tokens?: number; output_tokens?: number } | undefined;
+    /** Content-block indices that streamed text deltas for the in-flight
+     *  assistant message. The complete-message frame only re-emits a text
+     *  block if ITS deltas never arrived (CLI without partial messages, or
+     *  a dropped delta line) — a per-message flag would drop a block whose
+     *  deltas were lost whenever any other block streamed. */
+    let deltaBlocks = new Set<number>();
+    const toolNames = new Map<string, string>();
+
+    const handleLine = (t: string) => {
+      let obj: Record<string, unknown>;
+      try {
+        obj = JSON.parse(t) as Record<string, unknown>;
+      } catch {
+        return;
+      }
+      if (obj.type !== "stream_event") trace.line(t); // partial deltas would bloat the trace
+      if (obj.type === "system" && obj.subtype === "init") {
+        // The subprocess can race ahead of the HTTP MCP handshake: init
+        // reports the fleetlens server "pending" and the model runs with
+        // ZERO tools — it then "narrates" tool calls as text instead of
+        // making them. The tool list is fixed at init, so a pending server
+        // means a degraded run. Respawn (the handshake wins next time).
+        const servers = obj.mcp_servers as Array<{ name?: string; status?: string }> | undefined;
+        const fleetlens = servers?.find((s) => s.name === "fleetlens");
+        if (fleetlens && fleetlens.status !== "connected") {
+          abandoned = true;
+          trace.end({ runtime: "detached", elapsed_ms: Date.now() - startMs, mcp_status: fleetlens.status, retried: attempt < MCP_CONNECT_ATTEMPTS });
+          try {
+            proc.kill("SIGTERM");
+          } catch {}
+          if (attempt < MCP_CONNECT_ATTEMPTS) {
+            setTimeout(() => launch(attempt + 1), MCP_RETRY_DELAY_MS);
+          } else {
+            emit({ type: "error", message: `session tools failed to connect (mcp status: ${fleetlens.status}) — try again` });
+            finish();
+          }
+        }
+        return;
+      }
+      if (obj.type === "stream_event") {
+        const event = obj.event as Record<string, unknown> | undefined;
+        if (event?.type === "content_block_delta") {
+          const delta = event.delta as Record<string, unknown> | undefined;
+          if (delta?.type === "text_delta" && typeof delta.text === "string") {
+            if (typeof event.index === "number") deltaBlocks.add(event.index);
+            emit({ type: "delta", text: delta.text });
+          }
+        }
+        return;
+      }
+      if (obj.type === "assistant") {
+        const msg = obj.message as Record<string, unknown> | undefined;
+        const content = msg?.content as Array<Record<string, unknown>> | undefined;
+        if (Array.isArray(content)) {
+          content.forEach((block, i) => {
+            if (block.type === "text" && typeof block.text === "string" && !deltaBlocks.has(i)) {
+              emit({ type: "delta", text: block.text });
+            }
+            if (block.type === "tool_use" && typeof block.name === "string") {
+              const id = typeof block.id === "string" ? block.id : "";
+              const name = block.name.replace(/^mcp__fleetlens__/, "");
+              toolNames.set(id, name);
+              emit({ type: "tool", id, name, input: pruneInput(block.input) });
+            }
+          });
+        }
+        deltaBlocks = new Set();
+        return;
+      }
+      if (obj.type === "user") {
+        const msg = obj.message as Record<string, unknown> | undefined;
+        const content = msg?.content as Array<Record<string, unknown>> | undefined;
+        if (!Array.isArray(content)) return;
+        for (const block of content) {
+          if (block.type !== "tool_result") continue;
+          const id = typeof block.tool_use_id === "string" ? block.tool_use_id : "";
+          const inner = block.content;
+          const text = Array.isArray(inner)
+            ? inner
+                .map((b) => (b && typeof b === "object" && "text" in b ? String((b as { text: unknown }).text) : ""))
+                .join("")
+            : typeof inner === "string"
+              ? inner
+              : "";
+          emit({
+            type: "tool_result",
+            id,
+            name: toolNames.get(id) ?? "tool",
+            brief: briefResult(text),
+            isError: block.is_error === true,
+          });
+        }
+        return;
+      }
+      if (obj.type === "result") {
+        sawTerminal = true;
+        usage = obj.usage as { input_tokens?: number; output_tokens?: number } | undefined;
+        const totalTokens =
+          typeof usage?.input_tokens === "number" && typeof usage?.output_tokens === "number"
+            ? usage.input_tokens + usage.output_tokens
+            : undefined;
+        emit({ type: "done", totalTokens });
+      }
+    };
+
+    // Streaming decoder: chunk.toString("utf8") would mangle a multi-byte
+    // character split across stdout reads, corrupting that JSON line.
+    const decoder = new TextDecoder("utf-8");
+    proc.stdout.on("data", (chunk: Buffer) => {
+      if (abandoned) return;
+      lineBuf += decoder.decode(chunk, { stream: true });
+      const lines = lineBuf.split("\n");
+      lineBuf = lines.pop() ?? "";
+      for (const line of lines) {
+        const t = line.trim();
+        if (t && !abandoned) handleLine(t);
+      }
+    });
+    proc.stderr.on("data", (c: Buffer) => {
+      // Only a 400-char tail is ever surfaced; cap so a chatty subprocess
+      // can't grow the buffer unbounded before the kill timer.
+      if (stderr.length < 4000) stderr += c.toString("utf8");
+    });
+    proc.on("close", (code) => {
+      if (abandoned) return; // the retry owns the run lifecycle now
+      if (!sawTerminal && state.status === "running") {
+        const message = run.stoppedByUser
+          ? "stopped by user"
+          : stderr.trim().slice(0, 400) || `claude exited with code ${code}`;
+        emit({ type: "error", message });
+      }
+      trace.end({
+        runtime: "detached",
+        elapsed_ms: Date.now() - startMs,
+        exit_code: code ?? 0,
+        input_tokens: usage?.input_tokens,
+        output_tokens: usage?.output_tokens,
+      });
+      finish();
+    });
+    proc.on("error", (err) => {
+      if (abandoned) return;
+      emit({ type: "error", message: `Failed to spawn claude: ${err.message}` });
+      trace.end({ runtime: "detached", elapsed_ms: Date.now() - startMs, exit_code: -1, error: err.message });
+      finish();
+    });
+  };
+
+  launch(1);
+}

package/app/apps/web/lib/agent/search.test.ts

@@ -0,0 +1,111 @@
+import { describe, expect, test } from "vitest";
+import type { IndexDoc } from "./types";
+import { searchDocs } from "./search";
+
+function doc(partial: Partial<IndexDoc> & { sessionId: string }): IndexDoc {
+  return {
+    version: 1,
+    agent: "claude-code",
+    project: "/Users/me/Repo/foo",
+    day: "2026-07-01",
+    title: "untitled",
+    chunks: [],
+    mtimeMs: 0,
+    sizeBytes: 0,
+    ...partial,
+  };
+}
+
+const DOCS: IndexDoc[] = [
+  doc({
+    sessionId: "s1",
+    day: "2026-07-08",
+    title: "fix usage daemon crash",
+    chunks: [
+      { role: "user", text: "the usage daemon keeps crashing on boot", idx: 0 },
+      { role: "agent", text: "The crash came from a stale pid file in ~/.cclens", idx: 1 },
+    ],
+  }),
+  doc({
+    sessionId: "s2",
+    day: "2026-06-01",
+    project: "/Users/me/Repo/bar",
+    agent: "codex",
+    title: "add usage chart",
+    chunks: [{ role: "agent", text: "Added the usage chart with recharts", idx: 0 }],
+  }),
+  doc({
+    sessionId: "s3",
+    day: "2026-07-09",
+    title: "refactor timeline",
+    chunks: [{ role: "user", text: "please refactor the timeline page", idx: 0 }],
+  }),
+];
+
+describe("searchDocs", () => {
+  test("matches terms case-insensitively, ranking full-term matches first", () => {
+    const { hits, total } = searchDocs(DOCS, "USAGE daemon");
+    // s1 matches both terms, s2 matches only "usage" — ranked-OR semantics.
+    expect(total).toBe(2);
+    expect(hits[0]!.sessionId).toBe("s1");
+    expect(hits[0]!.matchedTerms.sort()).toEqual(["daemon", "usage"]);
+  });
+
+  test("docs matching all terms rank above partial matches", () => {
+    const { hits } = searchDocs(DOCS, "usage daemon chart");
+    // s1 matches usage+daemon (2 terms), s2 matches usage+chart (2 terms) — tie on
+    // count; but neither matches all 3. Both must appear, full-match-first ordering
+    // is covered by the score, so just assert both are present.
+    expect(hits.map((h) => h.sessionId).sort()).toEqual(["s1", "s2"]);
+  });
+
+  test("returns empty for no matches and blank queries", () => {
+    expect(searchDocs(DOCS, "zzzznope").hits).toEqual([]);
+    expect(searchDocs(DOCS, "  ").hits).toEqual([]);
+  });
+
+  test("quoted phrases require exact substring match", () => {
+    const { hits } = searchDocs(DOCS, '"stale pid file"');
+    expect(hits.map((h) => h.sessionId)).toEqual(["s1"]);
+    expect(searchDocs(DOCS, '"stale file pid"').hits).toEqual([]);
+  });
+
+  test("filters by project, agent, and day bounds", () => {
+    expect(searchDocs(DOCS, "usage", { filters: { agent: "codex" } }).hits.map((h) => h.sessionId)).toEqual(["s2"]);
+    expect(
+      searchDocs(DOCS, "usage", { filters: { project: "/Users/me/Repo/foo" } }).hits.map((h) => h.sessionId),
+    ).toEqual(["s1"]);
+    expect(searchDocs(DOCS, "usage", { filters: { after: "2026-07-01" } }).hits.map((h) => h.sessionId)).toEqual(["s1"]);
+    expect(searchDocs(DOCS, "usage", { filters: { before: "2026-06-30" } }).hits.map((h) => h.sessionId)).toEqual(["s2"]);
+  });
+
+  test("produces snippets around the match with role attribution", () => {
+    const { hits } = searchDocs(DOCS, "pid");
+    const snip = hits[0]!.snippets[0]!;
+    expect(snip.role).toBe("agent");
+    expect(snip.text).toContain("stale pid file");
+  });
+
+  test("newer sessions outrank older ones at equal relevance", () => {
+    const twin = (id: string, day: string) =>
+      doc({ sessionId: id, day, title: "same", chunks: [{ role: "user", text: "identical content here", idx: 0 }] });
+    const { hits } = searchDocs([twin("old", "2025-01-01"), twin("new", "2026-07-01")], "identical");
+    expect(hits.map((h) => h.sessionId)).toEqual(["new", "old"]);
+  });
+
+  test("respects limit but reports full total", () => {
+    const many = Array.from({ length: 30 }, (_, i) =>
+      doc({ sessionId: `m${i}`, chunks: [{ role: "user", text: "needle in haystack", idx: 0 }] }),
+    );
+    const { hits, total } = searchDocs(many, "needle", { limit: 5 });
+    expect(hits).toHaveLength(5);
+    expect(total).toBe(30);
+  });
+
+  test("title matches outweigh body matches", () => {
+    const titled = doc({ sessionId: "titled", title: "daemon work", chunks: [{ role: "agent", text: "unrelated", idx: 0 }] });
+    const body = doc({ sessionId: "body", title: "misc", chunks: [{ role: "agent", text: "daemon mentioned once", idx: 0 }] });
+    const { hits } = searchDocs([body, titled], "daemon");
+    expect(hits[0]!.sessionId).toBe("titled");
+  });
+});

package/app/apps/web/lib/agent/search.ts

@@ -0,0 +1,144 @@
+import type { IndexDoc, SearchFilters, SearchHit, SearchSnippet } from "./types";
+
+const SNIPPET_RADIUS = 120;
+const MAX_SNIPPETS = 3;
+const ROLE_WEIGHT: Record<string, number> = { user: 2, summary: 3, agent: 1 };
+const TITLE_WEIGHT = 4;
+/** Recency half-life: a hit ages to half its score every 60 days. */
+const HALF_LIFE_MS = 60 * 86_400_000;
+
+type ParsedQuery = { terms: string[]; phrases: string[] };
+
+export function parseQuery(q: string): ParsedQuery {
+  const phrases: string[] = [];
+  const rest = q.replace(/"([^"]+)"/g, (_, p: string) => {
+    phrases.push(p.toLowerCase());
+    return " ";
+  });
+  const terms = Array.from(
+    new Set(
+      rest
+        .toLowerCase()
+        .split(/[^\p{L}\p{N}_./-]+/u)
+        .filter((t) => t.length >= 2),
+    ),
+  );
+  return { terms, phrases };
+}
+
+function passesFilters(doc: IndexDoc, f?: SearchFilters): boolean {
+  if (!f) return true;
+  if (f.project && doc.project !== f.project) return false;
+  if (f.agent && doc.agent !== f.agent) return false;
+  if (f.after && doc.day < f.after) return false;
+  if (f.before && doc.day > f.before) return false;
+  return true;
+}
+
+function countOccurrences(haystack: string, needle: string): number {
+  let count = 0;
+  let pos = haystack.indexOf(needle);
+  while (pos !== -1) {
+    count++;
+    pos = haystack.indexOf(needle, pos + needle.length);
+  }
+  return count;
+}
+
+function snippetAround(text: string, matchPos: number, matchLen: number): string {
+  const start = Math.max(0, matchPos - SNIPPET_RADIUS);
+  const end = Math.min(text.length, matchPos + matchLen + SNIPPET_RADIUS);
+  const core = text.slice(start, end).replace(/\s+/g, " ").trim();
+  return `${start > 0 ? "…" : ""}${core}${end < text.length ? "…" : ""}`;
+}
+
+export function searchDocs(
+  docs: IndexDoc[],
+  query: string,
+  opts: { filters?: SearchFilters; limit?: number } = {},
+): { hits: SearchHit[]; total: number } {
+  const { terms, phrases } = parseQuery(query);
+  if (terms.length === 0 && phrases.length === 0) return { hits: [], total: 0 };
+
+  const nowMs = Date.now();
+  const scored: SearchHit[] = [];
+
+  for (const doc of docs) {
+    if (!passesFilters(doc, opts.filters)) continue;
+
+    const titleLower = doc.title.toLowerCase();
+    const matched = new Set<string>();
+    let score = 0;
+    const snippets: SearchSnippet[] = [];
+
+    // Phrases are hard requirements.
+    let phrasesOk = true;
+    for (const phrase of phrases) {
+      let found = false;
+      if (titleLower.includes(phrase)) {
+        found = true;
+        score += TITLE_WEIGHT * 2;
+      }
+      for (const chunk of doc.chunks) {
+        const lower = chunk.text.toLowerCase();
+        const pos = lower.indexOf(phrase);
+        if (pos === -1) continue;
+        found = true;
+        score += (ROLE_WEIGHT[chunk.role] ?? 1) * 2;
+        if (snippets.length < MAX_SNIPPETS) {
+          snippets.push({ role: chunk.role, text: snippetAround(chunk.text, pos, phrase.length) });
+        }
+      }
+      if (!found) {
+        phrasesOk = false;
+        break;
+      }
+      matched.add(`"${phrase}"`);
+    }
+    if (!phrasesOk) continue;
+
+    for (const term of terms) {
+      let termHits = 0;
+      if (titleLower.includes(term)) {
+        termHits += TITLE_WEIGHT;
+      }
+      for (const chunk of doc.chunks) {
+        const lower = chunk.text.toLowerCase();
+        const n = countOccurrences(lower, term);
+        if (n === 0) continue;
+        // log-dampen repeats so one chatty session doesn't dominate on frequency
+        termHits += (ROLE_WEIGHT[chunk.role] ?? 1) * (1 + Math.log2(n));
+        if (termHits > 0 && snippets.length < MAX_SNIPPETS) {
+          const pos = lower.indexOf(term);
+          snippets.push({ role: chunk.role, text: snippetAround(chunk.text, pos, term.length) });
+        }
+      }
+      if (termHits > 0) {
+        matched.add(term);
+        score += termHits;
+      }
+    }
+
+    if (matched.size === 0) continue;
+
+    const docMs = doc.startIso ? Date.parse(doc.startIso) : NaN;
+    const ageMs = Number.isNaN(docMs) ? HALF_LIFE_MS : Math.max(0, nowMs - docMs);
+    const recency = Math.pow(0.5, ageMs / HALF_LIFE_MS);
+    // Full-term coverage dominates, then relevance × recency.
+    const allTerms = matched.size === terms.length + phrases.length ? 1 : 0;
+    scored.push({
+      sessionId: doc.sessionId,
+      agent: doc.agent,
+      project: doc.project,
+      day: doc.day,
+      title: doc.title,
+      score: allTerms * 1_000_000 + score * (0.25 + 0.75 * recency),
+      matchedTerms: Array.from(matched),
+      snippets: snippets.slice(0, MAX_SNIPPETS),
+    });
+  }
+
+  scored.sort((a, b) => b.score - a.score || b.day.localeCompare(a.day));
+  const limit = opts.limit ?? 10;
+  return { hits: scored.slice(0, limit), total: scored.length };
+}