pi-vault-mind 0.14.2 → 0.16.3

package/dist/test/server-ws.test.js

@@ -5,16 +5,8 @@ import { afterEach, beforeEach, describe, it } from "node:test";
 import { WebSocket } from "ws";
 import { createJob, markJobDone, markJobRunning } from "../src/agent-queue.js";
 import { _resetAuthCache } from "../src/auth.js";
-import { createServerState, startServer, stopServer } from "../src/server.js";
-import { createWatcherState } from "../src/watcher.js";
+import { fakePi, makeVault, startTestServer } from "./helpers/server.js";
 const envVar = "PVM_API_TOKEN";
-const tmpVault = () => {
-    const p = path.join(process.cwd(), `.tmp-ws-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
-    if (fs.existsSync(p))
-        fs.rmSync(p, { recursive: true });
-    fs.mkdirSync(p, { recursive: true });
-    return p;
-};
 const waitForOpen = (ws, timeoutMs = 5000) => new Promise((resolve, reject) => {
     if (ws.readyState === ws.OPEN)
         return resolve();
@@ -67,49 +59,43 @@ const connect = (port, token) => {
         headers: token ? { Authorization: `Bearer ${token}` } : undefined,
     });
 };
+const isRecord = (value) => Boolean(value) && typeof value === "object";
+const isActivityTone = (value) => value === "neutral" || value === "ok" || value === "warn" || value === "error";
+function assertIsoString(value) {
+    if (typeof value !== "string")
+        assert.fail(`expected string timestamp, got ${String(value)}`);
+    assert.ok(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(value), `expected ISO timestamp, got ${String(value)}`);
+    assert.ok(!Number.isNaN(Date.parse(value)), `expected parseable ISO timestamp, got ${value}`);
+}
 describe("WebSocket /agent/stream", () => {
     let vaultPath;
-    let serverState;
-    let watcherState;
+    let srv;
     let port;
     let savedEnv;
     let savedHome;
+    let savedCwd;
     beforeEach(async () => {
         savedEnv = process.env[envVar];
         savedHome = process.env.HOME;
-        vaultPath = tmpVault();
+        savedCwd = process.cwd();
+        vaultPath = makeVault("ws");
         process.env.HOME = vaultPath;
         process.env[envVar] = "ws-test-token";
         _resetAuthCache();
-        fs.mkdirSync(path.join(vaultPath, ".pi", "agent"), { recursive: true });
-        fs.writeFileSync(path.join(vaultPath, ".pi", "agent", "vault-mind.config.json"), JSON.stringify({
+        process.chdir(vaultPath);
+        fs.mkdirSync(path.join(vaultPath, ".vault-mind"), { recursive: true });
+        fs.writeFileSync(path.join(vaultPath, ".vault-mind", "vault-mind.config.json"), JSON.stringify({
             vaultMind: {
                 vaults: { default: { path: vaultPath } },
                 embedding: { modal: { apiToken: "ws-test-token" } },
             },
         }), "utf-8");
-        watcherState = createWatcherState();
-        serverState = createServerState(0);
-        startServer({}, serverState, watcherState);
-        await new Promise((resolve, reject) => {
-            const srv = serverState.server;
-            if (!srv)
-                return reject(new Error("server not created"));
-            if (srv.listening) {
-                const addr = srv.address();
-                port = typeof addr === "object" && addr ? addr.port : 0;
-                return resolve();
-            }
-            srv.once("listening", () => {
-                const addr = srv.address();
-                port = typeof addr === "object" && addr ? addr.port : 0;
-                resolve();
-            });
-            srv.once("error", reject);
-        });
+        srv = await startTestServer(fakePi);
+        port = srv.port;
     });
     afterEach(async () => {
-        stopServer(serverState);
+        srv.stop();
+        process.chdir(savedCwd);
         if (savedEnv === undefined)
             process.env[envVar] = undefined;
         else
@@ -193,6 +179,47 @@ describe("WebSocket /agent/stream", () => {
         const types = events.map((e) => e.type);
         assert.deepEqual(types, ["job-updated", "job-notification", "job-completed"]);
     });
+    it("markJobRunning emits both queue update and activity event frames", async () => {
+        createJob(vaultPath, {
+            id: "j-activity",
+            vaultPath,
+            filePath: path.join(vaultPath, "activity.md"),
+            role: "miner",
+            agentName: "vault-mind-miner",
+            instruction: "test",
+            markerCount: 1,
+        });
+        const ws = connect(port, "ws-test-token");
+        const snapshotPromise = collectEvents(ws, 1);
+        await waitForOpen(ws);
+        await snapshotPromise;
+        try {
+            const eventsPromise = collectEvents(ws, 2, 1000);
+            markJobRunning(vaultPath, "j-activity");
+            const events = await eventsPromise;
+            const queueEvent = events.find((event) => isRecord(event) && event.type === "job-updated");
+            assert.ok(queueEvent, `expected job-updated frame, got ${JSON.stringify(events)}`);
+            assert.ok(isRecord(queueEvent.job));
+            assert.equal(queueEvent.job.id, "j-activity");
+            const activityFrame = events.find((event) => isRecord(event) && event.type === "activity-event");
+            assert.ok(activityFrame, `expected activity-event frame, got ${JSON.stringify(events)}`);
+            assert.ok(isRecord(activityFrame.event));
+            const activity = activityFrame.event;
+            assert.equal(activity.jobId, "j-activity");
+            assert.equal(activity.kind, "status");
+            assertIsoString(activity.ts);
+            if (typeof activity.label !== "string" || activity.label.trim().length === 0) {
+                assert.fail("expected non-empty activity label");
+            }
+            if (activity.tone !== undefined) {
+                assert.ok(isActivityTone(activity.tone));
+                assert.notEqual(activity.tone, "error");
+            }
+        }
+        finally {
+            ws.close();
+        }
+    });
     it("unsubscribes on close and does not receive further events", async () => {
         const ws = connect(port, "ws-test-token");
         const eventsPromise = collectEvents(ws, 1);

package/dist/test/session-crud.test.js

@@ -0,0 +1,323 @@
+import { strict as assert } from "node:assert";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { after, afterEach, before, beforeEach, describe, it } from "node:test";
+import { archiveSession, deleteSession, exportSession, getSession, listSessions, renameSession, SESSION_ID_RE, } from "../src/session-search.js";
+import { fakePi, fetchJson, makeVault, startTestServer, TEST_TOKEN, writeVaultConfig, } from "./helpers/server.js";
+const envVar = "PVM_API_TOKEN";
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+describe("Session CRUD (BC-7)", () => {
+    let tmpDir;
+    let sessionsDir;
+    let savedEnv;
+    let vaultPath;
+    let port;
+    let srv;
+    let savedCwd;
+    let savedSessionsDir;
+    before(() => {
+        savedEnv = process.env[envVar];
+        savedCwd = process.cwd();
+        savedSessionsDir = process.env.PI_SESSIONS_DIR;
+        process.env[envVar] = TEST_TOKEN;
+    });
+    after(() => {
+        srv?.stop();
+        if (savedEnv === undefined)
+            delete process.env[envVar];
+        else
+            process.env[envVar] = savedEnv;
+        process.chdir(savedCwd);
+        if (savedSessionsDir === undefined)
+            delete process.env.PI_SESSIONS_DIR;
+        else
+            process.env.PI_SESSIONS_DIR = savedSessionsDir;
+    });
+    beforeEach(() => {
+        // Fresh temp sessions dir for each test
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "pvm-session-crud-"));
+        sessionsDir = path.join(tmpDir, "sessions");
+        const slugDir = path.join(sessionsDir, "--test--");
+        fs.mkdirSync(slugDir, { recursive: true });
+        // Seed a single session
+        const sessionFile = path.join(slugDir, "2026-07-13T14-25-00_abc.jsonl");
+        const lines = [
+            JSON.stringify({ type: "session", id: "sess-001", cwd: "/test", timestamp: "T" }),
+            JSON.stringify({ type: "session_name", name: "My Session" }),
+            JSON.stringify({
+                type: "message",
+                id: "m1",
+                timestamp: "T",
+                message: { role: "user", content: "Hello world" },
+            }),
+            JSON.stringify({
+                type: "message",
+                id: "m2",
+                timestamp: "T",
+                message: { role: "assistant", content: "Hi there" },
+            }),
+        ];
+        fs.writeFileSync(sessionFile, lines.join("\n") + "\n", "utf-8");
+        // Point the session-search module at our temp dir
+        process.env.PI_SESSIONS_DIR = sessionsDir;
+    });
+    // REST tests need a vault; chdir into it before each REST test
+    async function setupVaultForRest() {
+        vaultPath = makeVault("session-crud");
+        writeVaultConfig(vaultPath, {
+            vaultMind: { vaults: { default: { path: vaultPath } } },
+        });
+        process.chdir(vaultPath);
+    }
+    afterEach(() => {
+        srv?.stop();
+        srv = undefined;
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+        if (fs.existsSync(vaultPath))
+            fs.rmSync(vaultPath, { recursive: true, force: true });
+    });
+    async function bootServer() {
+        srv = await startTestServer(fakePi);
+        port = srv.port;
+    }
+    // ── Unit tests for pure functions ────────────────────────────────
+    describe("SESSION_ID_RE", () => {
+        it("accepts valid session file stems", () => {
+            assert.ok(SESSION_ID_RE.test("2026-07-13T14-25-00_abc123"));
+            assert.ok(SESSION_ID_RE.test("simple-id"));
+            assert.ok(SESSION_ID_RE.test("v1.0.0"));
+        });
+        it("rejects path traversal and special chars", () => {
+            assert.ok(!SESSION_ID_RE.test("../etc/passwd"));
+            assert.ok(!SESSION_ID_RE.test("a/b"));
+            assert.ok(!SESSION_ID_RE.test("-leading-dash"));
+            assert.ok(!SESSION_ID_RE.test("has space"));
+            assert.ok(!SESSION_ID_RE.test(""));
+        });
+    });
+    describe("listSessions", () => {
+        it("returns summaries for valid sessions", () => {
+            const sessions = listSessions(sessionsDir);
+            assert.equal(sessions.length, 1);
+            const s = sessions[0];
+            assert.equal(s.id, "2026-07-13T14-25-00_abc");
+            assert.equal(s.name, "My Session");
+            assert.equal(s.messageCount, 2);
+            assert.equal(s.archived, false);
+            assert.ok(s.preview.includes("Hello"));
+        });
+        it("returns [] for missing dir", () => {
+            assert.deepEqual(listSessions("/nonexistent"), []);
+        });
+        it("returns [] for empty dir", () => {
+            assert.deepEqual(listSessions(""), []);
+        });
+    });
+    describe("getSession", () => {
+        it("returns detail with entries for valid id", () => {
+            const detail = getSession(sessionsDir, "2026-07-13T14-25-00_abc");
+            assert.equal(detail.id, "2026-07-13T14-25-00_abc");
+            assert.equal(detail.entries.length, 2);
+            assert.equal(detail.entries[0].role, "user");
+            assert.equal(detail.entries[0].content, "Hello world");
+            assert.equal(detail.entries[1].role, "assistant");
+        });
+        it("throws for invalid id", () => {
+            assert.throws(() => getSession(sessionsDir, "../etc"), /Invalid session id/);
+        });
+        it("throws for missing session", () => {
+            assert.throws(() => getSession(sessionsDir, "nonexistent"), /Session not found/);
+        });
+    });
+    describe("renameSession", () => {
+        it("appends a session_name entry", () => {
+            const r = renameSession(sessionsDir, "2026-07-13T14-25-00_abc", "New Name");
+            assert.equal(r.ok, true);
+            assert.equal(r.name, "New Name");
+            // Read back — name should be "New Name"
+            const detail = getSession(sessionsDir, "2026-07-13T14-25-00_abc");
+            assert.equal(detail.name, "New Name");
+        });
+        it("rejects empty name", () => {
+            assert.throws(() => renameSession(sessionsDir, "2026-07-13T14-25-00_abc", ""), /empty/);
+        });
+    });
+    describe("archiveSession", () => {
+        it("appends archive flag and round-trips", () => {
+            const r = archiveSession(sessionsDir, "2026-07-13T14-25-00_abc");
+            assert.equal(r.ok, true);
+            // Read back — archived should be true
+            const detail = getSession(sessionsDir, "2026-07-13T14-25-00_abc");
+            assert.equal(detail.archived, true);
+        });
+    });
+    describe("deleteSession", () => {
+        it("removes the session file", () => {
+            deleteSession(sessionsDir, "2026-07-13T14-25-00_abc");
+            assert.deepEqual(listSessions(sessionsDir), []);
+        });
+    });
+    describe("exportSession", () => {
+        beforeEach(() => {
+            vaultPath = makeVault("session-crud-export");
+        });
+        it("copies the session to .vault-mind/exports", () => {
+            const r = exportSession(sessionsDir, "2026-07-13T14-25-00_abc", vaultPath);
+            assert.ok(r.path.endsWith(".jsonl"));
+            assert.ok(fs.existsSync(r.path));
+            const content = fs.readFileSync(r.path, "utf-8");
+            assert.ok(content.includes("Hello world"));
+        });
+    });
+    // ── REST integration tests ───────────────────────────────────────
+    describe("REST /sessions", () => {
+        beforeEach(async () => {
+            await setupVaultForRest();
+        });
+        it("GET /sessions returns the list", async () => {
+            await bootServer();
+            const { status, body } = await fetchJson(port, "GET", "/sessions", { token: TEST_TOKEN });
+            assert.equal(status, 200);
+            assert.ok(Array.isArray(body), "expected session list array");
+            assert.equal(body.length, 1);
+            const first = body[0];
+            assert.ok(isRecord(first));
+            assert.ok(typeof first.id === "string");
+            assert.equal(first.id, "2026-07-13T14-25-00_abc");
+        });
+        it("GET /sessions requires auth", async () => {
+            await bootServer();
+            const { status } = await fetchJson(port, "GET", "/sessions");
+            assert.equal(status, 401);
+        });
+        it("GET /sessions/:id returns detail", async () => {
+            await bootServer();
+            const { status, body } = await fetchJson(port, "GET", "/sessions/2026-07-13T14-25-00_abc", {
+                token: TEST_TOKEN,
+            });
+            assert.equal(status, 200);
+            assert.ok(isRecord(body));
+            assert.ok(typeof body.id === "string");
+            assert.equal(body.id, "2026-07-13T14-25-00_abc");
+            assert.ok(Array.isArray(body.entries));
+            assert.equal(body.entries.length, 2);
+            const first = body.entries[0];
+            assert.ok(isRecord(first));
+            assert.ok(typeof first.role === "string");
+            assert.equal(first.role, "user");
+        });
+        it("GET /sessions/:id returns 404 for missing", async () => {
+            await bootServer();
+            const { status } = await fetchJson(port, "GET", "/sessions/nonexistent", {
+                token: TEST_TOKEN,
+            });
+            assert.equal(status, 404);
+        });
+        it("GET /sessions/:id returns 404 for invalid id (path traversal)", async () => {
+            await bootServer();
+            const { status } = await fetchJson(port, "GET", "/sessions/..%2Fetc", { token: TEST_TOKEN });
+            // %2F decodes to /, which doesn't match the session path regex → 404
+            assert.equal(status, 404);
+        });
+        it("PATCH /sessions/:id renames the session", async () => {
+            await bootServer();
+            const { status, body } = await fetchJson(port, "PATCH", "/sessions/2026-07-13T14-25-00_abc", {
+                body: { name: "Renamed" },
+                token: TEST_TOKEN,
+            });
+            assert.equal(status, 200);
+            assert.ok(isRecord(body));
+            assert.ok(typeof body.name === "string");
+            assert.equal(body.name, "Renamed");
+            // Verify via GET
+            const { body: detail } = await fetchJson(port, "GET", "/sessions/2026-07-13T14-25-00_abc", {
+                token: TEST_TOKEN,
+            });
+            assert.ok(isRecord(detail));
+            assert.ok(typeof detail.name === "string");
+            assert.equal(detail.name, "Renamed");
+        });
+        it("PATCH /sessions/:id rejects empty name with 400", async () => {
+            await bootServer();
+            const { status } = await fetchJson(port, "PATCH", "/sessions/2026-07-13T14-25-00_abc", {
+                body: { name: "" },
+                token: TEST_TOKEN,
+            });
+            assert.equal(status, 400);
+        });
+        it("POST /sessions/:id/export exports to vault", async () => {
+            await bootServer();
+            const { status, body } = await fetchJson(port, "POST", "/sessions/2026-07-13T14-25-00_abc/export", { token: TEST_TOKEN });
+            assert.equal(status, 200);
+            assert.ok(isRecord(body));
+            assert.ok(typeof body.path === "string");
+            assert.ok(fs.existsSync(body.path));
+        });
+        it("POST /sessions/:id/archive archives the session", async () => {
+            await bootServer();
+            const { status } = await fetchJson(port, "POST", "/sessions/2026-07-13T14-25-00_abc/archive", { token: TEST_TOKEN });
+            assert.equal(status, 200);
+            // Verify via GET — archived should be true
+            const { body } = await fetchJson(port, "GET", "/sessions/2026-07-13T14-25-00_abc", {
+                token: TEST_TOKEN,
+            });
+            assert.ok(isRecord(body));
+            assert.equal(body.archived, true);
+        });
+        it("DELETE /sessions/:id removes the session", async () => {
+            await bootServer();
+            const { status } = await fetchJson(port, "DELETE", "/sessions/2026-07-13T14-25-00_abc", {
+                token: TEST_TOKEN,
+            });
+            assert.equal(status, 200);
+            // Verify gone
+            assert.deepEqual(listSessions(sessionsDir), []);
+        });
+        it("DELETE /sessions/:id returns 409 for active session", async () => {
+            await bootServer();
+            // Set the server's active session ID to the test session
+            srv.serverState.activeSessionId = "2026-07-13T14-25-00_abc";
+            const { status, body } = await fetchJson(port, "DELETE", "/sessions/2026-07-13T14-25-00_abc", { token: TEST_TOKEN });
+            assert.equal(status, 409);
+            assert.ok(isRecord(body));
+            assert.ok(typeof body.error === "string");
+            assert.ok(body.error.includes("active"));
+        });
+        it("PATCH /sessions/:id returns 409 for active session", async () => {
+            await bootServer();
+            srv.serverState.activeSessionId = "2026-07-13T14-25-00_abc";
+            const { status } = await fetchJson(port, "PATCH", "/sessions/2026-07-13T14-25-00_abc", {
+                body: { name: "X" },
+                token: TEST_TOKEN,
+            });
+            assert.equal(status, 409);
+        });
+        it("POST /sessions/:id/archive returns 409 for active session", async () => {
+            await bootServer();
+            srv.serverState.activeSessionId = "2026-07-13T14-25-00_abc";
+            const { status } = await fetchJson(port, "POST", "/sessions/2026-07-13T14-25-00_abc/archive", { token: TEST_TOKEN });
+            assert.equal(status, 409);
+        });
+        it("DELETE /sessions/:id returns 409 via X-Active-Session header (plugin path)", async () => {
+            await bootServer();
+            // Plugin sets the active session via header on each request
+            const { status, body } = await fetchJson(port, "DELETE", "/sessions/2026-07-13T14-25-00_abc", { token: TEST_TOKEN, headers: { "X-Active-Session": "2026-07-13T14-25-00_abc" } });
+            assert.equal(status, 409);
+            assert.ok(isRecord(body));
+            assert.ok(typeof body.error === "string");
+            assert.ok(body.error.includes("active"));
+        });
+        it("POST /sessions/:id/export does NOT require write gate (read-only)", async () => {
+            await bootServer();
+            srv.serverState.activeSessionId = "2026-07-13T14-25-00_abc";
+            const { status } = await fetchJson(port, "POST", "/sessions/2026-07-13T14-25-00_abc/export", {
+                token: TEST_TOKEN,
+            });
+            // Export is read-only — should succeed even for active session
+            assert.equal(status, 200);
+        });
+    });
+});

package/dist/test/session-search.test.js

@@ -0,0 +1,139 @@
+import { strict as assert } from "node:assert";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { after, before, describe, it } from "node:test";
+import { searchSessions } from "../src/session-search.js";
+describe("searchSessions", () => {
+    let tmpDir;
+    let sessionsDir;
+    before(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "pvm-session-test-"));
+        sessionsDir = path.join(tmpDir, "sessions");
+        // Create a cwd-slug dir
+        const slugDir = path.join(sessionsDir, "--workspace--test");
+        fs.mkdirSync(slugDir, { recursive: true });
+        // Session file: header + session_name + messages
+        const sessionFile = path.join(slugDir, "2026-07-13T14-25-00_abc123.jsonl");
+        const lines = [
+            JSON.stringify({
+                type: "session",
+                id: "sess-001",
+                cwd: "/workspace/test",
+                timestamp: "2026-07-13T14:25:00Z",
+            }),
+            JSON.stringify({ type: "session_name", name: "Test Session" }),
+            JSON.stringify({
+                type: "message",
+                id: "msg-001",
+                parentId: undefined,
+                timestamp: "2026-07-13T14:25:01Z",
+                message: {
+                    role: "user",
+                    content: "Tell me about the widget system",
+                    timestamp: "2026-07-13T14:25:01Z",
+                },
+            }),
+            JSON.stringify({
+                type: "message",
+                id: "msg-002",
+                parentId: "msg-001",
+                timestamp: "2026-07-13T14:25:02Z",
+                message: {
+                    role: "assistant",
+                    content: [
+                        {
+                            type: "text",
+                            text: "To be completely clear, this is a much longer preamble that goes on for quite a while so that we can verify the widget truncation logic actually produces leading and trailing ellipsis characters.",
+                        },
+                    ],
+                },
+            }),
+            JSON.stringify({
+                type: "message",
+                id: "msg-003",
+                parentId: "msg-002",
+                timestamp: "2026-07-13T14:25:03Z",
+                message: { role: "user", content: "No match here" },
+            }),
+        ];
+        fs.writeFileSync(sessionFile, lines.join("\n") + "\n", "utf-8");
+    });
+    after(() => {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+    it("returns session hits matching the query", () => {
+        const hits = searchSessions(sessionsDir, "widget", 10);
+        assert.ok(hits.length >= 2, `expected at least 2 hits, got ${hits.length}`);
+        for (const h of hits) {
+            assert.equal(h._source, "session");
+            assert.equal(h.sessionId, "sess-001");
+            assert.equal(h.sessionTitle, "Test Session");
+            assert.ok(h.score > 0);
+            assert.ok(h.snippet.length > 0);
+            assert.ok(h.path.endsWith(".jsonl"));
+        }
+    });
+    it("returns correct role for matched entries", () => {
+        const hits = searchSessions(sessionsDir, "widget", 10);
+        const roles = hits.map((h) => h.role);
+        assert.ok(roles.includes("user"), "should have user hit");
+        assert.ok(roles.includes("assistant"), "should have assistant hit");
+    });
+    it("uses entryId from the entry id field", () => {
+        const hits = searchSessions(sessionsDir, "widget", 10);
+        const ids = hits.map((h) => h.entryId);
+        assert.ok(ids.includes("msg-001"), "should have msg-001");
+        assert.ok(ids.includes("msg-002"), "should have msg-002");
+    });
+    it("ellipsizes snippet when truncated", () => {
+        const hits = searchSessions(sessionsDir, "widget", 10);
+        const longHit = hits.find((h) => h.role === "assistant");
+        assert.ok(longHit, "should have an assistant hit");
+        assert.ok(longHit.snippet.startsWith("…"), "assistant snippet should have leading ellipsis");
+        assert.ok(longHit.snippet.endsWith("…"), "assistant snippet should have trailing ellipsis");
+    });
+    it("returns empty array for non-matching query", () => {
+        const hits = searchSessions(sessionsDir, "nonexistent", 10);
+        assert.equal(hits.length, 0);
+    });
+    it("returns empty array for empty query", () => {
+        const hits = searchSessions(sessionsDir, "", 10);
+        assert.equal(hits.length, 0);
+    });
+    it("returns empty array for missing dir", () => {
+        const hits = searchSessions("/nonexistent/path", "widget", 10);
+        assert.equal(hits.length, 0);
+    });
+    it("ranks by score descending", () => {
+        // Create a file with 2 occurrences vs 1 occurrence
+        const slugDir = path.join(sessionsDir, "--workspace--test2");
+        fs.mkdirSync(slugDir, { recursive: true });
+        const file = path.join(slugDir, "2026-07-13T15-00-00_def456.jsonl");
+        const lines = [
+            JSON.stringify({
+                type: "session",
+                id: "sess-002",
+                cwd: "/test",
+                timestamp: "2026-07-13T15:00:00Z",
+            }),
+            JSON.stringify({
+                type: "message",
+                id: "m1",
+                timestamp: "T",
+                message: { role: "user", content: "widget widget widget" },
+            }),
+            JSON.stringify({
+                type: "message",
+                id: "m2",
+                timestamp: "T",
+                message: { role: "assistant", content: "widget" },
+            }),
+        ];
+        fs.writeFileSync(file, lines.join("\n") + "\n", "utf-8");
+        const hits = searchSessions(sessionsDir, "widget", 10);
+        assert.ok(hits.length >= 3, `expected at least 3 hits, got ${hits.length}`);
+        // Score 3 should rank above score 1
+        assert.ok(hits[0].score >= hits[1].score, "hits should be sorted by score desc");
+    });
+});