failproofai 0.0.11-beta.1 → 0.0.11-beta.3

package/.next/standalone/lib/auth/api-server-client.ts

@@ -0,0 +1,281 @@
+/**
+ * Low-level HTTP client for the FailproofAI api-server's /v0/auth/* endpoints.
+ *
+ * Shared by both the CLI (failproofai auth ...) and the dashboard's Next.js
+ * API route proxies. Has no filesystem access — token persistence lives in
+ * `./auth-store.ts`.
+ *
+ * The base URL is resolved from FAILPROOF_API_URL (preferred) or the legacy
+ * FAILPROOFAI_API_URL, falling back to the hosted api-server. Local-dev
+ * contributors should set FAILPROOF_API_URL=http://localhost:8080 (or
+ * whatever port their local api-server uses) in `.env.local`.
+ */
+
+import { trackEvent } from "../telemetry";
+import { isAbortError } from "../fetch-with-timeout";
+
+export const DEFAULT_API_BASE = "https://api.befailproof.ai";
+
+export function getApiBase(): string {
+  const raw =
+    process.env.FAILPROOF_API_URL ??
+    process.env.FAILPROOFAI_API_URL ??
+    DEFAULT_API_BASE;
+  return raw.replace(/\/+$/, "");
+}
+
+export class AuthApiError extends Error {
+  readonly status: number;
+  readonly code: string;
+  readonly retryAfterSecs?: number;
+  constructor(status: number, code: string, message: string, retryAfterSecs?: number) {
+    super(message);
+    this.status = status;
+    this.code = code;
+    this.retryAfterSecs = retryAfterSecs;
+    this.name = "AuthApiError";
+  }
+}
+
+export interface LoginRequestResponse {
+  status: "code_sent";
+  expires_in: number;
+  resend_available_in: number;
+}
+
+export interface UserView {
+  id: string;
+  email: string;
+}
+
+export interface TokenResponse {
+  token_type: "Bearer";
+  access_token: string;
+  access_expires_in: number;
+  refresh_token: string;
+  refresh_expires_in: number;
+  user: UserView;
+}
+
+export interface RefreshResponse {
+  token_type: "Bearer";
+  access_token: string;
+  access_expires_in: number;
+  refresh_token: string;
+  refresh_expires_in: number;
+}
+
+export interface MeResponse {
+  id: string;
+  email: string;
+  status: string;
+  created_at: string;
+}
+
+interface ServerErrorBody {
+  // The docs describe `{ code, message }`; the live Rust server returns
+  // `{ success: false, code, detail }`. We tolerate either.
+  code?: string;
+  message?: string;
+  detail?: string;
+  retry_after_secs?: number;
+}
+
+async function parseError(res: Response): Promise<AuthApiError> {
+  let body: ServerErrorBody = {};
+  try {
+    body = (await res.json()) as ServerErrorBody;
+  } catch {
+    // body might be empty or non-JSON
+  }
+  const code = body.code ?? `http_${res.status}`;
+  const message = body.message ?? body.detail ?? res.statusText ?? "request failed";
+  let retryAfterSecs = body.retry_after_secs;
+  if (retryAfterSecs === undefined) {
+    const h = res.headers.get("retry-after");
+    if (h) {
+      const n = Number(h);
+      if (Number.isFinite(n)) retryAfterSecs = n;
+    }
+  }
+  // Clamp to a sane range: a misbehaving (or hostile) api-server could
+  // return `-3600` or `1e20` and our UI would render "wait 1e20s" or
+  // backoff loops would fire immediately on negatives. 24h is the longest
+  // wait the dashboard/CLI is willing to surface as a literal duration.
+  if (retryAfterSecs !== undefined) {
+    retryAfterSecs = Math.max(0, Math.min(86400, retryAfterSecs));
+  }
+  return new AuthApiError(res.status, code, message, retryAfterSecs);
+}
+
+/** Hard cap on every auth/reminder HTTP call. Without this, a wedged DNS
+ *  resolver or a hung server keeps the CLI / dashboard route stuck forever. */
+const REQUEST_TIMEOUT_MS = 10_000;
+
+function timeoutSignal(extra?: AbortSignal): AbortSignal {
+  const t = AbortSignal.timeout(REQUEST_TIMEOUT_MS);
+  if (!extra) return t;
+  // Compose so an externally-cancelled caller still aborts. Prefer the
+  // native `AbortSignal.any` (Node 20.3+, Bun 1.0.27+); fall back to a
+  // hand-rolled controller for older runtimes — without this fallback
+  // an `extra` signal would be silently dropped.
+  const anyFn = (AbortSignal as unknown as { any?: (s: AbortSignal[]) => AbortSignal }).any;
+  if (anyFn) return anyFn([t, extra]);
+  const composed = new AbortController();
+  const onAbort = (s: AbortSignal) => composed.abort(s.reason);
+  if (t.aborted) onAbort(t);
+  else t.addEventListener("abort", () => onAbort(t), { once: true });
+  if (extra.aborted) onAbort(extra);
+  else extra.addEventListener("abort", () => onAbort(extra), { once: true });
+  return composed.signal;
+}
+
+function pathFromUrl(url: string): string {
+  try {
+    return new URL(url).pathname;
+  } catch {
+    return url;
+  }
+}
+
+async function fetchWithTimeout(url: string, init: RequestInit): Promise<Response> {
+  try {
+    return await fetch(url, { ...init, signal: timeoutSignal(init.signal ?? undefined) });
+  } catch (err) {
+    const isTimeout = isAbortError(err);
+    // Low-cardinality "api-server is down" counter. We only attach the
+    // request path (not the full URL) and a coarse kind so it stays a
+    // cheap signal in PostHog. No-ops on the CLI side when telemetry
+    // has not been initialised.
+    trackEvent("api_server_unreachable", {
+      kind: isTimeout ? "timeout" : "network",
+      path: pathFromUrl(url),
+      method: typeof init.method === "string" ? init.method : "GET",
+    });
+    if (isTimeout) {
+      throw new AuthApiError(
+        0,
+        "timeout",
+        `request to ${url} timed out after ${REQUEST_TIMEOUT_MS}ms`,
+      );
+    }
+    throw err;
+  }
+}
+
+async function postJson<T>(path: string, body: unknown, init?: { accessToken?: string }): Promise<T> {
+  const headers: Record<string, string> = { "content-type": "application/json" };
+  if (init?.accessToken) headers["authorization"] = `Bearer ${init.accessToken}`;
+  const res = await fetchWithTimeout(`${getApiBase()}${path}`, {
+    method: "POST",
+    headers,
+    body: JSON.stringify(body),
+  });
+  if (res.status === 204) return undefined as T;
+  if (!res.ok) throw await parseError(res);
+  return (await res.json()) as T;
+}
+
+async function getJson<T>(path: string, accessToken: string): Promise<T> {
+  const res = await fetchWithTimeout(`${getApiBase()}${path}`, {
+    method: "GET",
+    headers: { authorization: `Bearer ${accessToken}` },
+  });
+  if (!res.ok) throw await parseError(res);
+  return (await res.json()) as T;
+}
+
+export async function requestLoginCode(email: string): Promise<LoginRequestResponse> {
+  return postJson<LoginRequestResponse>("/v0/auth/login/request", { email });
+}
+
+export async function verifyLoginCode(email: string, code: string): Promise<TokenResponse> {
+  return postJson<TokenResponse>("/v0/auth/login/verify", { email, code });
+}
+
+export async function refreshAccessToken(refreshToken: string): Promise<RefreshResponse> {
+  return postJson<RefreshResponse>("/v0/auth/token/refresh", {
+    refresh_token: refreshToken,
+  });
+}
+
+export async function logoutSession(accessToken: string, refreshToken: string): Promise<void> {
+  await postJson<void>(
+    "/v0/auth/logout",
+    { refresh_token: refreshToken },
+    { accessToken },
+  );
+}
+
+export async function fetchMe(accessToken: string): Promise<MeResponse> {
+  return getJson<MeResponse>("/v0/auth/me", accessToken);
+}
+
+export interface ServerReminder {
+  user_id: string;
+  email: string;
+  fire_at: number; // unix seconds
+  set_at: number;  // unix seconds
+}
+
+export async function scheduleReminder(
+  accessToken: string,
+  body: { in_days?: number; at?: number },
+): Promise<ServerReminder> {
+  const res = await postJson<{ reminder: ServerReminder }>(
+    "/v0/reminders",
+    body,
+    { accessToken },
+  );
+  return res.reminder;
+}
+
+export async function cancelReminder(accessToken: string): Promise<void> {
+  const res = await fetchWithTimeout(`${getApiBase()}/v0/reminders`, {
+    method: "DELETE",
+    headers: { authorization: `Bearer ${accessToken}` },
+  });
+  if (res.status === 204 || res.ok) return;
+  throw await parseError(res);
+}
+
+interface JwtClaims {
+  sub: string;
+  email: string;
+  iss?: string;
+  aud?: string;
+  iat?: number;
+  exp: number;
+  token_type?: string;
+}
+
+/**
+ * Decode the JWT payload without verifying the signature. Safe for client-side
+ * reading (sub, email, exp). Returns null if the token is malformed.
+ *
+ * Strictly validates base64url before decoding: `Buffer.from(s, 'base64url')`
+ * silently truncates on illegal characters (`+`, `/`, whitespace, embedded
+ * NULs) rather than throwing, and the truncated bytes can happen to parse as
+ * JSON with a numeric `exp` field, producing synthetic "valid" claims from a
+ * corrupted token.
+ */
+const BASE64URL_RE = /^[A-Za-z0-9_-]+={0,2}$/;
+
+export function decodeJwt(token: string): JwtClaims | null {
+  try {
+    const parts = token.split(".");
+    if (parts.length !== 3) return null;
+    // Header and payload must both be syntactically valid base64url. Empty
+    // segments are also rejected (Buffer.from("","base64url") would return
+    // an empty buffer that JSON.parse correctly throws on, but rejecting
+    // upfront is cheaper and clearer).
+    if (!BASE64URL_RE.test(parts[0])) return null;
+    if (!BASE64URL_RE.test(parts[1])) return null;
+    const json = Buffer.from(parts[1], "base64url").toString("utf8");
+    const parsed = JSON.parse(json) as JwtClaims;
+    if (typeof parsed.exp !== "number") return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}

package/.next/standalone/lib/auth/auth-store.ts

@@ -0,0 +1,250 @@
+/**
+ * Persistence layer for the FailproofAI auth.json file.
+ *
+ * Tokens live at ~/.failproofai/auth.json with mode 0600. The dashboard's
+ * Next.js API routes and the CLI both read/write through here so the user's
+ * session survives across `failproofai` (dashboard) and `failproofai auth`
+ * (CLI) invocations.
+ */
+
+import { existsSync, readFileSync, rmSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import { writeJsonAtomically } from "../atomic-write";
+import {
+  AuthApiError,
+  decodeJwt,
+  fetchMe,
+  refreshAccessToken,
+  type MeResponse,
+} from "./api-server-client";
+
+export interface StoredAuth {
+  access_token: string;
+  refresh_token: string;
+  access_expires_at: number; // unix seconds
+  refresh_expires_at: number; // unix seconds (best-effort; not strictly verified server-side)
+  user: { id: string; email: string };
+}
+
+export function getAuthDir(): string {
+  const override = process.env.FAILPROOFAI_AUTH_DIR;
+  if (override) return override;
+  return join(homedir(), ".failproofai");
+}
+
+export function getAuthFilePath(): string {
+  return join(getAuthDir(), "auth.json");
+}
+
+/** Location of the persisted re-audit reminder (separate from auth.json so
+ *  the reminder survives unrelated session refreshes). */
+export function getReminderFilePath(): string {
+  return join(getAuthDir(), "next-audit.json");
+}
+
+export interface StoredReminder {
+  /** Unix seconds. */
+  next_audit_at: number;
+  /** Email the reminder was set for. Used to invalidate the reminder if the
+   *  active session belongs to a different user. */
+  user_email: string;
+  /** Unix seconds. */
+  set_at: number;
+}
+
+export function readReminder(): StoredReminder | null {
+  const p = getReminderFilePath();
+  if (!existsSync(p)) return null;
+  try {
+    const raw = readFileSync(p, "utf-8");
+    const parsed = JSON.parse(raw) as Partial<StoredReminder>;
+    if (
+      typeof parsed.next_audit_at !== "number" ||
+      typeof parsed.user_email !== "string" ||
+      typeof parsed.set_at !== "number"
+    ) {
+      return null;
+    }
+    return {
+      next_audit_at: parsed.next_audit_at,
+      user_email: parsed.user_email,
+      set_at: parsed.set_at,
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function writeReminder(reminder: StoredReminder): void {
+  writeJsonAtomically(getReminderFilePath(), reminder);
+}
+
+export function deleteReminder(): void {
+  const p = getReminderFilePath();
+  if (existsSync(p)) rmSync(p, { force: true });
+}
+
+export function readAuth(): StoredAuth | null {
+  const p = getAuthFilePath();
+  if (!existsSync(p)) return null;
+  try {
+    const raw = readFileSync(p, "utf-8");
+    const parsed = JSON.parse(raw) as Partial<StoredAuth>;
+    if (
+      typeof parsed.access_token !== "string" ||
+      typeof parsed.refresh_token !== "string" ||
+      typeof parsed.access_expires_at !== "number" ||
+      typeof parsed.user !== "object" ||
+      !parsed.user ||
+      typeof (parsed.user as { id?: unknown }).id !== "string" ||
+      typeof (parsed.user as { email?: unknown }).email !== "string"
+    ) {
+      return null;
+    }
+    return {
+      access_token: parsed.access_token,
+      refresh_token: parsed.refresh_token,
+      access_expires_at: parsed.access_expires_at,
+      refresh_expires_at:
+        typeof parsed.refresh_expires_at === "number"
+          ? parsed.refresh_expires_at
+          : parsed.access_expires_at,
+      user: {
+        id: (parsed.user as { id: string }).id,
+        email: (parsed.user as { email: string }).email,
+      },
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function writeAuth(auth: StoredAuth): void {
+  writeJsonAtomically(getAuthFilePath(), auth);
+}
+
+export function deleteAuth(): void {
+  const p = getAuthFilePath();
+  if (existsSync(p)) rmSync(p, { force: true });
+}
+
+/** Convert verify/refresh response into the on-disk shape. */
+export function authFromTokenResponse(token: {
+  access_token: string;
+  refresh_token: string;
+  access_expires_in: number;
+  refresh_expires_in: number;
+  user?: { id: string; email: string };
+}, existingUser?: { id: string; email: string }): StoredAuth {
+  const now = Math.floor(Date.now() / 1000);
+  const user = token.user ?? existingUser;
+  if (!user) {
+    throw new Error("authFromTokenResponse: missing user identity");
+  }
+  return {
+    access_token: token.access_token,
+    refresh_token: token.refresh_token,
+    access_expires_at: now + token.access_expires_in,
+    refresh_expires_at: now + token.refresh_expires_in,
+    user,
+  };
+}
+
+/**
+ * Return a fresh access token, refreshing in-place if the current one is
+ * within the leeway window of expiry. Mutates auth.json on disk on success.
+ * Returns null if the stored session is gone or the refresh failed (caller
+ * should treat that as "logged out").
+ */
+const REFRESH_LEEWAY_SECS = 60;
+
+/**
+ * In-flight refresh dedup. Without this, two concurrent callers (e.g.
+ * the dashboard's `/api/auth/status` poll and a `/api/auth/reminder`
+ * POST in flight) both observe the same expired access token, both call
+ * `refreshAccessToken(auth.refresh_token)` with the same refresh token,
+ * and the api-server treats the second call as token-replay and revokes
+ * every session for that user — a silent logout. Keying on the refresh
+ * token avoids accidentally sharing a refresh across logins/logouts in
+ * the same process.
+ */
+const inFlightRefreshes = new Map<string, Promise<StoredAuth>>();
+
+async function dedupedRefresh(auth: StoredAuth): Promise<StoredAuth> {
+  const existing = inFlightRefreshes.get(auth.refresh_token);
+  if (existing) return existing;
+  const p = (async () => {
+    const refreshed = await refreshAccessToken(auth.refresh_token);
+    const next = authFromTokenResponse(refreshed, auth.user);
+    writeAuth(next);
+    return next;
+  })();
+  inFlightRefreshes.set(auth.refresh_token, p);
+  try {
+    return await p;
+  } finally {
+    inFlightRefreshes.delete(auth.refresh_token);
+  }
+}
+
+export async function getValidAccessToken(): Promise<StoredAuth | null> {
+  const auth = readAuth();
+  if (!auth) return null;
+  const now = Math.floor(Date.now() / 1000);
+  if (auth.access_expires_at - now > REFRESH_LEEWAY_SECS) return auth;
+  // Either expired or close to expiring — try to refresh.
+  try {
+    return await dedupedRefresh(auth);
+  } catch (err) {
+    if (err instanceof AuthApiError && err.status === 401) {
+      // Session unrecoverable — wipe.
+      deleteAuth();
+      return null;
+    }
+    // Network errors etc — surface to caller as null so the UI can recover.
+    return null;
+  }
+}
+
+/**
+ * Verify with the server that the stored access token is still valid.
+ * Refreshes once on 401. Returns the live /me response and the (possibly
+ * refreshed) stored auth, or null if the session can't be recovered.
+ */
+export async function whoAmI(): Promise<{ me: MeResponse; auth: StoredAuth } | null> {
+  const fresh = await getValidAccessToken();
+  if (!fresh) return null;
+  try {
+    const me = await fetchMe(fresh.access_token);
+    return { me, auth: fresh };
+  } catch (err) {
+    if (err instanceof AuthApiError && err.status === 401) {
+      // Maybe the leeway wasn't enough — try one more refresh and retry.
+      const reread = readAuth();
+      if (!reread) return null;
+      try {
+        const next = await dedupedRefresh(reread);
+        const me = await fetchMe(next.access_token);
+        return { me, auth: next };
+      } catch (retryErr) {
+        // Symmetry with `getValidAccessToken`: wipe the session only on an
+        // unambiguous 401. A transient timeout/5xx during the retry-fetchMe
+        // must NOT throw away the freshly-written valid tokens, otherwise a
+        // brief api-server hiccup silently logs the user out.
+        if (retryErr instanceof AuthApiError && retryErr.status === 401) {
+          deleteAuth();
+        }
+        return null;
+      }
+    }
+    return null;
+  }
+}
+
+/** Reads the JWT exp claim for diagnostics. */
+export function readAccessExpiry(auth: StoredAuth): number | null {
+  const claims = decodeJwt(auth.access_token);
+  return claims?.exp ?? null;
+}

package/.next/standalone/lib/claude-sessions.ts

@@ -0,0 +1,181 @@
+/**
+ * Claude Code session transcript discovery helpers.
+ *
+ * Claude stores transcripts at:
+ *   <CLAUDE_PROJECTS_PATH>/<encoded-cwd>/<sessionId>.jsonl
+ *
+ * Subagent transcripts (when a session spawned subagents) live alongside:
+ *   <CLAUDE_PROJECTS_PATH>/<encoded-cwd>/<sessionId>/subagents/<agentId>.jsonl
+ *
+ * The parser for these files lives in `lib/log-entries.ts` (`parseLogContent`,
+ * `parseSessionLog`). This module exposes discovery only — the audit pipeline
+ * and any future Claude-specific tool walk the directory layout via these
+ * helpers instead of re-implementing the path conventions.
+ *
+ * Mirrors the shape of `lib/cursor-sessions.ts` for parity across CLIs.
+ */
+import { readdirSync, statSync, existsSync } from "node:fs";
+import { join, basename } from "node:path";
+import { getClaudeProjectsPath, decodeFolderName } from "./paths";
+
+const UUID_RE = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i;
+
+export interface ClaudeProjectFolder {
+  /** Encoded folder name on disk (e.g. "-home-user-project"). */
+  name: string;
+  /** Decoded filesystem path (e.g. "/home/user/project"). */
+  cwd: string;
+  /** Absolute path of the encoded folder. */
+  path: string;
+}
+
+export interface ClaudeTranscriptFile {
+  projectName: string;
+  /** Decoded cwd of the project. */
+  cwd: string;
+  sessionId: string;
+  /** Absolute path of `<sessionId>.jsonl`. */
+  transcriptPath: string;
+  mtimeMs: number;
+  sizeBytes: number;
+  /** True when this is a subagent transcript spawned from a parent session. */
+  isSubagent: boolean;
+}
+
+/** Returns the Claude projects root, honoring the CLAUDE_PROJECTS_PATH env var. */
+export function getClaudeProjectsRoot(): string {
+  return getClaudeProjectsPath();
+}
+
+/** Lists all Claude project folders (one per encoded cwd). Returns [] if the
+ *  projects root doesn't exist. Filenames that don't look like Claude project
+ *  encodings are still included — encoding is permissive. */
+export function listClaudeProjects(): ClaudeProjectFolder[] {
+  const root = getClaudeProjectsRoot();
+  let entries: import("node:fs").Dirent[];
+  try {
+    entries = readdirSync(root, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries
+    .filter((e) => e.isDirectory())
+    .map((e) => ({
+      name: e.name,
+      cwd: decodeFolderName(e.name),
+      path: join(root, e.name),
+    }));
+}
+
+/** Lists every JSONL transcript under one Claude project folder, including
+ *  subagent transcripts under `<sessionId>/subagents/`. Returns [] on missing
+ *  or unreadable paths. */
+export function listClaudeTranscripts(project: ClaudeProjectFolder): ClaudeTranscriptFile[] {
+  const out: ClaudeTranscriptFile[] = [];
+  let entries: import("node:fs").Dirent[];
+  try {
+    entries = readdirSync(project.path, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+
+  for (const entry of entries) {
+    if (entry.isFile() && entry.name.endsWith(".jsonl")) {
+      const sessionId = entry.name.slice(0, -".jsonl".length);
+      if (!UUID_RE.test(sessionId)) continue;
+      const transcriptPath = join(project.path, entry.name);
+      try {
+        const s = statSync(transcriptPath);
+        out.push({
+          projectName: project.name,
+          cwd: project.cwd,
+          sessionId,
+          transcriptPath,
+          mtimeMs: s.mtimeMs,
+          sizeBytes: s.size,
+          isSubagent: false,
+        });
+      } catch {
+        // unreadable — skip
+      }
+    } else if (entry.isDirectory() && UUID_RE.test(entry.name)) {
+      // Subagent transcripts at <sessionId>/subagents/<agentId>.jsonl
+      const subDir = join(project.path, entry.name, "subagents");
+      if (!existsSync(subDir)) continue;
+      let subEntries: import("node:fs").Dirent[];
+      try {
+        subEntries = readdirSync(subDir, { withFileTypes: true });
+      } catch {
+        continue;
+      }
+      for (const sub of subEntries) {
+        if (!sub.isFile() || !sub.name.endsWith(".jsonl")) continue;
+        const agentId = sub.name.slice(0, -".jsonl".length);
+        const transcriptPath = join(subDir, sub.name);
+        try {
+          const s = statSync(transcriptPath);
+          out.push({
+            projectName: project.name,
+            cwd: project.cwd,
+            sessionId: agentId,
+            transcriptPath,
+            mtimeMs: s.mtimeMs,
+            sizeBytes: s.size,
+            isSubagent: true,
+          });
+        } catch {
+          // unreadable — skip
+        }
+      }
+    }
+  }
+
+  return out;
+}
+
+/** Convenience: locate one Claude transcript file by session ID across all
+ *  project folders. Returns null if not found. */
+export function findClaudeTranscript(sessionId: string): string | null {
+  if (!UUID_RE.test(sessionId)) return null;
+  for (const project of listClaudeProjects()) {
+    const candidate = join(project.path, `${sessionId}.jsonl`);
+    if (existsSync(candidate)) return candidate;
+    // Subagent fallback
+    let entries: import("node:fs").Dirent[];
+    try {
+      entries = readdirSync(project.path, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory() || !UUID_RE.test(entry.name)) continue;
+      const subCandidate = join(project.path, entry.name, "subagents", `${sessionId}.jsonl`);
+      if (existsSync(subCandidate)) return subCandidate;
+    }
+  }
+  return null;
+}
+
+/** For tests: list all session IDs across all projects. */
+export function _listAllSessionIds(): string[] {
+  const ids: string[] = [];
+  for (const project of listClaudeProjects()) {
+    for (const t of listClaudeTranscripts(project)) {
+      ids.push(t.sessionId);
+    }
+  }
+  return ids;
+}
+
+/** For tests: stat one transcript file. */
+export function _statTranscript(path: string): { mtimeMs: number; sizeBytes: number } | null {
+  try {
+    const s = statSync(path);
+    return { mtimeMs: s.mtimeMs, sizeBytes: s.size };
+  } catch {
+    return null;
+  }
+}
+
+/** Re-export for callers that want to construct paths from a basename. */
+export { basename };