codex-work-receipt 0.7.4 → 0.8.0

package/docs/miniprogram-file-import.md

@@ -0,0 +1,67 @@
+# 小程序文件导入实现
+
+<p><strong>中文</strong> · <a href="./miniprogram-file-import.en.md">English</a> · <a href="./mobile-import.md">返回手机导入</a></p>
+
+配套小程序源码不在本仓库中。本页定义 `cwr-file-v1` 的移动端接入边界；兼容夹具位于 `docs/fixtures/cwr-file-v1.json`。
+
+## 选择与读取
+
+```js
+const MAX_IMPORT_BYTES = 2 * 1024 * 1024;
+
+wx.chooseMessageFile({
+  count: 1,
+  type: "file",
+  extension: ["json", "cwr"],
+  success({ tempFiles }) {
+    const file = tempFiles[0];
+    if (!file || file.size > MAX_IMPORT_BYTES) return showFileTooLarge();
+    wx.getFileSystemManager().readFile({
+      filePath: file.path,
+      encoding: "utf8",
+      success: ({ data }) => previewReceiptFile(data),
+      fail: showReadError,
+    });
+  },
+});
+```
+
+用户取消选择不应显示错误。扩展名只用于过滤，不能代替内容校验。官方接口参考：[`wx.chooseMessageFile`](https://developers.weixin.qq.com/miniprogram/dev/api/media/image/wx.chooseMessageFile.html) 和 [`FileSystemManager.readFile`](https://developers.weixin.qq.com/miniprogram/dev/api/file/FileSystemManager.readFile.html)。
+
+## 校验顺序
+
+1. UTF-8 JSON 能够解析，顶层是普通对象。
+2. `format === "codex-work-receipt"`。
+3. `file_version === 1`；更高版本提示升级小程序。
+4. `payload_schema` 为 `cwr1` 或 `cwr2`，并与 `payload.v` 一致。
+5. 对规范化 payload JSON 计算 SHA-256，与 `integrity.digest` 比较。
+6. 严格校验 compact payload 的字段类型、数组长度、日期、时区和非负数值范围。
+7. cwr2 校验 `fact_count === facts.length`、factId 唯一性、manifest hash 和每个 content hash。
+8. 禁止把不可信对象直接合并到应用状态或对象原型。
+
+SHA-256 只校验文件是否被损坏，不代表官方签名。公开统计必须继续把客户端数据视为不可信数据。
+
+规范化必须与桌面端一致：递归按 JavaScript 默认字符串排序（UTF-16 code unit 顺序）排列对象键，保持数组顺序，用无空白 JSON 编码为 UTF-8 后计算 SHA-256。请先用 `docs/fixtures/cwr-file-v1.json` 验证实现得到相同 digest。
+
+## 预览与入库
+
+文件和二维码解码后都应得到同一种 compact payload，并进入同一个业务管线：
+
+```text
+validate → preview → confirm → deduplicate → persist
+```
+
+确认页至少展示：
+
+- `payload.o` 与 `payload.d` 对应的统计范围
+- `payload.s[0]` 会话数
+- cwr2 的 `payload.a[4]` canonical fact 数量；cwr1 标记为滚动摘要
+- 可以预计算时展示新增、更新、已存在数量
+
+用户确认前不得写入数据库。入库必须原子化；任一 fact 失败时整次导入失败，不留下部分记录。
+
+## 二维码兼容
+
+新版桌面端只生成完整的单个 `cwr1` 或 `cwr2` 数据码。小程序仍需保留 `cwr2p` 收集和重组能力，以导入旧版本已经生成的分片二维码。
+
+建议覆盖 iOS、Android、Windows 微信和 macOS 微信的文件传输助手流程，并测试取消、超大文件、损坏 JSON、错误 digest、未来版本、重复导入、重叠范围和 append-only 更新。

package/docs/mobile-import.en.md

@@ -1,21 +1,29 @@
-# Mobile QR import
+# Mobile file and single-QR import
 
 <p><a href="./mobile-import.md">中文</a> · <strong>English</strong> · <a href="../README.en.md">Back to README</a></p>
 
-The desktop page shows both the fixed mini-program code and a data QR code for the current receipt. The companion mini program validates the protocol and privacy-safe fields on the phone, then saves the private receipt to the user's anonymous account database:
+The desktop page always provides one `.cwr.json` WeChat import file. The fixed mini-program code only opens the companion app. A data QR appears only when the complete receipt safely fits in one code.
 
 1. Scan the fixed mini-program code in WeChat and open the companion mini program.
-2. Tap the desktop-import action.
-3. Scan the adjacent data QR code. Multipart receipts rotate one part at a time on the computer, while the mini program automatically reopens scanning until all parts are collected.
-4. Validate the `cwr1`, `cwr2`, or multipart `cwr2p` prefix, checksum, and schema version.
-5. Single codes decompress immediately. Multipart codes can arrive out of order, and missed parts are collected on the next rotation before the privacy-safe metrics are parsed.
-6. Recognize a session, today, last-seven-days, or this-week range. New receipts use canonical facts for deduplication and are stored in the anonymous account database by default.
-7. Render the selected template with Canvas and save it to the phone.
+2. Select “Download WeChat import file” in the desktop page.
+3. Send the `.cwr.json` file to WeChat File Transfer or one of your own chats.
+4. Tap “Import from chat file” in the mini program and select that file.
+5. Validate the file format, version, SHA-256 digest, payload schema, and privacy-safe fields.
+6. Preview the range, session count, and canonical fact count. Only deduplicate and persist after user confirmation.
+7. Render the selected template on Canvas and save it to the photo library.
 
-The phone keeps only multipart staging, pending database writes, and necessary caches. Saving a private receipt does not automatically join public statistics; participation in the AI Cooperative is a separate choice inside the companion mini program.
+The mini program should use `wx.chooseMessageFile` to select the chat file and `FileSystemManager.readFile` to read it as UTF-8. It must enforce its own product size limit, validate all untrusted input, and avoid partial writes before confirmation.
 
-The QR code does not transfer an image. The desktop page and mini program independently render the same structured receipt data. Older QR codes without an explicit range field remain supported through the legacy label fallback. QR payloads exclude prompts, response text, source code, project paths, file names, and original session IDs.
+## Optional single-code import
+
+When the complete `cwr1` or `cwr2` payload safely fits in one data QR, the page offers “Or import by scanning.” The single data code replaces the mini-program code, so two scannable codes are never shown at once. New `cwr2p` multipart codes are no longer generated.
+
+The updated mini program should continue decoding `cwr1`, `cwr2`, and historical `cwr2p` receipts for backwards compatibility.
+
+Neither files nor QR codes transfer an image. Desktop and mobile render the same privacy-safe structured data independently. Import data excludes prompts, response text, source code, project paths, file names, and original session IDs. Sending the file to a chat explicitly uses WeChat's file-transfer system, so send it only to a chat you trust.
+
+Saving a private receipt does not automatically join public statistics; participation in the AI Cooperative remains a separate choice.
 
 The companion mini program is a separate product. This repository does not contain its source code, AppID, backend code, or server credentials.
 
-See the [data schema and QR protocol](data-schema.en.md).
+See the [data schema, file, and QR protocol](data-schema.en.md). For implementation details, see [mini-program file import](miniprogram-file-import.en.md).

package/docs/mobile-import.md

@@ -1,21 +1,29 @@
-# 手机扫码导入
+# 手机文件与单码导入
 
 <p><strong>中文</strong> · <a href="./mobile-import.en.md">English</a> · <a href="../README.md">返回 README</a></p>
 
-桌面网页会同时展示固定小程序码和当前小票的数据二维码。配套小程序会先在手机端完成协议和隐私字段校验，再把私人小票保存到用户的匿名账号数据库：
+桌面网页始终提供一个 `.cwr.json` 微信导入文件。固定小程序码只负责打开配套小程序；数据足够小时，网页才额外提供一个完整的数据二维码。
 
 1. 微信扫描固定小程序码并打开配套小程序。
-2. 点击“从电脑导入”。
-3. 扫描网页旁边的数据二维码；多分片小票会在电脑上自动逐张轮播，小程序在未集齐时自动继续打开扫码。
-4. 小程序校验 `cwr1`、`cwr2` 或 `cwr2p` 分片前缀、checksum 和结构版本。
-5. 单码立即解压；多分片允许乱序、漏扫后等待下一轮补齐，全部到齐再解析脱敏统计数据。
-6. 识别单会话、今日、近七日或本周范围；新版小票按规范事实去重，完整记录默认保存到匿名账号数据库。
+2. 在桌面网页点击“下载微信导入文件”。
+3. 把 `.cwr.json` 发送到“文件传输助手”或自己的任意微信聊天。
+4. 在小程序中点击“从聊天文件导入”，选择刚才发送的文件。
+5. 小程序校验文件格式、版本、SHA-256、数据协议和隐私字段。
+6. 小程序先展示统计范围、会话数和 canonical fact 数量；用户确认后再按规范事实去重并入库。
 7. 使用 Canvas 重新绘制所选模板并保存到手机相册。
 
-手机本地只保留扫码分片、待入库记录和必要缓存。私人小票入库不等于自动加入公开统计；是否参与 AI 供销社匿名汇总由用户在配套小程序中单独决定。
+文件导入使用微信官方 `wx.chooseMessageFile` 选择聊天文件，再通过 `FileSystemManager.readFile` 以 UTF-8 读取。小程序应设置独立的产品大小上限、严格校验内容，并在确认前不写入任何数据。
 
-二维码不会传输图片。桌面端和小程序端根据同一份结构数据分别渲染小票；旧版二维码没有显式范围字段时仍按原有文案兼容识别。二维码不包含 Prompt、回复正文、代码、项目路径、文件名或原始会话 ID。
+## 可选的单码导入
+
+如果完整的 `cwr1` 或 `cwr2` 数据能安全放进一个二维码，网页会显示“也可以扫码导入”。点击后，唯一的数据二维码会替换小程序码；页面不会同时显示多个可扫描二维码，也不会生成新的 `cwr2p` 分片。
+
+新版小程序仍应保留 `cwr1`、`cwr2` 和历史 `cwr2p` 解码能力，确保旧小票能够继续导入。
+
+导入文件和二维码都不传输图片。桌面端和小程序端根据同一份脱敏结构数据分别渲染小票；它们不包含 Prompt、回复正文、代码、项目路径、文件名或原始会话 ID。把文件发送到聊天属于用户主动使用微信文件传输体系的行为，请只发送到可信聊天。
+
+私人小票入库不等于自动加入公开统计；是否参与 AI 供销社匿名汇总由用户在配套小程序中单独决定。
 
 配套小程序是独立产品，本仓库不包含其源码、AppID、后台代码或服务端密钥。
 
-协议细节见 [数据结构与二维码协议](data-schema.md)。
+协议细节见 [数据结构、文件与二维码协议](data-schema.md)。小程序开发接入见 [小程序文件导入实现](miniprogram-file-import.md)。

package/docs/privacy.en.md

@@ -21,14 +21,29 @@ Session logs are parsed locally in bounded chunks, one JSONL row at a time. Afte
 
 ## Where data is saved
 
-Generated HTML and JSON files are written to `codex-work-receipt-output/` by default. Deduplicated history is stored under `~/.codex-work-receipt/`. Use `--output` and `--data-dir` to change these locations.
+Generated HTML, full JSON, and privacy-safe `.cwr.json` WeChat import files are written to `codex-work-receipt-output/` by default. Deduplicated history is stored under `~/.codex-work-receipt/`. Use `--output` and `--data-dir` to change these locations.
 
 The runtime does not upload Codex session data to a project server. The initial or updated package download performed by `npx` is a normal package-manager network request and does not contain local session data.
 
-If the user actively scans a data QR code, the companion mini program saves the privacy-safe receipt to the user's anonymous account database for history recovery and canonical deduplication. This happens inside the companion product and does not upload prompts, response text, source code, project paths, file names, or original session IDs. Joining AI Cooperative aggregate statistics remains a separate user choice.
+If the user actively sends a `.cwr.json` file to a WeChat chat, that file passes through WeChat's file-transfer system. The user can then select it in the companion mini program, preview it, and save it to the anonymous account database for history recovery and canonical deduplication. The file excludes prompts, response text, source code, project paths, file names, and original session IDs. Joining AI Cooperative aggregate statistics remains a separate user choice.
 
-## QR payload
+## Automatic saving
 
-The QR code contains versioned, privacy-safe receipt metrics only. It does not contain the original session or an image. Treat the QR code as a scannable data file and share it only with people you trust.
+Automatic saving is an explicit opt-in local feature. Enabling it:
 
-See the [data schema and QR protocol](data-schema.en.md).
+- safely merges one Codex `Stop` hook into `~/.codex/hooks.json`
+- stores a stable offline runtime under `~/.codex-work-receipt/runtime/`
+- quietly refreshes the daily HTML, full JSON, and `.cwr.json` under `~/.codex-work-receipt/auto/YYYY-MM-DD/`
+- stores the selected mode and latest run state in `config.json` and `auto-state.json`
+
+The hook input includes the session identifier and event name supplied by Codex. The trigger script uses them only to confirm a valid `Stop` event; receipt statistics still use the existing local privacy-filtering parser. The hook does not upload sessions, send WeChat files, or continuously monitor other applications. Each trigger starts one short-lived local process that exits after generation.
+
+Switching to manual-only mode removes this tool's hook without deleting receipt history or changing unrelated hooks. An existing `hooks.json` is backed up before changes. If it is not valid JSON, setup stops instead of replacing it. Codex also asks users to review non-managed hooks through its own hook trust flow.
+
+## Import files and QR payloads
+
+The import file and optional single data QR contain versioned, privacy-safe receipt metrics only. They do not contain the original session or an image. Scan import appears only when the complete payload fits in one code; the desktop no longer creates new multipart QR codes. Send files only to chats you trust and show data codes only to people you trust.
+
+Automatic mode does not generate a data QR. It maintains only the `.cwr.json` import file that the user may choose to send through WeChat.
+
+See the [data schema, file, and QR protocol](data-schema.en.md).

package/docs/privacy.md

@@ -21,14 +21,29 @@ AI 打工小票在本机读取 Codex 会话，并在本机完成统计和渲染
 
 ## 会保存在哪里
 
-生成的 HTML 和 JSON 默认位于当前目录的 `codex-work-receipt-output/`，去重历史保存在 `~/.codex-work-receipt/`。可以使用 `--output` 和 `--data-dir` 修改位置。
+生成的 HTML、完整 JSON 和脱敏 `.cwr.json` 微信导入文件默认位于当前目录的 `codex-work-receipt-output/`，去重历史保存在 `~/.codex-work-receipt/`。可以使用 `--output` 和 `--data-dir` 修改位置。
 
 运行期间不会把 Codex 会话数据上传到本项目的服务器。通过 `npx` 首次下载或更新 npm 包属于包管理器的正常网络请求，不包含本地会话内容。
 
-如果用户主动扫描数据二维码，配套小程序会把二维码中的脱敏小票保存到用户的匿名账号数据库，用于历史恢复和规范去重。这一步发生在配套小程序中，不会上传 Prompt、回复正文、代码、项目路径、文件名或原始会话 ID；是否参与 AI 供销社匿名统计仍由用户单独决定。
+如果用户主动把 `.cwr.json` 发送到微信聊天，文件会经过微信的文件传输体系。随后用户可在配套小程序中选择该聊天文件、确认内容并保存到匿名账号数据库，用于历史恢复和规范去重。文件不会包含 Prompt、回复正文、代码、项目路径、文件名或原始会话 ID；是否参与 AI 供销社匿名统计仍由用户单独决定。
 
-## 二维码
+## 自动保存
 
-二维码只包含当前小票的版本化脱敏统计，不包含原始会话或图片。二维码等同于一份可扫描的数据文件，请只向信任的人展示。
+自动保存是明确选择加入的本地功能。启用后会：
 
-格式说明见 [数据结构与二维码协议](data-schema.md)。
+- 在 `~/.codex/hooks.json` 中安全合并一个 Codex `Stop` Hook
+- 在 `~/.codex-work-receipt/runtime/` 保存一份稳定的离线运行器
+- 在 `~/.codex-work-receipt/auto/YYYY-MM-DD/` 静默刷新当天的 HTML、完整 JSON 和 `.cwr.json`
+- 在 `config.json` 和 `auto-state.json` 中保存模式与最近运行状态
+
+Hook 输入包含 Codex 提供的会话标识和事件名称；触发脚本只用它确认这是一次有效的 `Stop` 事件，实际统计仍通过本机已有的隐私过滤解析器完成。Hook 不会上传会话、自动发送微信文件或持续监控其他应用。每次触发只启动短生命周期的本地进程，完成后退出。
+
+切换到仅手动模式会移除本工具添加的 Hook，不会删除历史小票或修改其他 Hook。已有 `hooks.json` 在变更前会备份；如果它不是有效 JSON，安装会停止而不是覆盖文件。Codex 还会要求用户按自身 Hook 信任机制审查非托管 Hook。
+
+## 导入文件与二维码
+
+导入文件和可选的单个数据二维码只包含当前小票的版本化脱敏统计，不包含原始会话或图片。只有完整载荷能放进一个二维码时才提供扫码导入；桌面端不再生成新的多分片二维码。请只把导入文件发送到可信聊天，也只向信任的人展示数据二维码。
+
+自动模式不生成数据二维码，只维护可由用户主动发送到微信的 `.cwr.json` 导入文件。
+
+格式说明见 [数据结构、文件与二维码协议](data-schema.md)。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-work-receipt",
-  "version": "0.7.4",
+  "version": "0.8.0",
   "type": "module",
   "description": "Generate a privacy-first Codex work receipt from local session metadata.",
   "author": "a-bai-2026",
@@ -27,7 +27,7 @@
   "scripts": {
     "receipt": "node src/cli.mjs",
     "test": "node --test",
-    "check": "node --check src/cli.mjs && node --check src/core/skill-installer.mjs && node --check src/core/pet-installer.mjs && node --check src/core/range.mjs",
+    "check": "node --check src/cli.mjs && node --check src/auto-hook.mjs && node --check src/auto-runner.mjs && node --check src/core/auto-mode.mjs && node --check src/core/generator.mjs && node --check src/core/mode-selector.mjs && node --check src/lib/files.mjs && node --check src/core/skill-installer.mjs && node --check src/core/pet-installer.mjs && node --check src/core/range.mjs",
     "prepublishOnly": "npm test && npm run check"
   },
   "files": [

package/skills/ai-work-receipt/SKILL.md

@@ -39,13 +39,13 @@ npx --yes codex-work-receipt@latest --latest --lang zh-CN --theme classic
 Replace only the mode and optional flags according to the request.
 
 3. Let the CLI open the generated HTML unless the user requested `--no-open`.
-4. On success, report the HTML path and tell the user to scan the official mini-program code first, then the adjacent data QR code.
+4. On success, report both the HTML path and the `.cwr.json` WeChat import file path. Tell the user to send the import file to WeChat File Transfer, open the official mini program, and choose “Import from chat file”. If the CLI reports that a single data QR is available, mention scanning as an optional shortcut; never instruct the user to scan multipart codes.
 5. When `--hours` was used, explicitly state that the receipt is a private rolling summary and will not enter AI Work Cooperative statistics.
 
 ## Privacy and failures
 
 - Do not read, quote, summarize, or expose prompt text, response text, code, project paths, or file names from Codex sessions.
-- Do not upload session data or add custom mini-program codes. The CLI reads numerical metadata locally and uses the fixed official mini-program code.
+- Do not upload session data or add custom mini-program codes. The CLI reads numerical metadata locally and uses the fixed official mini-program code. Sending the privacy-safe `.cwr.json` file through WeChat is an explicit user action, not an automatic CLI upload.
 - If `npx` needs network permission to fetch the package, request the narrow permission needed to run it.
 - If no Codex session is found, report that the user must complete at least one Codex task locally before generating a receipt.
 - If generation fails, return the CLI error concisely and do not claim that a receipt was created.

package/src/auto-hook.mjs

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+function argumentValue(name) {
+  const index = process.argv.indexOf(name);
+  return index >= 0 ? process.argv[index + 1] : null;
+}
+
+async function readStdin() {
+  let value = "";
+  for await (const chunk of process.stdin) value += chunk;
+  return value;
+}
+
+async function main() {
+  try {
+    const workReceiptHome = argumentValue("--work-receipt-home");
+    if (!workReceiptHome) return;
+    const input = JSON.parse(await readStdin());
+    if (input?.hook_event_name !== "Stop" || !input?.session_id) return;
+
+    const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+    const runnerEntry = path.join(scriptDir, "auto-runner.mjs");
+    if (!fs.existsSync(runnerEntry)) return;
+    const child = spawn(process.execPath, [
+      runnerEntry,
+      "--work-receipt-home",
+      workReceiptHome,
+      "--triggered-at",
+      new Date().toISOString(),
+    ], {
+      detached: true,
+      stdio: "ignore",
+      env: process.env,
+    });
+    child.unref();
+  } catch {
+    // Automatic receipt failures must never interrupt the Codex turn.
+  }
+}
+
+await main();

package/src/auto-runner.mjs

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  automaticOutputPath,
+  readAutoConfig,
+  readAutoState,
+  writeAutoState,
+} from "./core/auto-mode.mjs";
+import { dateKey } from "./lib/time.mjs";
+
+const LOCK_STALE_MS = 10 * 60 * 1000;
+
+function argumentValue(name) {
+  const index = process.argv.indexOf(name);
+  return index >= 0 ? process.argv[index + 1] : null;
+}
+
+function delay(milliseconds) {
+  return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+
+function emptyActivityError(error) {
+  return /没有找到|No Codex sessions found/.test(String(error?.message || ""));
+}
+
+function pendingTime(pendingPath, fallback = new Date()) {
+  try {
+    const value = new Date(fs.readFileSync(pendingPath, "utf8").trim());
+    return Number.isNaN(value.getTime()) ? fallback : value;
+  } catch {
+    return fallback;
+  }
+}
+
+function crossesConfiguredDay(workReceiptHome, left, right) {
+  const config = readAutoConfig({ workReceiptHome });
+  const timezone = config?.preferences?.timezone || "Asia/Shanghai";
+  return dateKey(left, timezone) !== dateKey(right, timezone);
+}
+
+function acquireLock(lockPath, pendingPath) {
+  fs.mkdirSync(path.dirname(lockPath), { recursive: true });
+  try {
+    const descriptor = fs.openSync(lockPath, "wx");
+    fs.writeFileSync(descriptor, `${JSON.stringify({ pid: process.pid, created_at: new Date().toISOString() })}\n`);
+    fs.closeSync(descriptor);
+    return true;
+  } catch (error) {
+    if (error.code !== "EEXIST") throw error;
+    try {
+      const age = Date.now() - fs.statSync(lockPath).mtimeMs;
+      if (age > LOCK_STALE_MS) {
+        fs.rmSync(lockPath, { force: true });
+        return acquireLock(lockPath, pendingPath);
+      }
+    } catch {
+      // Another worker may have released the lock between checks.
+    }
+    fs.writeFileSync(pendingPath, `${new Date().toISOString()}\n`, "utf8");
+    return false;
+  }
+}
+
+async function generateOnce({ workReceiptHome, now = new Date() }) {
+  const config = readAutoConfig({ workReceiptHome });
+  if (!config || config.mode !== "automatic") return { status: "disabled" };
+
+  const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+  const projectDir = path.dirname(scriptDir);
+  const vendorScript = path.join(projectDir, "vendor", "dom-to-image-more.min.js");
+  if (fs.existsSync(vendorScript)) process.env.CODEX_WORK_RECEIPT_DOM_TO_IMAGE = vendorScript;
+  process.env.CODEX_WORK_RECEIPT_HOME = workReceiptHome;
+
+  const previousState = readAutoState({ workReceiptHome }) || {};
+  const attemptedAt = new Date().toISOString();
+  try {
+    const { generateReceipt } = await import("./core/generator.mjs");
+    const outputFile = automaticOutputPath(config, now);
+    const generated = await generateReceipt({
+      mode: "today",
+      sessionId: null,
+      hours: null,
+      timezone: config.preferences?.timezone || "Asia/Shanghai",
+      locale: config.preferences?.locale || "zh-CN",
+      theme: config.preferences?.theme || "classic",
+      output: outputFile,
+      dataDir: workReceiptHome,
+    }, {
+      projectDir,
+      now,
+      codexHome: config.hook?.codex_home || null,
+    });
+    const state = {
+      state_version: 1,
+      status: "ok",
+      last_attempt_at: attemptedAt,
+      last_success_at: new Date().toISOString(),
+      output_file: generated.outputFile,
+      structured_file: generated.persisted.companionPath,
+      import_file: generated.persisted.transferPath,
+      receipt_id: generated.record.id,
+      snapshot_hash: generated.record.source.snapshot_hash,
+      error: null,
+    };
+    writeAutoState({ workReceiptHome }, state);
+    return state;
+  } catch (error) {
+    const state = {
+      ...previousState,
+      state_version: 1,
+      status: emptyActivityError(error) ? "waiting" : "error",
+      last_attempt_at: attemptedAt,
+      error: String(error?.message || error),
+    };
+    writeAutoState({ workReceiptHome }, state);
+    return state;
+  }
+}
+
+export async function runAutomaticReceipt({ workReceiptHome, now = new Date(), retryAfterCoalesce = true }) {
+  const lockPath = path.join(workReceiptHome, "auto.lock");
+  const pendingPath = path.join(workReceiptHome, "auto.pending");
+  if (!acquireLock(lockPath, pendingPath)) {
+    if (!retryAfterCoalesce) return { status: "coalesced" };
+    await delay(800);
+    if (fs.existsSync(lockPath)) return { status: "coalesced" };
+    return runAutomaticReceipt({
+      workReceiptHome,
+      now: pendingTime(pendingPath),
+      retryAfterCoalesce: false,
+    });
+  }
+
+  try {
+    await delay(350);
+    const pendingBeforeRun = fs.existsSync(pendingPath) ? pendingTime(pendingPath) : null;
+    fs.rmSync(pendingPath, { force: true });
+    let result = await generateOnce({ workReceiptHome, now });
+    if (pendingBeforeRun && crossesConfiguredDay(workReceiptHome, now, pendingBeforeRun)) {
+      result = await generateOnce({ workReceiptHome, now: pendingBeforeRun });
+    }
+    if (fs.existsSync(pendingPath)) {
+      const nextRunAt = pendingTime(pendingPath);
+      fs.rmSync(pendingPath, { force: true });
+      await delay(350);
+      result = await generateOnce({ workReceiptHome, now: nextRunAt });
+    }
+    return result;
+  } finally {
+    fs.rmSync(lockPath, { force: true });
+  }
+}
+
+async function main() {
+  const workReceiptHome = argumentValue("--work-receipt-home");
+  if (!workReceiptHome) return;
+  const triggeredAtValue = new Date(argumentValue("--triggered-at") || Date.now());
+  const triggeredAt = Number.isNaN(triggeredAtValue.getTime()) ? new Date() : triggeredAtValue;
+  try {
+    await runAutomaticReceipt({ workReceiptHome: path.resolve(workReceiptHome), now: triggeredAt });
+  } catch {
+    // Automatic receipt failures must never interrupt the Codex turn.
+  }
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  await main();
+}