codex-work-receipt 0.9.0 → 0.10.1

package/src/core/range.mjs

@@ -4,6 +4,7 @@ export const RECEIPT_SCOPES = new Set([
   "latest",
   "session",
   "last-hours",
+  "custom-range",
   "today",
   "last-7-days",
   "this-week",
@@ -14,6 +15,8 @@ const SCOPE_ALIASES = new Map([
   ["session", "session"],
   ["hours", "last-hours"],
   ["last-hours", "last-hours"],
+  ["custom", "custom-range"],
+  ["custom-range", "custom-range"],
   ["today", "today"],
   ["7d", "last-7-days"],
   ["last-7-days", "last-7-days"],
@@ -47,7 +50,125 @@ function floorToMinute(value) {
   return date;
 }
 
-export function resolveRange(scope, timezone, now = new Date(), sessionId = null, hours = null) {
+function parseDateParts(value) {
+  const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(String(value || "").trim());
+  if (!match) return null;
+  return { year: Number(match[1]), month: Number(match[2]), day: Number(match[3]) };
+}
+
+function parseDateTimeParts(value) {
+  const match = /^(\d{4})-(\d{2})-(\d{2})[T\s](\d{2}):(\d{2})$/.exec(String(value || "").trim());
+  if (!match) return null;
+  return {
+    year: Number(match[1]),
+    month: Number(match[2]),
+    day: Number(match[3]),
+    hour: Number(match[4]),
+    minute: Number(match[5]),
+  };
+}
+
+function validCalendarParts(parts, includeTime = false) {
+  if (!parts) return false;
+  const probe = new Date(Date.UTC(parts.year, parts.month - 1, parts.day));
+  if (
+    probe.getUTCFullYear() !== parts.year ||
+    probe.getUTCMonth() + 1 !== parts.month ||
+    probe.getUTCDate() !== parts.day
+  ) return false;
+  if (!includeTime) return true;
+  return parts.hour >= 0 && parts.hour <= 23 && parts.minute >= 0 && parts.minute <= 59;
+}
+
+function zonedParts(date, timezone) {
+  const parts = new Intl.DateTimeFormat("en-CA", {
+    timeZone: timezone,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+    hourCycle: "h23",
+  }).formatToParts(date);
+  return Object.fromEntries(parts.filter((part) => part.type !== "literal").map((part) => [part.type, Number(part.value)]));
+}
+
+function zonedDateTime(parts, timezone) {
+  const target = Date.UTC(parts.year, parts.month - 1, parts.day, parts.hour || 0, parts.minute || 0, 0, 0);
+  let result = new Date(target);
+  for (let index = 0; index < 3; index += 1) {
+    const displayed = zonedParts(result, timezone);
+    const displayedUtc = Date.UTC(
+      displayed.year,
+      displayed.month - 1,
+      displayed.day,
+      displayed.hour,
+      displayed.minute,
+      displayed.second,
+    );
+    result = new Date(result.getTime() + target - displayedUtc);
+  }
+  const displayed = zonedParts(result, timezone);
+  if (
+    displayed.year !== parts.year ||
+    displayed.month !== parts.month ||
+    displayed.day !== parts.day ||
+    displayed.hour !== (parts.hour || 0) ||
+    displayed.minute !== (parts.minute || 0)
+  ) throw new Error("自定义时间在所选时区中不存在，请检查夏令时切换或输入格式");
+  return result;
+}
+
+export function parseCustomRange(from, to, timezone) {
+  const fromDate = parseDateParts(from);
+  const toDate = parseDateParts(to);
+  const fromDateTime = parseDateTimeParts(from);
+  const toDateTime = parseDateTimeParts(to);
+
+  if (fromDate && toDate) {
+    if (!validCalendarParts(fromDate) || !validCalendarParts(toDate)) throw new Error("自定义日期无效");
+    const startDate = String(from).trim();
+    const endDate = String(to).trim();
+    if (startDate > endDate) throw new Error("自定义区间的开始日期不能晚于结束日期");
+    const nextDate = shiftDateKey(endDate, 1);
+    return {
+      boundaryKind: "calendar-days",
+      startDate,
+      endDate,
+      startAt: zonedDateTime({ ...fromDate, hour: 0, minute: 0 }, timezone),
+      endAt: zonedDateTime({ ...parseDateParts(nextDate), hour: 0, minute: 0 }, timezone),
+    };
+  }
+
+  if (fromDateTime && toDateTime) {
+    if (!validCalendarParts(fromDateTime, true) || !validCalendarParts(toDateTime, true)) {
+      throw new Error("自定义时间无效");
+    }
+    const startAt = zonedDateTime(fromDateTime, timezone);
+    const endAt = zonedDateTime(toDateTime, timezone);
+    if (startAt >= endAt) throw new Error("自定义区间的开始时间必须早于结束时间");
+    return {
+      boundaryKind: "exact-time",
+      startDate: dateKey(startAt, timezone),
+      endDate: dateKey(endAt, timezone),
+      startAt,
+      endAt,
+    };
+  }
+
+  throw new Error("自定义区间请统一使用 YYYY-MM-DD，或 YYYY-MM-DDTHH:mm 格式");
+}
+
+export function resolveRange(
+  scope,
+  timezone,
+  now = new Date(),
+  sessionId = null,
+  hours = null,
+  customRange = null,
+  projectId = null,
+) {
   const normalizedScope = normalizeScope(scope);
   if (!normalizedScope || !RECEIPT_SCOPES.has(normalizedScope)) {
     throw new Error(`不支持的统计范围：${scope}`);
@@ -59,6 +180,7 @@ export function resolveRange(scope, timezone, now = new Date(), sessionId = null
   let startAt = null;
   let endAt = null;
   let windowHours = null;
+  let boundaryKind = null;
 
   if (normalizedScope === "last-hours") {
     windowHours = Number(hours ?? 3);
@@ -69,6 +191,15 @@ export function resolveRange(scope, timezone, now = new Date(), sessionId = null
     startAt = new Date(endAt.getTime() - windowHours * 60 * 60 * 1000);
     startDate = dateKey(startAt, timezone);
     endDate = dateKey(endAt, timezone);
+    boundaryKind = "exact-time";
+  } else if (normalizedScope === "custom-range") {
+    if (!customRange?.from || !customRange?.to) throw new Error("自定义区间需要开始和结束时间");
+    const parsed = parseCustomRange(customRange.from, customRange.to, timezone);
+    startDate = parsed.startDate;
+    endDate = parsed.endDate;
+    startAt = parsed.startAt;
+    endAt = parsed.endAt;
+    boundaryKind = parsed.boundaryKind;
   } else if (normalizedScope === "today") {
     startDate = targetDate;
     endDate = targetDate;
@@ -90,23 +221,27 @@ export function resolveRange(scope, timezone, now = new Date(), sessionId = null
     endAt,
     hours: windowHours,
     sessionId: sessionId || null,
+    boundaryKind,
+    projectId: projectId || null,
   };
 }
 
-export function isCalendarScope(scope) {
-  return scope === "today" || scope === "last-7-days" || scope === "this-week";
+export function isCalendarRange(range) {
+  return range?.scope === "today" || range?.scope === "last-7-days" || range?.scope === "this-week"
+    || (range?.scope === "custom-range" && range?.boundaryKind === "calendar-days");
 }
 
-export function isTimeWindowScope(scope) {
-  return scope === "last-hours";
+export function isTimeWindowRange(range) {
+  return range?.scope === "last-hours"
+    || (range?.scope === "custom-range" && range?.boundaryKind === "exact-time");
 }
 
 export function isDateInRange(date, range) {
   if (!date) return false;
-  if (isTimeWindowScope(range.scope)) {
-    return date >= range.startAt && date <= range.endAt;
+  if (isTimeWindowRange(range)) {
+    return date >= range.startAt && (range.scope === "custom-range" ? date < range.endAt : date <= range.endAt);
   }
-  if (!isCalendarScope(range.scope)) return true;
+  if (!isCalendarRange(range)) return true;
   const key = dateKey(date, range.timezone);
   return key >= range.startDate && key <= range.endDate;
 }
@@ -145,6 +280,18 @@ export function outputSlugForRange(range, receiptId = "") {
       : endAt.toISOString().replace(/[-:]/g, "").slice(0, 13);
     return `last-${Number(range?.hours || 3)}-hours-${safeSlugSegment(endStamp, "window")}`;
   }
+  if (scope === "custom-range") {
+    if (range?.boundaryKind === "calendar-days") {
+      const dateSpan = startDate === endDate ? endDate : `${startDate}-to-${endDate}`;
+      return `custom-${safeSlugSegment(dateSpan, "range")}`;
+    }
+    const startAt = range?.startAt instanceof Date ? range.startAt : new Date(range?.startAt || 0);
+    const endAt = range?.endAt instanceof Date ? range.endAt : new Date(range?.endAt || 0);
+    const stamp = (value) => Number.isNaN(value.getTime())
+      ? "time"
+      : value.toISOString().replace(/[-:]/g, "").slice(0, 13);
+    return `custom-${safeSlugSegment(`${stamp(startAt)}-to-${stamp(endAt)}`, "range")}`;
+  }
   if (scope === "last-7-days" || scope === "this-week") {
     const dateSpan = startDate === endDate ? endDate : `${startDate}-to-${endDate}`;
     return `${scope}-${safeSlugSegment(dateSpan, scope)}`;

package/src/core/receipt-record.mjs

@@ -52,7 +52,8 @@ function fingerprintSessionIds(sessionIds) {
 export function buildReceiptRecord(metrics, defaultTheme = "classic", locale = DEFAULT_LOCALE, canonical = {}) {
   const sessionFingerprint = fingerprintSessionIds(metrics.sessionIds);
   const logicalKey = buildLogicalReceiptKey(metrics);
-  const summaryOnly = metrics.mode === "last-hours";
+  const summaryOnly = metrics.mode === "last-hours"
+    || (metrics.mode === "custom-range" && metrics.boundaryKind === "exact-time");
   const insights = metrics.insights || fallbackInsights(metrics);
   const schemaVersion = summaryOnly ? 1 : SCHEMA_VERSION;
   const sourceVersion = summaryOnly ? "cwr1" : SOURCE_VERSION;
@@ -72,6 +73,8 @@ export function buildReceiptRecord(metrics, defaultTheme = "classic", locale = D
     rangeEndDate: metrics.rangeEndDate,
     windowStartAt: metrics.windowStartAt?.toISOString() || null,
     windowEndAt: metrics.windowEndAt?.toISOString() || null,
+    boundaryKind: metrics.boundaryKind || null,
+    projectFiltered: Boolean(metrics.projectId),
   });
   const workProfileId = metrics.workProfileId || "temporary-hire";
   const workProfile = getWorkProfileCopy(workProfileId, locale);
@@ -108,6 +111,8 @@ export function buildReceiptRecord(metrics, defaultTheme = "classic", locale = D
       version: sourceVersion,
       scope: metrics.mode,
       hours: metrics.windowHours || null,
+      range_kind: metrics.boundaryKind || null,
+      filter_kind: metrics.projectId ? "project" : null,
       collector_version: COLLECTOR_VERSION,
       logical_key: logicalKey,
       session_fingerprint: sessionFingerprint,

package/src/core/selector.mjs

@@ -1,5 +1,7 @@
 import { createInterface } from "node:readline/promises";
 
+import { parseCustomRange } from "./range.mjs";
+
 function formatSessionDate(value, timezone, locale) {
   return new Intl.DateTimeFormat(locale === "en" ? "en-US" : "zh-CN", {
     timeZone: timezone,
@@ -21,6 +23,15 @@ function sessionLine(session, index, timezone, locale) {
   return `${index + 1}. ${start}–${end} · ${session.completedTurns} 轮 · ${session.toolCalls} 次工具调用 · ${model}`;
 }
 
+function projectLine(project, index, timezone, locale) {
+  const latest = formatSessionDate(project.endAt, timezone, locale);
+  const suffix = project.projectId.slice(-6).toUpperCase();
+  if (locale === "en") {
+    return `${index + 1}. ${project.projectLabel} · ${project.sessionCount} sessions · latest ${latest} · ${suffix}`;
+  }
+  return `${index + 1}. ${project.projectLabel} · ${project.sessionCount} 个会话 · 最近 ${latest} · ${suffix}`;
+}
+
 async function askForNumber(readline, prompt, minimum, maximum, fallback = null) {
   while (true) {
     const answer = (await readline.question(prompt)).trim();
@@ -30,11 +41,135 @@ async function askForNumber(readline, prompt, minimum, maximum, fallback = null)
   }
 }
 
-export async function promptForRange({ locale, timezone, loadRecentSessions }) {
+async function askForValue(readline, prompt) {
+  while (true) {
+    const answer = (await readline.question(prompt)).trim();
+    if (answer) return answer;
+  }
+}
+
+async function chooseSession(readline, { locale, timezone, loadRecentSessions }) {
   const isEnglish = locale === "en";
-  const readline = createInterface({ input: process.stdin, output: process.stdout });
+  const sessions = await loadRecentSessions();
+  if (!sessions.length) throw new Error(isEnglish ? "No Codex sessions found" : "没有找到可选择的 Codex 会话");
+
+  console.log(isEnglish ? "\nRecent sessions:\n" : "\n最近的会话：\n");
+  sessions.forEach((session, index) => console.log(sessionLine(session, index, timezone, locale)));
+  const choice = await askForNumber(
+    readline,
+    isEnglish ? `\nEnter 1–${sessions.length}: ` : `\n请输入 1–${sessions.length}：`,
+    1,
+    sessions.length,
+  );
+  return { mode: "session", sessionId: sessions[choice - 1].sessionId };
+}
+
+async function chooseCustomRange(readline, { locale, timezone }) {
+  const isEnglish = locale === "en";
+  console.log(isEnglish ? "\nChoose custom range precision:\n" : "\n请选择自定义区间精度：\n");
+  console.log(isEnglish
+    ? "1. Calendar dates (accountable cwr2 facts)"
+    : "1. 按自然日（生成可计入供销社的 cwr2 事实）");
+  console.log(isEnglish
+    ? "2. Exact date and time (private cwr1 summary)"
+    : "2. 精确到时间（生成不计入供销社的私人 cwr1 摘要）");
+  const precision = await askForNumber(
+    readline,
+    isEnglish ? "\nEnter 1–2 (default 1): " : "\n请输入 1–2（默认 1）：",
+    1,
+    2,
+    1,
+  );
+  const dateOnly = precision === 1;
+  const format = dateOnly ? "YYYY-MM-DD" : "YYYY-MM-DDTHH:mm";
+  while (true) {
+    const from = await askForValue(
+      readline,
+      isEnglish ? `Start (${format}, ${timezone}): ` : `开始（${format}，${timezone}）：`,
+    );
+    const to = await askForValue(
+      readline,
+      isEnglish ? `End (${format}, ${timezone}): ` : `结束（${format}，${timezone}）：`,
+    );
+    try {
+      parseCustomRange(from, to, timezone);
+    } catch (error) {
+      console.log(isEnglish ? `Invalid range: ${error.message}` : `区间无效：${error.message}`);
+      continue;
+    }
+    const confirmation = (await readline.question(isEnglish
+      ? `Use ${from} to ${to} in ${timezone}? [Y/n]: `
+      : `确认统计 ${timezone} 的 ${from} 至 ${to}？[Y/n]：`)).trim().toLowerCase();
+    if (!confirmation || confirmation === "y" || confirmation === "yes") {
+      return { mode: "custom-range", sessionId: null, from, to };
+    }
+  }
+}
+
+async function chooseProjectRange(readline, { locale, timezone, loadRecentProjects }) {
+  const isEnglish = locale === "en";
+  const projects = await loadRecentProjects();
+  if (!projects.length) throw new Error(isEnglish ? "No projects found in recent Codex sessions" : "最近的 Codex 会话中没有找到项目");
 
+  console.log(isEnglish ? "\nRecent projects:\n" : "\n最近的项目：\n");
+  projects.forEach((project, index) => console.log(projectLine(project, index, timezone, locale)));
+  const projectChoice = await askForNumber(
+    readline,
+    isEnglish ? `\nEnter 1–${projects.length}: ` : `\n请输入 1–${projects.length}：`,
+    1,
+    projects.length,
+  );
+
+  console.log(isEnglish ? "\nChoose a range for this project:\n" : "\n请选择该项目的统计范围：\n");
+  console.log(isEnglish ? "1. Today (recommended)" : "1. 今天（推荐）");
+  console.log(isEnglish ? "2. Last 3 hours" : "2. 最近 3 小时");
+  console.log(isEnglish ? "3. Last 7 calendar days" : "3. 最近 7 个自然日");
+  console.log(isEnglish ? "4. This week" : "4. 本周");
+  console.log(isEnglish ? "5. Custom range" : "5. 自定义时间区间");
+  const rangeChoice = await askForNumber(
+    readline,
+    isEnglish ? "\nEnter 1–5 (default 1): " : "\n请输入 1–5（默认 1）：",
+    1,
+    5,
+    1,
+  );
+  const projectId = projects[projectChoice - 1].projectId;
+  if (rangeChoice === 1) return { mode: "today", projectId };
+  if (rangeChoice === 2) return { mode: "last-hours", hours: 3, projectId };
+  if (rangeChoice === 3) return { mode: "last-7-days", projectId };
+  if (rangeChoice === 4) return { mode: "this-week", projectId };
+  return { ...(await chooseCustomRange(readline, { locale, timezone })), projectId };
+}
+
+async function withReadline(callback) {
+  const readline = createInterface({ input: process.stdin, output: process.stdout });
   try {
+    return await callback(readline);
+  } finally {
+    readline.close();
+  }
+}
+
+export function promptForSpecificSession(options) {
+  return withReadline((readline) => chooseSession(readline, options));
+}
+
+export function promptForCustomRange(options) {
+  return withReadline((readline) => chooseCustomRange(readline, options));
+}
+
+export function promptForProjectRange(options) {
+  return withReadline((readline) => chooseProjectRange(readline, options));
+}
+
+export async function promptForRange({
+  locale,
+  timezone,
+  loadRecentSessions,
+  loadRecentProjects,
+}) {
+  const isEnglish = locale === "en";
+  return withReadline(async (readline) => {
     console.log(isEnglish ? "\nChoose a receipt range:\n" : "\n请选择小票统计范围：\n");
     console.log(isEnglish ? "1. All activity today (recommended)" : "1. 今天全部活动（推荐）");
     console.log(isEnglish
@@ -42,13 +177,15 @@ export async function promptForRange({ locale, timezone, loadRecentSessions }) {
       : "2. 最近 3 小时（私人滚动摘要，不计入供销社）");
     console.log(isEnglish ? "3. Last 7 calendar days" : "3. 最近 7 个自然日");
     console.log(isEnglish ? "4. This week (Monday to now)" : "4. 本周（周一至今）");
-    console.log(isEnglish ? "5. Choose a specific session" : "5. 选择一个具体会话");
+    console.log(isEnglish ? "5. Custom date or time range" : "5. 自定义日期或时间区间");
+    console.log(isEnglish ? "6. Choose a specific session" : "6. 选择一个具体会话");
+    console.log(isEnglish ? "7. Choose a project" : "7. 选择一个项目");
 
     const choice = await askForNumber(
       readline,
-      isEnglish ? "\nEnter 1–5 (default 1): " : "\n请输入 1–5（默认 1）：",
+      isEnglish ? "\nEnter 1–7 (default 1): " : "\n请输入 1–7（默认 1）：",
       1,
-      5,
+      7,
       1,
     );
 
@@ -56,20 +193,8 @@ export async function promptForRange({ locale, timezone, loadRecentSessions }) {
     if (choice === 2) return { mode: "last-hours", sessionId: null, hours: 3 };
     if (choice === 3) return { mode: "last-7-days", sessionId: null };
     if (choice === 4) return { mode: "this-week", sessionId: null };
-
-    const sessions = await loadRecentSessions();
-    if (!sessions.length) throw new Error(isEnglish ? "No Codex sessions found" : "没有找到可选择的 Codex 会话");
-
-    console.log(isEnglish ? "\nRecent sessions:\n" : "\n最近的会话：\n");
-    sessions.forEach((session, index) => console.log(sessionLine(session, index, timezone, locale)));
-    const sessionChoice = await askForNumber(
-      readline,
-      isEnglish ? `\nEnter 1–${sessions.length}: ` : `\n请输入 1–${sessions.length}：`,
-      1,
-      sessions.length,
-    );
-    return { mode: "session", sessionId: sessions[sessionChoice - 1].sessionId };
-  } finally {
-    readline.close();
-  }
+    if (choice === 5) return chooseCustomRange(readline, { locale, timezone });
+    if (choice === 6) return chooseSession(readline, { locale, timezone, loadRecentSessions });
+    return chooseProjectRange(readline, { locale, timezone, loadRecentProjects });
+  });
 }

package/src/parsers/codex.mjs

@@ -5,6 +5,7 @@ import path from "node:path";
 
 import { rowDate } from "../lib/time.mjs";
 import { classifyToolName } from "../lib/tool-category.mjs";
+import { projectDescriptorFromSessionMeta } from "../core/project-identity.mjs";
 
 const READ_CHUNK_BYTES = 256 * 1024;
 const MAX_JSONL_ROW_BYTES = 64 * 1024 * 1024;
@@ -115,7 +116,7 @@ function sessionReadError(file, error) {
   );
 }
 
-function readJsonl(file) {
+function readJsonl(file, projectSecret = null) {
   const rows = [];
   const buffer = Buffer.allocUnsafe(READ_CHUNK_BYTES);
   const lineParts = [];
@@ -125,6 +126,7 @@ function readJsonl(file) {
   let tail = Buffer.alloc(0);
   let skippingOversizedLine = false;
   let fileDescriptor = null;
+  let project = null;
 
   const resetLine = () => {
     lineParts.length = 0;
@@ -160,7 +162,11 @@ function readJsonl(file) {
     const line = lineBuffer.toString("utf8").replace(/\r$/, "");
     if (line.trim()) {
       try {
-        const compact = compactRow(JSON.parse(line), lineIndex);
+        const parsed = JSON.parse(line);
+        if (!project && parsed?.type === "session_meta" && projectSecret) {
+          project = projectDescriptorFromSessionMeta(parsed.payload, projectSecret);
+        }
+        const compact = compactRow(parsed, lineIndex);
         if (compact) rows.push(compact);
       } catch {
         console.warn(`跳过无法解析的记录：${file.filePath}:${lineIndex}`);
@@ -200,11 +206,12 @@ function readJsonl(file) {
     rows,
     byteLength: offset,
     tailHash: crypto.createHash("sha256").update(tail).digest("hex"),
+    project,
   };
 }
 
-function sessionFromFile(file) {
-  const { rows, byteLength, tailHash } = readJsonl(file);
+function sessionFromFile(file, projectSecret = null) {
+  const { rows, byteLength, tailHash, project } = readJsonl(file, projectSecret);
   const meta = rows.find((row) => row.type === "session_meta")?.payload || {};
   const metadataSessionId = meta.session_id || meta.id || null;
   const timestamps = rows.map(rowDate).filter(Boolean).sort((left, right) => left - right);
@@ -215,6 +222,8 @@ function sessionFromFile(file) {
     modifiedAt: file.modifiedAt,
     sessionId: metadataSessionId || path.basename(file.filePath, ".jsonl"),
     identityQuality: metadataSessionId ? "metadata" : "filename_fallback",
+    projectId: project?.projectId || null,
+    projectLabel: project?.projectLabel || null,
     sourceRevision: {
       kind: "append-only-jsonl-v1",
       row_count: rows.length,
@@ -281,12 +290,16 @@ export function deduplicateCodexSessions(sessions) {
   return [...selected.values()];
 }
 
-export function loadCodexSessions(range, { codexHome = null } = {}) {
+export function loadCodexSessions(range, { codexHome = null, projectSecret = null } = {}) {
   const files = codexSessionFiles(codexHome);
   let candidates = files;
   let scanMode = "none";
 
-  if (range.scope === "latest") {
+  if (range.projectId) {
+    const fullScan = process.env.CODEX_WORK_RECEIPT_FULL_SCAN === "1";
+    candidates = range.startDate && !fullScan ? calendarCandidates(files, range.startDate) : files;
+    scanMode = fullScan ? "full" : "best_effort";
+  } else if (range.scope === "latest") {
     candidates = files.slice(0, 40);
   } else if (range.scope === "session" && range.sessionId) {
     const filenameMatches = files.filter((file) => path.basename(file.filePath).includes(range.sessionId));
@@ -297,7 +310,8 @@ export function loadCodexSessions(range, { codexHome = null } = {}) {
     scanMode = fullScan ? "full" : "best_effort";
   }
 
-  const sessions = deduplicateCodexSessions(candidates.map(sessionFromFile))
+  const sessions = deduplicateCodexSessions(candidates.map((file) => sessionFromFile(file, projectSecret)))
+    .filter((session) => !range.projectId || session.projectId === range.projectId)
     .sort((left, right) => right.endAt - left.endAt);
 
   if (range.scope === "latest") {
@@ -346,3 +360,34 @@ export function listRecentCodexSessions(limit = 10, { codexHome = null } = {}) {
     };
   });
 }
+
+export function listRecentCodexProjects(
+  limit = 10,
+  { codexHome = null, projectSecret = null } = {},
+) {
+  if (!projectSecret) throw new Error("列出项目时缺少本地项目身份密钥");
+  const sessions = deduplicateCodexSessions(codexSessionFiles(codexHome)
+    .slice(0, Math.max(120, limit * 20))
+    .map((file) => sessionFromFile(file, projectSecret))
+    .filter((session) => session.rows.length && session.projectId));
+  const projects = new Map();
+  for (const session of sessions) {
+    const current = projects.get(session.projectId);
+    if (!current) {
+      projects.set(session.projectId, {
+        projectId: session.projectId,
+        projectLabel: session.projectLabel,
+        sessionCount: 1,
+        startAt: session.startAt,
+        endAt: session.endAt,
+      });
+      continue;
+    }
+    current.sessionCount += 1;
+    if (session.startAt < current.startAt) current.startAt = session.startAt;
+    if (session.endAt > current.endAt) current.endAt = session.endAt;
+  }
+  return [...projects.values()]
+    .sort((left, right) => right.endAt - left.endAt)
+    .slice(0, limit);
+}