codex-work-receipt 0.9.0 → 0.10.0

package/src/core/args.mjs

@@ -11,16 +11,25 @@ Usage:
   npx codex-work-receipt@latest --today --lang en
   npx codex-work-receipt@latest --range last-7-days --lang en
   npx codex-work-receipt@latest --range this-week --lang en
+  npx codex-work-receipt@latest --custom-range --lang en
+  npx codex-work-receipt@latest --select-session --lang en
+  npx codex-work-receipt@latest --select-project --lang en
   npx codex-work-receipt@latest --install-skill --lang en
   npx codex-work-receipt@latest --install-companion --lang en
   npx codex-work-receipt@latest --setup --lang en
 
 Options:
-  --range <name>              Range: latest, last-hours, today, last-7-days, this-week
+  --range <name>              Range: latest, last-hours, custom-range, today, last-7-days, this-week
   --hours <number>            Summarize the last 1-168 hours
+  --custom-range              Interactively choose a custom date or time range
+  --from <value>              Custom start: YYYY-MM-DD or YYYY-MM-DDTHH:mm
+  --to <value>                Custom end: YYYY-MM-DD or YYYY-MM-DDTHH:mm
   --latest                    Summarize the latest active Codex session (default)
   --today                     Summarize all Codex activity from today
   --session <id>              Summarize one specific Codex session
+  --select-session            Interactively choose a recent Codex session
+  --project <directory>       Limit the receipt to one local project
+  --select-project            Interactively choose a recent project and range
   --timezone <name>           Use an IANA timezone, for example Asia/Shanghai
   --lang <name>               Receipt language: zh-CN, en
   --theme <name>              Default theme: classic, diner, payroll
@@ -46,16 +55,25 @@ Codex AI 打工小票
   npx codex-work-receipt@latest --today
   npx codex-work-receipt@latest --range last-7-days
   npx codex-work-receipt@latest --range this-week
+  npx codex-work-receipt@latest --custom-range
+  npx codex-work-receipt@latest --select-session
+  npx codex-work-receipt@latest --select-project
   npx codex-work-receipt@latest --install-skill
   npx codex-work-receipt@latest --install-companion
   npx codex-work-receipt@latest --setup
 
 选项：
-  --range <name>              统计范围：latest、last-hours、today、last-7-days、this-week
+  --range <name>              统计范围：latest、last-hours、custom-range、today、last-7-days、this-week
   --hours <number>            统计最近 1～168 小时
+  --custom-range              交互选择自定义日期或精确时间区间
+  --from <value>              自定义开始：YYYY-MM-DD 或 YYYY-MM-DDTHH:mm
+  --to <value>                自定义结束：YYYY-MM-DD 或 YYYY-MM-DDTHH:mm
   --latest                    统计最近活跃的 Codex 会话（默认）
   --today                     统计本地时区今天发生的全部 Codex 活动
   --session <id>              统计指定的 Codex 会话
+  --select-session            交互选择最近的 Codex 会话
+  --project <directory>       只统计指定的本地项目目录
+  --select-project            交互选择最近项目及统计范围
   --timezone <name>           指定 IANA 时区，例如 Asia/Shanghai
   --lang <name>               小票语言：zh-CN、en
   --theme <name>              默认主题：classic、diner、payroll
@@ -79,7 +97,14 @@ export function parseArgs(argv) {
     mode: "latest",
     modeExplicit: false,
     sessionId: null,
+    selectSession: false,
+    project: null,
+    projectId: null,
+    selectProject: false,
     hours: null,
+    customRange: false,
+    from: null,
+    to: null,
     timezone: Intl.DateTimeFormat().resolvedOptions().timeZone || "Asia/Shanghai",
     locale: "zh-CN",
     theme: "classic",
@@ -103,7 +128,10 @@ export function parseArgs(argv) {
     ["--output", "output"],
     ["--data-dir", "dataDir"],
     ["--session", "sessionId"],
+    ["--project", "project"],
     ["--hours", "hours"],
+    ["--from", "from"],
+    ["--to", "to"],
   ]);
 
   for (let index = 0; index < argv.length; index += 1) {
@@ -114,7 +142,13 @@ export function parseArgs(argv) {
     } else if (argument === "--today") {
       result.mode = "today";
       result.modeExplicit = true;
-    } else if (argument === "--install-pet") result.installPet = true;
+    } else if (argument === "--custom-range") {
+      result.mode = "custom-range";
+      result.modeExplicit = true;
+      result.customRange = true;
+    } else if (argument === "--select-session") result.selectSession = true;
+    else if (argument === "--select-project") result.selectProject = true;
+    else if (argument === "--install-pet") result.installPet = true;
     else if (argument === "--uninstall-pet") result.uninstallPet = true;
     else if (argument === "--install-companion") result.installCompanion = true;
     else if (argument === "--range") {
@@ -142,6 +176,10 @@ export function parseArgs(argv) {
       } else if (key === "hours") {
         result.mode = "last-hours";
         result.modeExplicit = true;
+      } else if (key === "from" || key === "to") {
+        result.mode = "custom-range";
+        result.modeExplicit = true;
+        result.customRange = true;
       }
     } else throw new Error(`不认识的参数：${argument}`);
   }
@@ -164,6 +202,18 @@ export function parseArgs(argv) {
     }
   }
   if (result.mode === "last-hours" && result.hours === null) result.hours = 3;
+  if (result.mode === "custom-range") result.customRange = true;
+  if (Boolean(result.from) !== Boolean(result.to)) throw new Error("--from 和 --to 必须同时使用");
+  if (result.selectSession && result.selectProject) throw new Error("不能同时选择会话和项目");
+  if ((result.selectSession || result.selectProject) && result.modeExplicit) {
+    throw new Error("交互选择参数不能与统计范围参数同时使用");
+  }
+  if (result.selectSession && result.project) throw new Error("指定会话时不能同时指定项目");
+  if (result.selectProject && result.project) throw new Error("不能同时使用 --project 和 --select-project");
+  if (result.project && !result.modeExplicit) {
+    result.mode = "today";
+    result.modeExplicit = true;
+  }
   const managementActions = [
     result.setup,
     result.enableAuto,
@@ -172,8 +222,14 @@ export function parseArgs(argv) {
   ].filter(Boolean).length;
   if (managementActions > 1) throw new Error("自动保存管理参数不能同时使用");
   if (managementActions && result.modeExplicit) throw new Error("自动保存管理参数不能与统计范围参数同时使用");
+  if (managementActions && (result.selectSession || result.selectProject || result.project)) {
+    throw new Error("自动保存管理参数不能与会话或项目选择参数同时使用");
+  }
   if (managementActions && (
     result.installSkill || result.installPet || result.uninstallPet || result.installCompanion
   )) throw new Error("自动保存管理参数不能与 Skill 或桌宠管理参数同时使用");
+  if ((result.selectSession || result.selectProject || result.project) && (
+    result.installSkill || result.installPet || result.uninstallPet || result.installCompanion
+  )) throw new Error("会话或项目选择参数不能与 Skill 或桌宠管理参数同时使用");
   return result;
 }

package/src/core/fact-buckets.mjs

@@ -7,7 +7,7 @@ import {
   METRIC_SCHEMA_VERSION,
 } from "./fact-identity.mjs";
 import { dateKey, rowDate } from "../lib/time.mjs";
-import { isCalendarScope, isDateInRange, shiftDateKey } from "./range.mjs";
+import { isCalendarRange, isDateInRange, shiftDateKey } from "./range.mjs";
 
 const TOKEN_KEYS = [
   "input_tokens",
@@ -112,7 +112,7 @@ function metricsForRows(sessionRows, bucketRows, localDate, timezone) {
 }
 
 function coverageForRange(range, scanMode, observedAt) {
-  if (!isCalendarScope(range.scope)) {
+  if (!isCalendarRange(range)) {
     return {
       kind: "selected_sessions",
       scan_mode: "none",
@@ -151,7 +151,7 @@ export function buildCanonicalFacts(sessions, range, options = {}) {
 
     for (const row of sessionRows) {
       const date = rowDate(row);
-      if (!date || (isCalendarScope(range.scope) && !isDateInRange(date, range))) continue;
+      if (!date || (isCalendarRange(range) && !isDateInRange(date, range))) continue;
       const localDate = dateKey(date, accountingTimezone);
       const rows = buckets.get(localDate) || [];
       rows.push(row);

package/src/core/fact-identity.mjs

@@ -25,16 +25,20 @@ export function buildLogicalReceiptKey(metrics) {
   const sessionPart = stableId("cwg", "codex-work-receipt/session-group/v1", [
     ...[...metrics.sessionIds].sort(),
   ]);
+  const projectPart = metrics.projectId ? `:project:${metrics.projectId}` : "";
   if (metrics.mode === "latest" || metrics.mode === "session") {
-    return `${metrics.mode}:${sessionPart}:${metrics.timezone}`;
+    return `${metrics.mode}:${sessionPart}:${metrics.timezone}${projectPart}`;
   }
   if (metrics.mode === "last-hours") {
-    return `last-hours:${metrics.windowHours}:${metrics.windowStartAt.toISOString()}:${metrics.windowEndAt.toISOString()}:${metrics.timezone}`;
+    return `last-hours:${metrics.windowHours}:${metrics.windowStartAt.toISOString()}:${metrics.windowEndAt.toISOString()}:${metrics.timezone}${projectPart}`;
+  }
+  if (metrics.mode === "custom-range") {
+    return `custom-range:${metrics.boundaryKind}:${metrics.windowStartAt.toISOString()}:${metrics.windowEndAt.toISOString()}:${metrics.timezone}${projectPart}`;
   }
   if (metrics.mode === "this-week") {
-    return `this-week:${metrics.rangeStartDate}:${metrics.timezone}`;
+    return `this-week:${metrics.rangeStartDate}:${metrics.timezone}${projectPart}`;
   }
-  return `${metrics.mode}:${metrics.rangeStartDate}:${metrics.rangeEndDate}:${metrics.timezone}`;
+  return `${metrics.mode}:${metrics.rangeStartDate}:${metrics.rangeEndDate}:${metrics.timezone}${projectPart}`;
 }
 
 export function buildSummaryReceiptId(logicalReceiptKey) {

package/src/core/generator.mjs

@@ -4,6 +4,7 @@ import path from "node:path";
 import { buildCanonicalFacts } from "./fact-buckets.mjs";
 import { createReceiptFile } from "./file-payload.mjs";
 import { collectMetrics } from "./metrics.mjs";
+import { getProjectIdentitySecret } from "./project-identity.mjs";
 import { outputSlugForRange, resolveRange } from "./range.mjs";
 import {
   buildReceiptRecord,
@@ -39,11 +40,22 @@ export async function generateReceipt(
 ) {
   if (!projectDir) throw new Error("生成小票时缺少项目目录");
 
-  const range = resolveRange(options.mode, options.timezone, now, options.sessionId, options.hours);
-  const sessions = loadCodexSessions(range, { codexHome });
+  const range = resolveRange(
+    options.mode,
+    options.timezone,
+    now,
+    options.sessionId,
+    options.hours,
+    options.mode === "custom-range" ? { from: options.from, to: options.to } : null,
+    options.projectId,
+  );
+  const projectSecret = range.projectId ? getProjectIdentitySecret({ dataDir: options.dataDir }) : null;
+  const sessions = loadCodexSessions(range, { codexHome, projectSecret });
   const metrics = collectMetrics(sessions, range);
   const observedAt = now.toISOString();
-  const canonical = range.scope === "last-hours"
+  const summaryOnly = range.scope === "last-hours"
+    || (range.scope === "custom-range" && range.boundaryKind === "exact-time");
+  const canonical = summaryOnly
     ? {}
     : buildCanonicalFacts(sessions, range, { observedAt });
   const record = buildReceiptRecord(metrics, options.theme, options.locale, canonical);

package/src/core/metrics.mjs

@@ -2,9 +2,9 @@ import { dateKey, rowDate } from "../lib/time.mjs";
 import { toolCategoryForRow } from "../lib/tool-category.mjs";
 import {
   calendarDayCount,
-  isCalendarScope,
+  isCalendarRange,
   isDateInRange,
-  isTimeWindowScope,
+  isTimeWindowRange,
 } from "./range.mjs";
 import { selectWorkProfileId } from "./presentation.mjs";
 
@@ -111,7 +111,7 @@ function sessionTokenUsage(rows, range) {
   for (const row of events) {
     const currentUsage = row.payload.info.total_token_usage;
     const date = rowDate(row);
-    const selected = (!isCalendarScope(range.scope) && !isTimeWindowScope(range.scope))
+    const selected = (!isCalendarRange(range) && !isTimeWindowRange(range))
       || isDateInRange(date, range);
 
     for (const key of Object.keys(totals)) {
@@ -141,6 +141,7 @@ function calculateWorkPoints(metrics) {
 
 function emptyRangeMessage(range) {
   if (range.scope === "last-hours") return `最近 ${range.hours} 小时没有找到 Codex 活动`;
+  if (range.scope === "custom-range") return "自定义时间区间内没有找到 Codex 活动";
   if (range.scope === "today") return `没有找到 ${range.targetDate} 的 Codex 活动`;
   if (range.scope === "last-7-days") return `没有找到 ${range.startDate} 至 ${range.endDate} 的 Codex 活动`;
   if (range.scope === "this-week") return `本周暂时没有找到 Codex 活动`;
@@ -169,7 +170,7 @@ export function collectMetrics(sessions, range) {
   const activityByHour = Array(24).fill(0);
 
   for (const session of sessions) {
-    const scopedRows = isCalendarScope(range.scope) || isTimeWindowScope(range.scope)
+    const scopedRows = isCalendarRange(range) || isTimeWindowRange(range)
       ? session.rows.filter((row) => isDateInRange(rowDate(row), range))
       : session.rows;
 
@@ -183,7 +184,7 @@ export function collectMetrics(sessions, range) {
     let sessionHasSelectedModel = false;
     for (const row of session.rows) {
       if (row.type === "turn_context" && row.payload?.model) activeModel = row.payload.model;
-      const selected = (!isCalendarScope(range.scope) && !isTimeWindowScope(range.scope))
+      const selected = (!isCalendarRange(range) && !isTimeWindowRange(range))
         || isDateInRange(rowDate(row), range);
       if (!selected) continue;
       const date = rowDate(row);
@@ -258,7 +259,9 @@ export function collectMetrics(sessions, range) {
     windowStartAt: range.startAt,
     windowEndAt: range.endAt,
     windowHours: range.hours,
-    calendarDayCount: isCalendarScope(range.scope) ? calendarDayCount(range) : 1,
+    boundaryKind: range.boundaryKind,
+    projectId: range.projectId,
+    calendarDayCount: isCalendarRange(range) ? calendarDayCount(range) : 1,
     activeDayCount: Math.max(1, activeDateKeys.size),
     sessionIds,
     sessionCount: scopedSessions.length,

package/src/core/presentation.mjs

@@ -102,18 +102,30 @@ const RECEIPT_COPY = {
         copyErrorLabel: "复制失败",
         copiedStatus: "命令已复制到剪贴板",
         copyErrorStatus: "无法自动复制，请手动选择命令",
+        tabAria: "小票功能分类",
         groups: [
           {
-            title: "生成小票",
+            id: "time",
+            title: "时间范围",
             commands: [
               { label: "生成最近一次小票", args: "--latest" },
               { label: "生成最近 3 小时小票", args: "--hours 3" },
               { label: "生成今日小票", args: "--today" },
               { label: "生成最近 7 天小票", args: "--range last-7-days" },
               { label: "生成本周小票", args: "--range this-week" },
+              { label: "自定义时间区间", args: "--custom-range" },
             ],
           },
           {
+            id: "selection",
+            title: "会话与项目",
+            commands: [
+              { label: "选择指定会话", args: "--select-session" },
+              { label: "选择指定项目", args: "--select-project" },
+            ],
+          },
+          {
+            id: "automation",
             title: "自动与手动",
             commands: [
               { label: "重新选择工作模式", args: "--setup" },
@@ -123,6 +135,7 @@ const RECEIPT_COPY = {
             ],
           },
           {
+            id: "companion",
             title: "票仔与对话开票",
             commands: [
               { label: "安装票仔和对话开票", args: "--install-companion" },
@@ -142,6 +155,9 @@ const RECEIPT_COPY = {
       latest: "最近一次会话",
       session: "指定会话",
       "last-hours": "最近 {hours} 小时",
+      "custom-range-calendar-days": "自定义日期",
+      "custom-range-exact-time": "自定义时间",
+      "custom-range": "自定义区间",
       today: "今日全部会话",
       "last-7-days": "最近 7 个自然日",
       "this-week": "本周全部会话",
@@ -235,6 +251,8 @@ const RECEIPT_COPY = {
     placeholderAria: "小程序码待接入",
     transferNote: "导入文件和可选数据码只包含时间、轮次、Token 和工具调用等统计，不包含 Prompt、回复正文、代码、项目路径或文件名。",
     rollingSummaryNotice: "最近 {hours} 小时属于滚动摘要，只保存到私人历史，不参与 AI 供销社统计。需要统计时请生成“今日 / 本周 / 近 7 日 / 指定会话”小票。",
+    customSummaryNotice: "精确时间区间属于私人摘要，不参与 AI 供销社统计。按自然日选择自定义区间时可以生成可去重的规范事实。",
+    projectScopeTemplate: "指定项目 · {scope}",
     privacy: "结构数据和微信导入文件同时保存在本机；只有你主动发送文件或扫码时，脱敏统计才会离开电脑。",
   },
   en: {
@@ -264,18 +282,30 @@ const RECEIPT_COPY = {
         copyErrorLabel: "Copy failed",
         copiedStatus: "Command copied to the clipboard",
         copyErrorStatus: "Could not copy automatically. Select the command manually.",
+        tabAria: "Receipt feature categories",
         groups: [
           {
-            title: "Generate receipts",
+            id: "time",
+            title: "Time ranges",
             commands: [
               { label: "Generate the latest receipt", args: "--latest" },
               { label: "Generate the last 3 hours", args: "--hours 3" },
               { label: "Generate today's receipt", args: "--today" },
               { label: "Generate the last 7 days", args: "--range last-7-days" },
               { label: "Generate this week's receipt", args: "--range this-week" },
+              { label: "Choose a custom range", args: "--custom-range" },
+            ],
+          },
+          {
+            id: "selection",
+            title: "Sessions and projects",
+            commands: [
+              { label: "Choose a specific session", args: "--select-session" },
+              { label: "Choose a specific project", args: "--select-project" },
             ],
           },
           {
+            id: "automation",
             title: "Automatic and manual",
             commands: [
               { label: "Choose a working mode", args: "--setup" },
@@ -285,6 +315,7 @@ const RECEIPT_COPY = {
             ],
           },
           {
+            id: "companion",
             title: "Ticket Buddy and chat commands",
             commands: [
               { label: "Install Ticket Buddy and chat commands", args: "--install-companion" },
@@ -304,6 +335,9 @@ const RECEIPT_COPY = {
       latest: "Latest session",
       session: "Selected session",
       "last-hours": "Last {hours} hours",
+      "custom-range-calendar-days": "Custom dates",
+      "custom-range-exact-time": "Custom time range",
+      "custom-range": "Custom range",
       today: "All sessions today",
       "last-7-days": "Last 7 calendar days",
       "this-week": "All sessions this week",
@@ -397,6 +431,8 @@ const RECEIPT_COPY = {
     placeholderAria: "Mini-program code pending",
     transferNote: "The import file and optional data code contain only statistics such as time, turns, Tokens, and tool calls. They do not contain prompts, responses, code, project paths, or file names.",
     rollingSummaryNotice: "The last {hours} hours is a rolling summary for private history only. It does not participate in AI Work Cooperative accounting. Use today, this week, the last seven days, or a specific session for accountable facts.",
+    customSummaryNotice: "An exact time range is a private summary and does not participate in AI Work Cooperative accounting. Choose whole calendar dates to create deduplicated canonical facts.",
+    projectScopeTemplate: "Selected project · {scope}",
     privacy: "Structured data and the WeChat import file stay on this computer until you explicitly send the file or scan its data code.",
   },
 };
@@ -406,6 +442,7 @@ const COMPENSATION_COPY = {
     latest: "本单工资",
     session: "本单工资",
     "last-hours": "本段工资",
+    "custom-range": "区间工资",
     today: "本日工资",
     "last-7-days": "近七日工资",
     "this-week": "本周工资",
@@ -416,6 +453,7 @@ const COMPENSATION_COPY = {
     latest: "SHIFT PAY",
     session: "SHIFT PAY",
     "last-hours": "WINDOW PAY",
+    "custom-range": "RANGE PAY",
     today: "TODAY'S PAY",
     "last-7-days": "7-DAY PAY",
     "this-week": "THIS WEEK'S PAY",
@@ -444,15 +482,26 @@ export function getReceiptCopy(locale = DEFAULT_LOCALE) {
   return RECEIPT_COPY[SUPPORTED_LOCALES.has(locale) ? locale : DEFAULT_LOCALE];
 }
 
-export function getScopeLabel(scope, locale = DEFAULT_LOCALE, hours = null) {
-  const template = getReceiptCopy(locale).scope[scope] || getReceiptCopy(locale).scope.latest;
-  return String(template).replaceAll("{hours}", String(hours || 3));
+export function getScopeLabel(scope, locale = DEFAULT_LOCALE, hours = null, options = {}) {
+  const copy = getReceiptCopy(locale);
+  const scopeKey = scope === "custom-range" && options.rangeKind
+    ? `custom-range-${options.rangeKind}`
+    : scope;
+  const template = copy.scope[scopeKey] || copy.scope[scope] || copy.scope.latest;
+  const label = String(template).replaceAll("{hours}", String(hours || 3));
+  return options.filterKind === "project"
+    ? String(copy.projectScopeTemplate).replaceAll("{scope}", label)
+    : label;
 }
 
 export function getRollingSummaryNotice(locale = DEFAULT_LOCALE, hours = null) {
   return String(getReceiptCopy(locale).rollingSummaryNotice).replaceAll("{hours}", String(hours || 3));
 }
 
+export function getCustomSummaryNotice(locale = DEFAULT_LOCALE) {
+  return getReceiptCopy(locale).customSummaryNotice;
+}
+
 export function buildCompensation(scope, amount, locale = DEFAULT_LOCALE) {
   const copy = COMPENSATION_COPY[SUPPORTED_LOCALES.has(locale) ? locale : DEFAULT_LOCALE];
   return {

package/src/core/project-identity.mjs

@@ -0,0 +1,132 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { writeFileAtomicSync } from "../lib/files.mjs";
+
+const PROJECT_KEY_FILENAME = "project-identity.key";
+const PROJECT_ID_DOMAIN = "codex-work-receipt/project/v1";
+
+function workReceiptHome(requestedDataDir = null) {
+  return path.resolve(
+    requestedDataDir || process.env.CODEX_WORK_RECEIPT_HOME || path.join(os.homedir(), ".codex-work-receipt"),
+  );
+}
+
+function normalizeRepositoryUrl(value) {
+  return String(value || "")
+    .trim()
+    .replace(/\\/g, "/")
+    .replace(/^git@([^:]+):/i, "$1/")
+    .replace(/^[a-z][a-z0-9+.-]*:\/\/(?:[^@/]+@)?/i, "")
+    .replace(/\.git\/?$/i, "")
+    .replace(/\/+$/, "")
+    .toLowerCase();
+}
+
+function projectLabelFromRepositoryUrl(value) {
+  const normalized = String(value || "").trim().replace(/\\/g, "/").replace(/\.git\/?$/i, "");
+  const segment = normalized.split(/[/:]/).filter(Boolean).at(-1);
+  return segment || null;
+}
+
+function normalizeWorkingDirectory(value) {
+  const resolved = path.resolve(String(value || "").trim());
+  return process.platform === "win32" ? resolved.toLowerCase() : resolved;
+}
+
+function projectIdForIdentity(identity, secret) {
+  const digest = crypto
+    .createHmac("sha256", secret)
+    .update(`${PROJECT_ID_DOMAIN}\0${identity}`)
+    .digest("hex");
+  return `cwp_${digest}`;
+}
+
+function gitDirectoryForProject(projectPath) {
+  let current = projectPath;
+  while (true) {
+    const candidate = path.join(current, ".git");
+    if (fs.existsSync(candidate)) {
+      const stats = fs.statSync(candidate);
+      if (stats.isDirectory()) return candidate;
+      if (stats.isFile()) {
+        const match = /^gitdir:\s*(.+)$/im.exec(fs.readFileSync(candidate, "utf8"));
+        if (match) return path.resolve(current, match[1].trim());
+      }
+    }
+    const parent = path.dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+function repositoryUrlFromConfig(gitDirectory) {
+  if (!gitDirectory) return null;
+  let configPath = path.join(gitDirectory, "config");
+  if (!fs.existsSync(configPath)) {
+    const commonDirPath = path.join(gitDirectory, "commondir");
+    if (fs.existsSync(commonDirPath)) {
+      configPath = path.join(path.resolve(gitDirectory, fs.readFileSync(commonDirPath, "utf8").trim()), "config");
+    }
+  }
+  if (!fs.existsSync(configPath)) return null;
+  const config = fs.readFileSync(configPath, "utf8");
+  const origin = /\[remote\s+"origin"\]([\s\S]*?)(?=\n\s*\[|$)/i.exec(config)?.[1] || "";
+  return /^\s*url\s*=\s*(.+)$/im.exec(origin)?.[1]?.trim() || null;
+}
+
+export function getProjectIdentitySecret({ dataDir = null } = {}) {
+  const directory = workReceiptHome(dataDir);
+  const keyPath = path.join(directory, PROJECT_KEY_FILENAME);
+  fs.mkdirSync(directory, { recursive: true });
+  if (fs.existsSync(keyPath)) {
+    const value = fs.readFileSync(keyPath, "utf8").trim();
+    if (/^[a-f0-9]{64}$/i.test(value)) return Buffer.from(value, "hex");
+    throw new Error(`项目身份密钥无效：${keyPath}`);
+  }
+
+  const secret = crypto.randomBytes(32);
+  writeFileAtomicSync(keyPath, `${secret.toString("hex")}\n`);
+  try { fs.chmodSync(keyPath, 0o600); } catch {}
+  return secret;
+}
+
+export function projectDescriptorFromSessionMeta(payload, secret) {
+  if (!secret || !payload || typeof payload !== "object") return null;
+  const repositoryUrl = typeof payload.git?.repository_url === "string"
+    ? payload.git.repository_url
+    : null;
+  const cwd = typeof payload.cwd === "string" ? payload.cwd : null;
+  if (!repositoryUrl && !cwd) return null;
+
+  const identity = repositoryUrl
+    ? `repository:${normalizeRepositoryUrl(repositoryUrl)}`
+    : `directory:${normalizeWorkingDirectory(cwd)}`;
+  const label = repositoryUrl
+    ? projectLabelFromRepositoryUrl(repositoryUrl)
+    : path.basename(normalizeWorkingDirectory(cwd));
+  return {
+    projectId: projectIdForIdentity(identity, secret),
+    projectLabel: label || "Codex project",
+  };
+}
+
+export function projectDescriptorFromPath(value, secret) {
+  if (!secret) throw new Error("指定项目时缺少本地项目身份密钥");
+  const projectPath = normalizeWorkingDirectory(value);
+  if (!fs.existsSync(projectPath) || !fs.statSync(projectPath).isDirectory()) {
+    throw new Error(`项目目录不存在：${value}`);
+  }
+  const repositoryUrl = repositoryUrlFromConfig(gitDirectoryForProject(projectPath));
+  const identity = repositoryUrl
+    ? `repository:${normalizeRepositoryUrl(repositoryUrl)}`
+    : `directory:${projectPath}`;
+  return {
+    projectId: projectIdForIdentity(identity, secret),
+    projectLabel: repositoryUrl
+      ? projectLabelFromRepositoryUrl(repositoryUrl)
+      : path.basename(projectPath),
+  };
+}