@lightupai/polaris 0.0.76 → 0.0.78

package/tests/annotations.test.ts

@@ -0,0 +1,209 @@
+import { describe, expect, test, beforeAll, afterAll } from "bun:test";
+import {
+  createDb,
+  createOrg,
+  createProject,
+  createSession,
+  pushEvent,
+  addAnnotation,
+  listSessionAnnotations,
+  listDecisions,
+  deleteAnnotation,
+  searchEvents,
+  type Sql,
+} from "../src/service/db";
+import { Annotation } from "../src/types";
+import type { PolarisEvent } from "../src/types";
+
+const DATABASE_URL = process.env.DATABASE_URL ?? "postgres://polaris:polaris@localhost:5432/polaris_test";
+
+// Unique ids so this file is self-contained against a live Postgres.
+// (annotations rows survive resetTestData, so org-scoped uniqueness matters.)
+const RUN = crypto.randomUUID().slice(0, 8);
+const ORG = `anno-org-${RUN}`;
+const OTHER_ORG = `anno-other-org-${RUN}`;
+const PROJECT = `pj-anno-${RUN}`;
+const PROJECT_B = `pj-anno-b-${RUN}`;
+
+let sql: Sql;
+
+function makeEvent(overrides: Partial<PolarisEvent> = {}): PolarisEvent {
+  return {
+    id: crypto.randomUUID(),
+    project: PROJECT,
+    session: "s1",
+    timestamp: new Date().toISOString(),
+    source: "hook",
+    sender: "user:manu",
+    payload: { hook_event_name: "UserPromptSubmit", session_id: "cc-s", prompt: "hello" },
+    ...overrides,
+  };
+}
+
+beforeAll(async () => {
+  // Drop and recreate via createDb (mirrors tests/db.test.ts) so the schema —
+  // including the additive annotations migration — matches src/service/db.ts exactly.
+  sql = await createDb(DATABASE_URL);
+  await sql`DROP TABLE IF EXISTS plan_changes`;
+  await sql`DROP TABLE IF EXISTS events`;
+  await sql`DROP TABLE IF EXISTS sessions`;
+  await sql`DROP TABLE IF EXISTS projects`;
+  await sql`DROP TABLE IF EXISTS users`;
+  await sql`DROP TABLE IF EXISTS orgs`;
+  await sql.end();
+  sql = await createDb(DATABASE_URL);
+  await createOrg(sql, ORG, "Annotations Org");
+  await createOrg(sql, OTHER_ORG, "Other Annotations Org");
+  await createProject(sql, ORG, PROJECT);
+  await createProject(sql, ORG, PROJECT_B);
+  await createSession(sql, ORG, PROJECT, "s1", "user:manu");
+  await createSession(sql, ORG, PROJECT, "s2", "user:manu");
+});
+
+afterAll(async () => {
+  await sql.end();
+});
+
+describe("annotations CRUD", () => {
+  test("add a star and list it back", async () => {
+    const event = makeEvent();
+    await pushEvent(sql, ORG, event);
+    const { id } = await addAnnotation(sql, ORG, {
+      event_id: event.id,
+      project: PROJECT,
+      session: "s1",
+      participant_id: "user:manu",
+      kind: "star",
+    });
+    expect(id).toBeDefined();
+
+    const annotations = await listSessionAnnotations(sql, ORG, PROJECT, "s1");
+    const star = annotations.find((a) => a.id === id);
+    expect(star).toBeDefined();
+    expect(star!.kind).toBe("star");
+    expect(star!.event_id).toBe(event.id);
+    expect(star!.participant_id).toBe("user:manu");
+    expect(star!.value).toBeNull();
+    // Round-trips through the shared zod schema
+    expect(() => Annotation.parse(star)).not.toThrow();
+  });
+
+  test("add a tag with a value and a session-level decision (no event_id)", async () => {
+    const event = makeEvent();
+    await pushEvent(sql, ORG, event);
+    const tag = await addAnnotation(sql, ORG, {
+      event_id: event.id,
+      project: PROJECT,
+      session: "s1",
+      participant_id: "user:krishna",
+      kind: "tag",
+      value: "auth",
+    });
+    const decision = await addAnnotation(sql, ORG, {
+      project: PROJECT,
+      session: "s1",
+      kind: "decision",
+      value: "Use RS256 for signing",
+    });
+
+    const annotations = await listSessionAnnotations(sql, ORG, PROJECT, "s1");
+    const tagged = annotations.find((a) => a.id === tag.id);
+    expect(tagged!.kind).toBe("tag");
+    expect(tagged!.value).toBe("auth");
+
+    const decided = annotations.find((a) => a.id === decision.id);
+    expect(decided!.kind).toBe("decision");
+    expect(decided!.event_id).toBeNull();
+    expect(decided!.participant_id).toBeNull();
+  });
+
+  test("listSessionAnnotations is scoped to org, project, and session", async () => {
+    const inS2 = await addAnnotation(sql, ORG, { project: PROJECT, session: "s2", kind: "star" });
+    const otherOrg = await addAnnotation(sql, OTHER_ORG, { project: PROJECT, session: "s1", kind: "star" });
+
+    const s1Ids = (await listSessionAnnotations(sql, ORG, PROJECT, "s1")).map((a) => a.id);
+    expect(s1Ids).not.toContain(inS2.id);
+    expect(s1Ids).not.toContain(otherOrg.id);
+
+    const s2Ids = (await listSessionAnnotations(sql, ORG, PROJECT, "s2")).map((a) => a.id);
+    expect(s2Ids).toContain(inS2.id);
+  });
+
+  test("listDecisions returns only decisions, newest first, with project filter and limit", async () => {
+    const d1 = await addAnnotation(sql, ORG, { project: PROJECT, session: "s2", kind: "decision", value: "first" });
+    const d2 = await addAnnotation(sql, ORG, { project: PROJECT_B, session: "s9", kind: "decision", value: "second" });
+    await addAnnotation(sql, ORG, { project: PROJECT_B, session: "s9", kind: "tag", value: "not-a-decision" });
+
+    const all = await listDecisions(sql, ORG);
+    expect(all.every((a) => a.kind === "decision")).toBe(true);
+    const ids = all.map((a) => a.id);
+    expect(ids).toContain(d1.id);
+    expect(ids).toContain(d2.id);
+    // Newest first
+    expect(ids.indexOf(d2.id)).toBeLessThan(ids.indexOf(d1.id));
+
+    const onlyB = await listDecisions(sql, ORG, { project: PROJECT_B });
+    expect(onlyB.map((a) => a.id)).toContain(d2.id);
+    expect(onlyB.map((a) => a.id)).not.toContain(d1.id);
+
+    const limited = await listDecisions(sql, ORG, { limit: 1 });
+    expect(limited).toHaveLength(1);
+  });
+
+  test("deleteAnnotation removes it; wrong org is a no-op", async () => {
+    const { id } = await addAnnotation(sql, ORG, { project: PROJECT, session: "s1", kind: "star" });
+
+    // Deleting under a different org must not remove it
+    await deleteAnnotation(sql, OTHER_ORG, id);
+    let ids = (await listSessionAnnotations(sql, ORG, PROJECT, "s1")).map((a) => a.id);
+    expect(ids).toContain(id);
+
+    await deleteAnnotation(sql, ORG, id);
+    ids = (await listSessionAnnotations(sql, ORG, PROJECT, "s1")).map((a) => a.id);
+    expect(ids).not.toContain(id);
+  });
+});
+
+describe("searchEvents tag filter", () => {
+  // Distinctive vocabulary ("kraken") so full-text matches are unambiguous.
+  const taggedInfra = makeEvent({
+    timestamp: "2026-06-10T10:00:00.000Z",
+    payload: { hook_event_name: "UserPromptSubmit", session_id: "cc-s", prompt: "the kraken deployment plan" },
+  });
+  const taggedBug = makeEvent({
+    timestamp: "2026-06-10T10:01:00.000Z",
+    payload: { hook_event_name: "UserPromptSubmit", session_id: "cc-s", prompt: "kraken retry logic" },
+  });
+  const untagged = makeEvent({
+    timestamp: "2026-06-10T10:02:00.000Z",
+    payload: { hook_event_name: "UserPromptSubmit", session_id: "cc-s", prompt: "kraken docs" },
+  });
+
+  beforeAll(async () => {
+    for (const event of [taggedInfra, taggedBug, untagged]) {
+      await pushEvent(sql, ORG, event);
+    }
+    await addAnnotation(sql, ORG, { event_id: taggedInfra.id, project: PROJECT, session: "s1", kind: "tag", value: "infra" });
+    await addAnnotation(sql, ORG, { event_id: taggedBug.id, project: PROJECT, session: "s1", kind: "tag", value: "bug" });
+    // A star with the same value must NOT satisfy the tag filter (kind='tag' only)
+    await addAnnotation(sql, ORG, { event_id: untagged.id, project: PROJECT, session: "s1", kind: "star", value: "infra" });
+  });
+
+  test("without a tag filter all matches are returned", async () => {
+    const { results } = await searchEvents(sql, ORG, { q: "kraken" });
+    expect(results.map((r) => r.event.id).sort()).toEqual([taggedInfra.id, taggedBug.id, untagged.id].sort());
+  });
+
+  test("tag filter restricts to events carrying that tag annotation", async () => {
+    const infra = await searchEvents(sql, ORG, { q: "kraken", tag: "infra" });
+    expect(infra.results.map((r) => r.event.id)).toEqual([taggedInfra.id]);
+
+    const bug = await searchEvents(sql, ORG, { q: "kraken", tag: "bug" });
+    expect(bug.results.map((r) => r.event.id)).toEqual([taggedBug.id]);
+  });
+
+  test("an unknown tag matches nothing", async () => {
+    const { results } = await searchEvents(sql, ORG, { q: "kraken", tag: "nope" });
+    expect(results).toEqual([]);
+  });
+});

package/tests/bridge-discover.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, test, beforeAll, afterAll } from "bun:test";
+import {
+  createDb,
+  createOrg,
+  setOrgSlack,
+  type Sql,
+} from "../src/service/db";
+
+const DATABASE_URL = process.env.DATABASE_URL ?? "postgres://polaris:polaris@localhost:5432/polaris_test";
+
+// Unique ids so this file is self-contained against a live Postgres.
+const RUN = crypto.randomUUID().slice(0, 8);
+const ORG_A = `bridge-org-a-${RUN}`;
+const ORG_B = `bridge-org-b-${RUN}`;
+const ORG_NO_SLACK = `bridge-org-plain-${RUN}`;
+const ORG_TEAM_ONLY = `bridge-org-teamonly-${RUN}`;
+
+// Make sure the schema exists before importing the discovery module (its legacy
+// form runs a query at import time), then resolve the contract export. Until the
+// bridge agent's work is integrated the export is absent and these tests skip.
+{
+  const bootstrap = await createDb(DATABASE_URL);
+  await bootstrap.end();
+}
+let discoverBridgeOrgs: ((sql: Sql) => Promise<string[]>) | undefined;
+try {
+  const mod = (await import("../src/bridge-discover-org")) as Record<string, unknown>;
+  if (typeof mod.discoverBridgeOrgs === "function") {
+    discoverBridgeOrgs = mod.discoverBridgeOrgs as (sql: Sql) => Promise<string[]>;
+  }
+} catch {
+  // Import-time side effects failed (legacy script form) — treat as not available.
+}
+if (!discoverBridgeOrgs) {
+  console.warn("[bridge-discover.test] discoverBridgeOrgs not exported yet — skipping (expected before bridge-agent integration)");
+}
+
+let sql: Sql;
+
+beforeAll(async () => {
+  sql = await createDb(DATABASE_URL);
+  // Eligible: both slack_team_id and slack_bot_token set
+  await createOrg(sql, ORG_A, "Bridge Org A");
+  await setOrgSlack(sql, ORG_A, `T-A-${RUN}`, `xoxb-a-${RUN}`);
+  await createOrg(sql, ORG_B, "Bridge Org B");
+  await setOrgSlack(sql, ORG_B, `T-B-${RUN}`, `xoxb-b-${RUN}`);
+  // Ineligible: no Slack at all
+  await createOrg(sql, ORG_NO_SLACK, "Bridge Org Plain");
+  // Ineligible: team id but no bot token
+  await createOrg(sql, ORG_TEAM_ONLY, "Bridge Org Team Only");
+  await sql`UPDATE orgs SET slack_team_id = ${`T-half-${RUN}`} WHERE id = ${ORG_TEAM_ONLY}`;
+});
+
+afterAll(async () => {
+  await sql.end();
+});
+
+describe("discoverBridgeOrgs", () => {
+  test.skipIf(!discoverBridgeOrgs)("returns every org with full Slack credentials (no LIMIT 1)", async () => {
+    const orgs = await discoverBridgeOrgs!(sql);
+    expect(orgs).toContain(ORG_A);
+    expect(orgs).toContain(ORG_B);
+  });
+
+  test.skipIf(!discoverBridgeOrgs)("excludes orgs without complete Slack credentials", async () => {
+    const orgs = await discoverBridgeOrgs!(sql);
+    expect(orgs).not.toContain(ORG_NO_SLACK);
+    expect(orgs).not.toContain(ORG_TEAM_ONLY);
+  });
+});

package/tests/daemon-auth.test.ts

@@ -0,0 +1,123 @@
+import { describe, expect, test, afterAll } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { Subprocess } from "bun";
+
+// Best-effort coverage of the shared-local-secret daemon auth contract:
+//   - secret resolved (env POLARIS_DAEMON_SECRET) -> every endpoint requires
+//     the `x-polaris-daemon-secret` header, 401 otherwise
+//   - no secret resolved -> no auth (test/back-compat mode)
+//
+// The daemon runs as a SUBPROCESS with an isolated HOME so that neither the
+// secret env var nor any real ~/.polaris/config.json can leak into the other
+// test files (which start in-process daemons without auth).
+// Until the daemon agent's enforcement is integrated, the enforcement tests
+// detect "no 401" and skip with a warning instead of failing.
+
+const DAEMON_PATH = join(import.meta.dir, "..", "src", "daemon", "daemon.ts");
+const SECRET = `test-secret-${crypto.randomUUID()}`;
+
+const cleanups: Array<() => Promise<void> | void> = [];
+
+function baseEnv(home: string, overrides: Record<string, string>): Record<string, string> {
+  const env = { ...(process.env as Record<string, string>) };
+  delete env.POLARIS_DAEMON_SECRET;
+  return {
+    ...env,
+    HOME: home,
+    // /status and /register never call upstream; point it nowhere just in case.
+    POLARIS_SERVICE_URL: "http://127.0.0.1:9",
+    POLARIS_AUTH_TOKEN: "",
+    ...overrides,
+  };
+}
+
+async function spawnDaemon(overrides: Record<string, string>): Promise<{ proc: Subprocess; url: string } | null> {
+  const home = await mkdtemp(join(tmpdir(), "polaris-daemon-auth-"));
+  cleanups.push(() => rm(home, { recursive: true, force: true }));
+  for (let attempt = 0; attempt < 3; attempt++) {
+    const port = 20000 + Math.floor(Math.random() * 20000);
+    const proc = Bun.spawn([process.execPath, DAEMON_PATH], {
+      env: baseEnv(home, { POLARIS_DAEMON_PORT: String(port), ...overrides }),
+      stdout: "ignore",
+      stderr: "ignore",
+    });
+    const url = `http://127.0.0.1:${port}`;
+    const deadline = Date.now() + 8000;
+    while (Date.now() < deadline) {
+      if (proc.exitCode !== null) break; // crashed (port collision) — retry on a new port
+      try {
+        await fetch(`${url}/status`); // any HTTP response (200 or 401) means it's up
+        cleanups.push(() => { proc.kill(); });
+        return { proc, url };
+      } catch {
+        await Bun.sleep(100);
+      }
+    }
+    proc.kill();
+  }
+  return null;
+}
+
+const secured = await spawnDaemon({ POLARIS_DAEMON_SECRET: SECRET });
+let enforced = false;
+if (!secured) {
+  console.warn("[daemon-auth.test] could not start a daemon subprocess — skipping daemon auth tests");
+} else {
+  enforced = (await fetch(`${secured.url}/status`)).status === 401;
+  if (!enforced) {
+    console.warn("[daemon-auth.test] secret enforcement not detected — skipping (expected before daemon-agent integration)");
+  }
+}
+
+const unsecured = await spawnDaemon({});
+
+afterAll(async () => {
+  for (const cleanup of cleanups.reverse()) {
+    try { await cleanup(); } catch { /* best-effort */ }
+  }
+});
+
+describe("daemon auth (shared local secret)", () => {
+  test.skipIf(!enforced)("rejects requests without the secret header", async () => {
+    expect((await fetch(`${secured!.url}/status`)).status).toBe(401);
+    expect((await fetch(`${secured!.url}/status/cc-anything`)).status).toBe(401);
+    const post = await fetch(`${secured!.url}/register`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ ccSessionId: "cc-auth-1" }),
+    });
+    expect(post.status).toBe(401);
+  });
+
+  test.skipIf(!enforced)("rejects a wrong secret", async () => {
+    const res = await fetch(`${secured!.url}/status`, {
+      headers: { "x-polaris-daemon-secret": "wrong-secret" },
+    });
+    expect(res.status).toBe(401);
+  });
+
+  test.skipIf(!enforced)("accepts requests carrying the correct secret", async () => {
+    const res = await fetch(`${secured!.url}/status`, {
+      headers: { "x-polaris-daemon-secret": SECRET },
+    });
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.ok).toBe(true);
+
+    const post = await fetch(`${secured!.url}/register`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", "x-polaris-daemon-secret": SECRET },
+      body: JSON.stringify({ ccSessionId: "cc-auth-2" }),
+    });
+    expect(post.status).toBe(200);
+  });
+
+  test.skipIf(!unsecured)("without a resolved secret the daemon requires no auth (back-compat)", async () => {
+    const res = await fetch(`${unsecured!.url}/status`);
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.ok).toBe(true);
+  });
+});

package/tests/event-lookup.test.ts

@@ -0,0 +1,113 @@
+import { describe, expect, test, beforeAll, afterAll } from "bun:test";
+import {
+  createDb,
+  createOrg,
+  createProject,
+  createSession,
+  pushEvent,
+  getEventById,
+  getSessionEvents,
+  type Sql,
+} from "../src/service/db";
+import type { PolarisEvent } from "../src/types";
+
+const DATABASE_URL = process.env.DATABASE_URL ?? "postgres://polaris:polaris@localhost:5432/polaris_test";
+
+// Unique ids so this file is self-contained against a live Postgres.
+const RUN = crypto.randomUUID().slice(0, 8);
+const ORG = `lookup-org-${RUN}`;
+const PROJECT = `pj-lookup-${RUN}`;
+
+let sql: Sql;
+
+function makeEvent(overrides: Partial<PolarisEvent> = {}): PolarisEvent {
+  return {
+    id: crypto.randomUUID(),
+    project: PROJECT,
+    session: "s1",
+    timestamp: new Date().toISOString(),
+    source: "hook",
+    sender: "user:manu",
+    payload: { hook_event_name: "UserPromptSubmit", session_id: "cc-s", prompt: "hello lookup" },
+    ...overrides,
+  };
+}
+
+beforeAll(async () => {
+  // Drop and recreate via createDb (mirrors tests/db.test.ts) so the schema
+  // matches src/service/db.ts exactly.
+  sql = await createDb(DATABASE_URL);
+  await sql`DROP TABLE IF EXISTS plan_changes`;
+  await sql`DROP TABLE IF EXISTS events`;
+  await sql`DROP TABLE IF EXISTS sessions`;
+  await sql`DROP TABLE IF EXISTS projects`;
+  await sql`DROP TABLE IF EXISTS users`;
+  await sql`DROP TABLE IF EXISTS orgs`;
+  await sql.end();
+  sql = await createDb(DATABASE_URL);
+  await createOrg(sql, ORG, "Lookup Org");
+  await createProject(sql, ORG, PROJECT);
+  await createSession(sql, ORG, PROJECT, "s1", "user:manu");
+});
+
+afterAll(async () => {
+  await sql.end();
+});
+
+describe("pushEvent + getEventById", () => {
+  test("a pushed event is retrievable by id with project name and org_id", async () => {
+    const event = makeEvent();
+    await pushEvent(sql, ORG, event);
+
+    const fetched = await getEventById(sql, event.id);
+    expect(fetched).not.toBeNull();
+    expect(fetched!.id).toBe(event.id);
+    expect(fetched!.project).toBe(PROJECT);
+    expect(fetched!.session).toBe("s1");
+    expect(fetched!.source).toBe("hook");
+    expect(fetched!.sender).toBe("user:manu");
+    expect(fetched!.payload).toEqual(event.payload);
+    expect(fetched!.org_id).toBe(ORG);
+  });
+
+  test("returns null for an unknown uuid and for a malformed id", async () => {
+    expect(await getEventById(sql, crypto.randomUUID())).toBeNull();
+    // NOTIFY payloads are untyped strings — a non-uuid must not throw
+    expect(await getEventById(sql, "not-a-uuid")).toBeNull();
+  });
+
+  test("pushEvent into a nonexistent project is a silent no-op", async () => {
+    const event = makeEvent({ project: `pj-missing-${RUN}` });
+    await pushEvent(sql, ORG, event); // must not throw
+    expect(await getEventById(sql, event.id)).toBeNull();
+  });
+});
+
+describe("LISTEN/NOTIFY realtime backbone", () => {
+  test("pushEvent NOTIFYs 'polaris_event' with the event id", async () => {
+    // Dedicated second connection for LISTEN, mirroring how server.ts/bridge subscribe.
+    const listener = await createDb(DATABASE_URL);
+    const received: string[] = [];
+    try {
+      await listener.listen("polaris_event", (payload) => {
+        received.push(payload);
+      });
+
+      const event = makeEvent({ payload: { hook_event_name: "UserPromptSubmit", session_id: "cc-s", prompt: "notify me" } });
+      await pushEvent(sql, ORG, event);
+
+      const deadline = Date.now() + 5000;
+      while (!received.includes(event.id) && Date.now() < deadline) {
+        await Bun.sleep(25);
+      }
+      expect(received).toContain(event.id);
+
+      // The notified id resolves to the full event via getEventById (the listener's own connection)
+      const fetched = await getEventById(listener, event.id);
+      expect(fetched).not.toBeNull();
+      expect(fetched!.org_id).toBe(ORG);
+    } finally {
+      await listener.end({ timeout: 5 });
+    }
+  }, 15000);
+});

package/tests/label.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, test, beforeAll, afterAll } from "bun:test";
+import {
+  createDb,
+  createOrg,
+  createProject,
+  createSession,
+  getSession,
+  listSessions,
+  setSessionLabel,
+  type Sql,
+} from "../src/service/db";
+
+const DATABASE_URL = process.env.DATABASE_URL ?? "postgres://polaris:polaris@localhost:5432/polaris_test";
+
+// Unique ids so this file is self-contained against a live Postgres.
+const RUN = crypto.randomUUID().slice(0, 8);
+const ORG = `label-org-${RUN}`;
+const PROJECT = `pj-label-${RUN}`;
+const SESSION = "fx-label";
+const OTHER_SESSION = "fx-other";
+
+let sql: Sql;
+
+beforeAll(async () => {
+  // Drop and recreate via createDb (NOT tests/helpers.ts resetTestData, which builds
+  // a sessions table without the label column) so the additive label migration applies.
+  sql = await createDb(DATABASE_URL);
+  await sql`DROP TABLE IF EXISTS plan_changes`;
+  await sql`DROP TABLE IF EXISTS events`;
+  await sql`DROP TABLE IF EXISTS sessions`;
+  await sql`DROP TABLE IF EXISTS projects`;
+  await sql`DROP TABLE IF EXISTS users`;
+  await sql`DROP TABLE IF EXISTS orgs`;
+  await sql.end();
+  sql = await createDb(DATABASE_URL);
+  await createOrg(sql, ORG, "Label Org");
+  await createProject(sql, ORG, PROJECT);
+});
+
+afterAll(async () => {
+  await sql.end();
+});
+
+describe("session labels", () => {
+  test("createSession and getSession default to a null label", async () => {
+    const created = await createSession(sql, ORG, PROJECT, SESSION, "user:manu");
+    expect(created.label).toBeNull();
+
+    const fetched = await getSession(sql, ORG, PROJECT, SESSION);
+    expect(fetched).not.toBeNull();
+    expect(fetched!.label).toBeNull();
+  });
+
+  test("setSessionLabel then getSession returns the label", async () => {
+    await setSessionLabel(sql, ORG, PROJECT, SESSION, "Auth refactor");
+    const session = await getSession(sql, ORG, PROJECT, SESSION);
+    expect(session!.label).toBe("Auth refactor");
+  });
+
+  test("listSessions returns the label", async () => {
+    const sessions = await listSessions(sql, ORG, PROJECT);
+    const labeled = sessions.find((s) => s.name === SESSION);
+    expect(labeled).toBeDefined();
+    expect(labeled!.label).toBe("Auth refactor");
+  });
+
+  test("relabeling overwrites the previous label", async () => {
+    await setSessionLabel(sql, ORG, PROJECT, SESSION, "Token refresh work");
+    const session = await getSession(sql, ORG, PROJECT, SESSION);
+    expect(session!.label).toBe("Token refresh work");
+  });
+
+  test("labels are scoped to the target session", async () => {
+    await createSession(sql, ORG, PROJECT, OTHER_SESSION, null);
+    const other = await getSession(sql, ORG, PROJECT, OTHER_SESSION);
+    expect(other!.label).toBeNull();
+
+    const labeled = await getSession(sql, ORG, PROJECT, SESSION);
+    expect(labeled!.label).toBe("Token refresh work");
+  });
+
+  test("setSessionLabel on an unknown session is a silent no-op", async () => {
+    // Per the db contract: UPDATE matches 0 rows, no throw.
+    await setSessionLabel(sql, ORG, PROJECT, "fx-nonexistent", "ignored");
+    expect(await getSession(sql, ORG, PROJECT, "fx-nonexistent")).toBeNull();
+
+    const untouched = await getSession(sql, ORG, PROJECT, SESSION);
+    expect(untouched!.label).toBe("Token refresh work");
+  });
+});