@hellcoder/companion 0.96.0

package/server/claude-container-auth.test.ts

@@ -0,0 +1,44 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { hasContainerClaudeAuth } from "./claude-container-auth.js";
+
+describe("hasContainerClaudeAuth", () => {
+  let tempHome: string;
+  let prevHome: string | undefined;
+
+  beforeEach(() => {
+    tempHome = mkdtempSync(join(tmpdir(), "claude-auth-test-"));
+    prevHome = process.env.HOME;
+    process.env.HOME = tempHome;
+  });
+
+  afterEach(() => {
+    if (prevHome === undefined) {
+      delete process.env.HOME;
+    } else {
+      process.env.HOME = prevHome;
+    }
+    rmSync(tempHome, { recursive: true, force: true });
+  });
+
+  it("returns true when auth env vars are provided", () => {
+    expect(hasContainerClaudeAuth({ ANTHROPIC_API_KEY: "sk-test" })).toBe(true);
+    expect(hasContainerClaudeAuth({ ANTHROPIC_AUTH_TOKEN: "tok-test" })).toBe(true);
+    expect(hasContainerClaudeAuth({ CLAUDE_CODE_AUTH_TOKEN: "tok-test" })).toBe(true);
+  });
+
+  it("returns true when known auth files exist under ~/.claude", () => {
+    const claudeDir = join(tempHome, ".claude");
+    mkdirSync(claudeDir, { recursive: true });
+    writeFileSync(join(claudeDir, ".credentials.json"), "{\"token\":\"x\"}");
+
+    expect(hasContainerClaudeAuth()).toBe(true);
+  });
+
+  it("returns false when neither env nor auth files are present", () => {
+    expect(hasContainerClaudeAuth()).toBe(false);
+  });
+});
+

package/server/claude-container-auth.ts

@@ -0,0 +1,30 @@
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/**
+ * Returns true when Claude running inside a container has a plausible auth source:
+ * - explicit auth env vars, or
+ * - known auth files under ~/.claude that can be copied into the container.
+ */
+export function hasContainerClaudeAuth(envVars?: Record<string, string>): boolean {
+  if (
+    !!envVars?.ANTHROPIC_API_KEY
+    || !!envVars?.ANTHROPIC_AUTH_TOKEN
+    || !!envVars?.CLAUDE_CODE_AUTH_TOKEN
+    || !!envVars?.CLAUDE_CODE_OAUTH_TOKEN
+  ) {
+    return true;
+  }
+
+  const home = process.env.HOME || process.env.USERPROFILE || homedir();
+  const candidates = [
+    join(home, ".claude", ".credentials.json"),
+    join(home, ".claude", "auth.json"),
+    join(home, ".claude", ".auth.json"),
+    join(home, ".claude", "credentials.json"),
+  ];
+
+  return candidates.some((p) => existsSync(p));
+}
+

package/server/claude-protocol-contract.test.ts

@@ -0,0 +1,71 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { describe, expect, it } from "vitest";
+
+function readSnapshot(relativePath: string): string {
+  return readFileSync(resolve(process.cwd(), relativePath), "utf-8");
+}
+
+function extractAliasBody(tsSource: string, alias: string): string {
+  const match = tsSource.match(new RegExp(`export declare type ${alias} = \\{([\\s\\S]*?)\\n\\};`));
+  return match?.[1] || "";
+}
+
+describe("Claude protocol compatibility (offline Agent SDK snapshot)", () => {
+  it("includes all Claude message categories used by the bridge", () => {
+    const sdk = readSnapshot("server/protocol/claude-upstream/sdk.d.ts.txt");
+
+    expect(sdk).toContain("export declare type SDKAssistantMessage = {");
+    expect(sdk).toContain("type: 'assistant';");
+
+    expect(sdk).toContain("export declare type SDKPartialAssistantMessage = {");
+    expect(sdk).toContain("type: 'stream_event';");
+
+    expect(sdk).toContain("export declare type SDKResultSuccess = {");
+    expect(sdk).toContain("export declare type SDKResultError = {");
+    expect(sdk).toContain("type: 'result';");
+
+    expect(sdk).toContain("export declare type SDKToolProgressMessage = {");
+    expect(sdk).toContain("type: 'tool_progress';");
+
+    expect(sdk).toContain("export declare type SDKToolUseSummaryMessage = {");
+    expect(sdk).toContain("type: 'tool_use_summary';");
+
+    expect(sdk).toContain("export declare type SDKAuthStatusMessage = {");
+    expect(sdk).toContain("type: 'auth_status';");
+
+    expect(sdk).toContain("export declare type SDKUserMessage = {");
+    expect(sdk).toContain("type: 'user';");
+  });
+
+  it("keeps system init/status subtypes expected by ws-bridge", () => {
+    const sdk = readSnapshot("server/protocol/claude-upstream/sdk.d.ts.txt");
+
+    const systemInitBody = extractAliasBody(sdk, "SDKSystemMessage");
+    expect(systemInitBody).toContain("type: 'system';");
+    expect(systemInitBody).toContain("subtype: 'init';");
+
+    const systemStatusBody = extractAliasBody(sdk, "SDKStatusMessage");
+    expect(systemStatusBody).toContain("type: 'system';");
+    expect(systemStatusBody).toContain("subtype: 'status';");
+  });
+
+  it("keeps result and tool fields required by the UI", () => {
+    const sdk = readSnapshot("server/protocol/claude-upstream/sdk.d.ts.txt");
+
+    const resultSuccessBody = extractAliasBody(sdk, "SDKResultSuccess");
+    for (const field of ["duration_ms", "num_turns", "total_cost_usd", "stop_reason", "usage", "modelUsage"]) {
+      expect(resultSuccessBody).toContain(`${field}:`);
+    }
+
+    const toolProgressBody = extractAliasBody(sdk, "SDKToolProgressMessage");
+    for (const field of ["tool_use_id", "tool_name", "elapsed_time_seconds"]) {
+      expect(toolProgressBody).toContain(`${field}:`);
+    }
+
+    const userBody = extractAliasBody(sdk, "SDKUserMessage");
+    for (const field of ["message", "parent_tool_use_id", "session_id"]) {
+      expect(userBody).toContain(`${field}:`);
+    }
+  });
+});

package/server/claude-protocol-drift.test.ts

@@ -0,0 +1,78 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { describe, expect, it } from "vitest";
+
+function readFile(relativePath: string): string {
+  return readFileSync(resolve(process.cwd(), relativePath), "utf-8");
+}
+
+function extractCaseMethods(source: string, start: string, end: string): Set<string> {
+  const afterStart = source.split(start)[1];
+  if (!afterStart) return new Set();
+  const block = afterStart.split(end)[0] || "";
+  return new Set([...block.matchAll(/case "([^"]+)":/g)].map((m) => m[1]));
+}
+
+function extractTypeLiterals(tsSource: string): Set<string> {
+  return new Set([...tsSource.matchAll(/type:\s*'([^']+)'/g)].map((m) => m[1]));
+}
+
+describe("Claude ws-bridge method drift vs upstream Agent SDK snapshot", () => {
+  /**
+   * CLI message routing now lives in claude-adapter.ts (ClaudeAdapter.handleRawMessage).
+   * This test verifies that the adapter handles all upstream CLI message types.
+   */
+  it("keeps handled CLI message types aligned with upstream (or explicit local allowlist)", () => {
+    const adapter = readFile("server/claude-adapter.ts");
+    const sdk = readFile("server/protocol/claude-upstream/sdk.d.ts.txt");
+
+    // Extract case "xxx": from the routeCLIMessage switch in claude-adapter.ts
+    const handledFromCLI = extractCaseMethods(
+      adapter,
+      "private routeCLIMessage(msg: CLIMessage): void {",
+      "// -- System message handling",
+    );
+    expect(handledFromCLI.size).toBeGreaterThan(0);
+
+    const upstreamMessageTypes = extractTypeLiterals(sdk);
+
+    // Messages we intentionally support in raw CLI transport but are not part of SDKMessage union.
+    // - control_request / keep_alive: core transport types not in SDK
+    // - user: CLI echoes back user messages (including subagent tool_result blocks)
+    // - rate_limit_event: Claude API rate-limit status (allowed/throttled)
+    // - control_cancel_request: cancels a pending control_request (v2.1.81+)
+    // - streamlined_text / streamlined_tool_use_summary: simplified output mode (@internal, v2.1.81+)
+    // - prompt_suggestion: predicted next user prompts (v2.1.81+)
+    const localRawTransportTypes = new Set([
+      "control_request", "keep_alive", "user", "rate_limit_event",
+      "control_cancel_request", "streamlined_text", "streamlined_tool_use_summary", "prompt_suggestion",
+    ]);
+
+    for (const method of handledFromCLI) {
+      expect(
+        upstreamMessageTypes.has(method) || localRawTransportTypes.has(method),
+        `Unhandled by upstream snapshot (CLI message type): ${method}`,
+      ).toBe(true);
+    }
+  });
+
+  /**
+   * System subtypes (init, status) are now handled in claude-adapter.ts
+   * instead of ws-bridge.ts. This test verifies they are still present.
+   */
+  it("keeps system subtypes handled by ws-bridge aligned with upstream", () => {
+    const adapter = readFile("server/claude-adapter.ts");
+    const sdk = readFile("server/protocol/claude-upstream/sdk.d.ts.txt");
+
+    const upstreamInit = sdk.includes("export declare type SDKSystemMessage = {")
+      && sdk.includes("subtype: 'init';");
+    const upstreamStatus = sdk.includes("export declare type SDKStatusMessage = {")
+      && sdk.includes("subtype: 'status';");
+
+    expect(upstreamInit).toBe(true);
+    expect(upstreamStatus).toBe(true);
+
+    expect(adapter).toContain('if (msg.subtype === "init")');
+    expect(adapter).toContain('if (msg.subtype === "status")');
+  });
+});

package/server/claude-session-discovery.test.ts

@@ -0,0 +1,132 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { mkdtempSync, mkdirSync, rmSync, utimesSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { discoverClaudeSessions } from "./claude-session-discovery.js";
+
+const tempRoots: string[] = [];
+
+function createTempProjectsRoot(): string {
+  const root = mkdtempSync(join(tmpdir(), "claude-projects-test-"));
+  tempRoots.push(root);
+  return root;
+}
+
+function writeSessionFile(
+  projectsRoot: string,
+  projectDirName: string,
+  fileName: string,
+  payload: {
+    sessionId: string;
+    cwd: string;
+    gitBranch?: string;
+    slug?: string;
+  },
+  mtimeMs: number,
+) {
+  const projectDir = join(projectsRoot, projectDirName);
+  mkdirSync(projectDir, { recursive: true });
+  const filePath = join(projectDir, fileName);
+  const content = `${JSON.stringify({ type: "file-history-snapshot" })}\n${JSON.stringify(payload)}\n`;
+  writeFileSync(filePath, content, "utf-8");
+  const mtime = new Date(mtimeMs);
+  utimesSync(filePath, mtime, mtime);
+}
+
+afterEach(() => {
+  for (const root of tempRoots.splice(0)) {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+describe("discoverClaudeSessions", () => {
+  it("discovers persisted Claude sessions with cwd/branch metadata", () => {
+    const root = createTempProjectsRoot();
+    // Validate that a normal JSONL session file is parsed into resumable metadata.
+    writeSessionFile(
+      root,
+      "-Users-test-repo",
+      "session-a.jsonl",
+      {
+        sessionId: "session-a",
+        cwd: "/Users/test/repo",
+        gitBranch: "main",
+        slug: "curious-babbage",
+      },
+      1000,
+    );
+
+    const sessions = discoverClaudeSessions({ projectsRoot: root, limit: 10 });
+
+    expect(sessions).toHaveLength(1);
+    expect(sessions[0]).toMatchObject({
+      sessionId: "session-a",
+      cwd: "/Users/test/repo",
+      gitBranch: "main",
+      slug: "curious-babbage",
+    });
+  });
+
+  it("deduplicates by sessionId and keeps the most recently active record", () => {
+    const root = createTempProjectsRoot();
+    // Validate that when the same session appears in multiple files, the newest one wins.
+    writeSessionFile(
+      root,
+      "-Users-test-repo",
+      "session-a-old.jsonl",
+      {
+        sessionId: "session-a",
+        cwd: "/Users/test/repo",
+        gitBranch: "main",
+      },
+      1000,
+    );
+    writeSessionFile(
+      root,
+      "-Users-test-repo",
+      "session-a-new.jsonl",
+      {
+        sessionId: "session-a",
+        cwd: "/Users/test/repo",
+        gitBranch: "feature/new-ui",
+      },
+      2000,
+    );
+
+    const sessions = discoverClaudeSessions({ projectsRoot: root, limit: 10 });
+
+    expect(sessions).toHaveLength(1);
+    expect(sessions[0].gitBranch).toBe("feature/new-ui");
+    expect(sessions[0].lastActivityAt).toBe(2000);
+  });
+
+  it("applies the requested limit after sorting by recency", () => {
+    const root = createTempProjectsRoot();
+    // Validate that callers can bound result size for responsive UI pickers.
+    writeSessionFile(
+      root,
+      "-Users-test-repo",
+      "session-1.jsonl",
+      { sessionId: "session-1", cwd: "/Users/test/repo-1" },
+      1000,
+    );
+    writeSessionFile(
+      root,
+      "-Users-test-repo",
+      "session-2.jsonl",
+      { sessionId: "session-2", cwd: "/Users/test/repo-2" },
+      2000,
+    );
+    writeSessionFile(
+      root,
+      "-Users-test-repo",
+      "session-3.jsonl",
+      { sessionId: "session-3", cwd: "/Users/test/repo-3" },
+      3000,
+    );
+
+    const sessions = discoverClaudeSessions({ projectsRoot: root, limit: 2 });
+
+    expect(sessions.map((s) => s.sessionId)).toEqual(["session-3", "session-2"]);
+  });
+});

package/server/claude-session-discovery.ts

@@ -0,0 +1,157 @@
+import { closeSync, existsSync, openSync, readSync, readdirSync, statSync } from "node:fs";
+import { basename, join } from "node:path";
+import { homedir } from "node:os";
+
+export interface DiscoveredClaudeSession {
+  sessionId: string;
+  cwd: string;
+  gitBranch?: string;
+  slug?: string;
+  lastActivityAt: number;
+  sourceFile: string;
+}
+
+export interface DiscoverClaudeSessionsOptions {
+  limit?: number;
+  projectsRoot?: string;
+}
+
+const DEFAULT_DISCOVERY_LIMIT = 200;
+const MAX_DISCOVERY_LIMIT = 1000;
+const METADATA_SCAN_BYTES = 1024 * 1024; // 1 MiB from file head is enough for first metadata records.
+
+function extractMetadataFromJsonl(
+  filePath: string,
+): Pick<DiscoveredClaudeSession, "sessionId" | "cwd" | "gitBranch" | "slug"> | null {
+  let content = "";
+  const buffer = Buffer.allocUnsafe(METADATA_SCAN_BYTES);
+  let fd: number | null = null;
+  try {
+    fd = openSync(filePath, "r");
+    const bytesRead = readSync(fd, buffer, 0, METADATA_SCAN_BYTES, 0);
+    content = buffer.subarray(0, bytesRead).toString("utf-8");
+  } catch {
+    return null;
+  } finally {
+    if (fd !== null) {
+      try {
+        closeSync(fd);
+      } catch {
+        // no-op
+      }
+    }
+  }
+
+  const lines = content.split("\n");
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith("{")) continue;
+    try {
+      const parsed = JSON.parse(trimmed) as {
+        sessionId?: unknown;
+        cwd?: unknown;
+        gitBranch?: unknown;
+        slug?: unknown;
+      };
+      if (typeof parsed.sessionId !== "string" || typeof parsed.cwd !== "string") {
+        continue;
+      }
+      return {
+        sessionId: parsed.sessionId,
+        cwd: parsed.cwd,
+        gitBranch: typeof parsed.gitBranch === "string" ? parsed.gitBranch : undefined,
+        slug: typeof parsed.slug === "string" ? parsed.slug : undefined,
+      };
+    } catch {
+      // Ignore malformed/truncated line fragments near chunk boundary.
+    }
+  }
+
+  return null;
+}
+
+export function discoverClaudeSessions(
+  options: DiscoverClaudeSessionsOptions = {},
+): DiscoveredClaudeSession[] {
+  const projectsRoot = options.projectsRoot
+    || process.env.CLAUDE_PROJECTS_DIR
+    || join(homedir(), ".claude", "projects");
+  const requestedLimit = Number.isFinite(options.limit) ? Number(options.limit) : DEFAULT_DISCOVERY_LIMIT;
+  const limit = Math.max(1, Math.min(MAX_DISCOVERY_LIMIT, Math.floor(requestedLimit || DEFAULT_DISCOVERY_LIMIT)));
+
+  if (!existsSync(projectsRoot)) return [];
+
+  const sessionFiles: Array<{ filePath: string; mtimeMs: number }> = [];
+  let projectDirs: string[] = [];
+  try {
+    projectDirs = readdirSync(projectsRoot);
+  } catch {
+    return [];
+  }
+
+  for (const projectDir of projectDirs) {
+    const projectPath = join(projectsRoot, projectDir);
+    let stats: ReturnType<typeof statSync>;
+    try {
+      stats = statSync(projectPath);
+    } catch {
+      continue;
+    }
+    if (!stats.isDirectory()) continue;
+
+    let entries: string[] = [];
+    try {
+      entries = readdirSync(projectPath);
+    } catch {
+      continue;
+    }
+
+    for (const entry of entries) {
+      if (!entry.endsWith(".jsonl")) continue;
+      const filePath = join(projectPath, entry);
+      try {
+        const fileStats = statSync(filePath);
+        if (!fileStats.isFile()) continue;
+        sessionFiles.push({
+          filePath,
+          mtimeMs: fileStats.mtimeMs,
+        });
+      } catch {
+        // Skip deleted/corrupt entries.
+      }
+    }
+  }
+
+  sessionFiles.sort((a, b) => b.mtimeMs - a.mtimeMs);
+
+  const uniqueBySessionId = new Map<string, DiscoveredClaudeSession>();
+  for (const candidate of sessionFiles) {
+    if (uniqueBySessionId.size >= limit) break;
+
+    const metadata = extractMetadataFromJsonl(candidate.filePath);
+    if (!metadata) continue;
+
+    const prev = uniqueBySessionId.get(metadata.sessionId);
+    if (prev && prev.lastActivityAt >= candidate.mtimeMs) {
+      continue;
+    }
+
+    uniqueBySessionId.set(metadata.sessionId, {
+      sessionId: metadata.sessionId,
+      cwd: metadata.cwd,
+      gitBranch: metadata.gitBranch,
+      slug: metadata.slug,
+      lastActivityAt: candidate.mtimeMs,
+      sourceFile: candidate.filePath,
+    });
+  }
+
+  return Array.from(uniqueBySessionId.values())
+    .sort((a, b) => b.lastActivityAt - a.lastActivityAt)
+    .slice(0, limit)
+    .map((session) => ({
+      ...session,
+      // Defensive fallback if older records don't carry sessionId in JSONL.
+      sessionId: session.sessionId || basename(session.sourceFile, ".jsonl"),
+    }));
+}

package/server/claude-session-history.test.ts

@@ -0,0 +1,158 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import {
+  clearClaudeSessionHistoryCacheForTests,
+  getClaudeSessionHistoryPage,
+} from "./claude-session-history.js";
+
+const tempRoots: string[] = [];
+
+function createTempProjectsRoot(): string {
+  const root = mkdtempSync(join(tmpdir(), "claude-history-test-"));
+  tempRoots.push(root);
+  return root;
+}
+
+function writeSessionHistoryFile(
+  projectsRoot: string,
+  projectDirName: string,
+  sessionId: string,
+  lines: Array<Record<string, unknown>>,
+) {
+  const projectDir = join(projectsRoot, projectDirName);
+  mkdirSync(projectDir, { recursive: true });
+  const filePath = join(projectDir, `${sessionId}.jsonl`);
+  const content = lines.map((line) => JSON.stringify(line)).join("\n");
+  writeFileSync(filePath, content, "utf-8");
+  return filePath;
+}
+
+afterEach(() => {
+  clearClaudeSessionHistoryCacheForTests();
+  for (const root of tempRoots.splice(0)) {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+describe("getClaudeSessionHistoryPage", () => {
+  it("paginates chronologically while deduping assistant updates by message id", () => {
+    // Validate the loader merges repeated assistant updates into one message
+    // and returns cursor pages from newest backwards.
+    const root = createTempProjectsRoot();
+    const sessionId = "session-a";
+    writeSessionHistoryFile(root, "-Users-test-repo", sessionId, [
+      { type: "file-history-snapshot" },
+      {
+        type: "user",
+        sessionId,
+        uuid: "u-1",
+        timestamp: "2026-02-20T10:00:00.000Z",
+        message: { role: "user", content: "First prompt" },
+      },
+      {
+        type: "assistant",
+        sessionId,
+        uuid: "a-1-1",
+        timestamp: "2026-02-20T10:00:01.000Z",
+        message: {
+          role: "assistant",
+          id: "assistant-1",
+          model: "claude-opus",
+          stop_reason: null,
+          content: [{ type: "thinking", thinking: "Thinking..." }],
+        },
+      },
+      {
+        type: "assistant",
+        sessionId,
+        uuid: "a-1-2",
+        timestamp: "2026-02-20T10:00:02.000Z",
+        message: {
+          role: "assistant",
+          id: "assistant-1",
+          model: "claude-opus",
+          stop_reason: "end_turn",
+          content: [{ type: "text", text: "Merged final answer." }],
+        },
+      },
+      {
+        type: "user",
+        sessionId,
+        uuid: "u-meta",
+        isMeta: true,
+        timestamp: "2026-02-20T10:00:03.000Z",
+        message: { role: "user", content: "<command-name>/exit</command-name>" },
+      },
+      {
+        type: "user",
+        sessionId,
+        uuid: "u-tool-result",
+        timestamp: "2026-02-20T10:00:04.000Z",
+        message: {
+          role: "user",
+          content: [{ type: "tool_result", tool_use_id: "tu-1", content: "tool output" }],
+        },
+      },
+      {
+        type: "user",
+        sessionId,
+        uuid: "u-2",
+        timestamp: "2026-02-20T10:00:05.000Z",
+        message: { role: "user", content: "Second prompt" },
+      },
+      {
+        type: "assistant",
+        sessionId,
+        uuid: "a-2",
+        timestamp: "2026-02-20T10:00:06.000Z",
+        message: {
+          role: "assistant",
+          id: "assistant-2",
+          model: "claude-opus",
+          stop_reason: "tool_use",
+          content: [{ type: "tool_use", id: "tool-1", name: "Read", input: { file_path: "README.md" } }],
+        },
+      },
+    ]);
+
+    const latestPage = getClaudeSessionHistoryPage({
+      sessionId,
+      projectsRoot: root,
+      limit: 2,
+      cursor: 0,
+    });
+
+    expect(latestPage).not.toBeNull();
+    expect(latestPage?.totalMessages).toBe(4);
+    expect(latestPage?.hasMore).toBe(true);
+    expect(latestPage?.nextCursor).toBe(2);
+    expect(latestPage?.messages.map((msg) => msg.role)).toEqual(["user", "assistant"]);
+    expect(latestPage?.messages[0].content).toBe("Second prompt");
+
+    const olderPage = getClaudeSessionHistoryPage({
+      sessionId,
+      projectsRoot: root,
+      limit: 2,
+      cursor: latestPage?.nextCursor,
+    });
+
+    expect(olderPage).not.toBeNull();
+    expect(olderPage?.hasMore).toBe(false);
+    expect(olderPage?.messages.map((msg) => msg.role)).toEqual(["user", "assistant"]);
+    expect(olderPage?.messages[1].content).toContain("Merged final answer.");
+    expect(olderPage?.messages[1].content).toContain("Thinking...");
+  });
+
+  it("returns null when the session file cannot be found", () => {
+    // Validate a clean null response for unknown sessions so routes can return 404.
+    const root = createTempProjectsRoot();
+    const page = getClaudeSessionHistoryPage({
+      sessionId: "missing-session",
+      projectsRoot: root,
+      limit: 10,
+    });
+    expect(page).toBeNull();
+  });
+});