@liuyoumi/codex-history 0.1.2 → 0.1.4

package/CHANGELOG.md

@@ -1,12 +1,31 @@
 # Changelog
 
+## 0.1.4 - 2026-05-29
+
+### Added
+
+- Add `purge-orphans` for guarded cleanup of missing-rollout threads and logs-only orphan records.
+- Report estimated local disk space affected by orphan cleanup.
+
+## 0.1.3 - 2026-05-29
+
+### Changed
+
+- Remove purge backup creation and document `purge` as a permanent local deletion flow.
+- Report the CLI version from `package.json` instead of a stale hard-coded value.
+
+### Documentation
+
+- Refresh the README cover image to show only the terminal window.
+- Add agent workflow guidance for future implementation work.
+- Clarify the boundary between `AGENTS.md` and `docs/agent-workflow.md`.
+
 ## 0.1.2 - 2026-05-28
 
 ### Documentation
 
 - Use Chinese as the default README language.
 - Add an English README translation.
-- Refresh the README cover image to focus on a single guarded `purge` command flow.
 - Add README badges and clearer macOS, Windows, and Linux support notes.
 
 ## 0.1.1 - 2026-05-28
@@ -28,7 +47,7 @@ Initial release candidate.
 - `purge <id>` execution by full id or unique short id prefix.
 - Interactive purge confirmation by typing the standard short id.
 - `purge <id> --force` for non-interactive execution.
-- Guarded purge execution with mandatory backups.
+- Guarded purge execution with explicit confirmation.
 - SQLite cleanup for supported Codex stores.
 - JSON and JSONL state cleanup for supported Codex files.
 - Rollout jsonl and shell snapshot deletion.

package/README.en.md

@@ -4,7 +4,7 @@
   <img alt="npm" src="https://img.shields.io/npm/v/@liuyoumi/codex-history?style=flat-square&color=cb9b27" />
   <img alt="platform" src="https://img.shields.io/badge/platform-macOS%20%7C%20Windows%20%7C%20Linux-2ea043?style=flat-square" />
   <img alt="local only" src="https://img.shields.io/badge/local%20data-only-6e7681?style=flat-square" />
-  <img alt="backup" src="https://img.shields.io/badge/backup-before%20purge-0969da?style=flat-square" />
+  <img alt="confirm" src="https://img.shields.io/badge/confirm-before%20purge-0969da?style=flat-square" />
   <img alt="license" src="https://img.shields.io/npm/l/@liuyoumi/codex-history?style=flat-square" />
 </p>
 
@@ -18,7 +18,7 @@
 
 A small CLI for finding and removing local Codex conversation history.
 
-`codex-history` works on local Codex data files on your machine. It lists conversations using the same short titles shown by Codex when available, lets you narrow the list with `--grep`, and deletes one resolved conversation only after confirmation.
+`codex-history` works on local Codex data files on your machine. It lists conversations using the same short titles shown by Codex when available, lets you narrow the list with `--grep`, and deletes resolved conversations or orphaned data only after confirmation.
 
 ## Install
 
@@ -34,7 +34,7 @@ npx @liuyoumi/codex-history doctor
 
 ## Supported Platforms
 
-`codex-history` has been checked on macOS, Windows, and Linux for install, `doctor`, `list` / `--grep`, and guarded `purge` workflows with confirmation and backups.
+`codex-history` has been checked on macOS, Windows, and Linux for install, `doctor`, `list` / `--grep`, and guarded `purge` workflows with confirmation.
 
 | Platform | Status |
 | --- | --- |
@@ -51,6 +51,7 @@ codex-history doctor
 codex-history list
 codex-history list --grep "Astro"
 codex-history purge 019e6885
+codex-history purge-orphans
 ```
 
 `purge` prints the resolved conversation and asks you to type the standard short id before it deletes anything:
@@ -63,7 +64,7 @@ id: 019e6885-b5ae-7ae0-a50d-ce5f75b0ac08
 cwd: /Users/me/Projects/example
 updated: 2026-05-28T03:16:01.959Z
 
-A backup will be created before deletion.
+This cannot be undone.
 Type 019e6885 to confirm:
 ```
 
@@ -75,6 +76,7 @@ Type 019e6885 to confirm:
 | `codex-history list` | List local conversations. |
 | `codex-history list --grep <keyword>` | Filter conversations by title, id, or cwd. |
 | `codex-history purge <id>` | Remove one resolved local conversation after confirmation. |
+| `codex-history purge-orphans` | Remove orphaned local data after confirmation. |
 
 ### `doctor`
 
@@ -139,7 +141,27 @@ For scripts or non-interactive shells, use `--force`:
 codex-history purge 019e6885 --force
 ```
 
-`--force` skips only the interactive short-id confirmation. It still keeps schema validation, mandatory backup, active-thread protection, and post-purge verification.
+`--force` skips only the interactive short-id confirmation. It still keeps schema validation, active-thread protection, and post-purge verification.
+
+### `purge-orphans`
+
+Remove orphaned local data: conversations whose `state_5.sqlite.threads.rollout_path` points to a missing session or archived session file, and logs-only records that remain in `logs_2.sqlite.logs` without a matching thread in the `threads` table.
+
+```bash
+codex-history purge-orphans
+```
+
+The command first prints a cleanup plan, affected SQLite row counts, files to delete, and an estimated local disk space impact. You must type `purge-orphans` before it executes.
+
+For scripts or non-interactive shells, use `--force`:
+
+```bash
+codex-history purge-orphans --force
+```
+
+`--force` skips only interactive confirmation. It still keeps schema validation, active-thread protection, and post-purge verification. `purge-orphans` does not support JSON output.
+
+Space reporting is an estimate. After SQLite rows are deleted, database files may not shrink until Codex or another SQLite maintenance step runs vacuum.
 
 ## Options
 
@@ -151,6 +173,7 @@ codex-history --json purge 019e6885 --force
 
 - `--codex-home` defaults to `~/.codex`.
 - `--json` prints machine-readable output. For `purge`, JSON output requires `--force` because interactive confirmation is text-only.
+- `purge-orphans` does not support JSON output.
 - Color is enabled only in interactive terminals and respects `NO_COLOR`.
 
 ## Safety
@@ -160,7 +183,6 @@ Before deleting, `codex-history`:
 - validates the supported Codex data model
 - resolves the target to exactly one conversation
 - refuses the currently active thread when detectable
-- creates a mandatory backup under `~/.codex-history/backups`
 - removes known references from supported local Codex stores
 - verifies supported stores after mutation
 
@@ -174,13 +196,9 @@ If Codex Desktop is already showing the conversation you purge, quit or restart
 
 No. It only modifies supported local files on your machine.
 
-### Where are backups stored?
-
-Backups are written under `~/.codex-history/backups`.
-
 ### Can I recover a purged conversation?
 
-The tool creates a backup before deletion, but v0.1 does not include an automatic restore command. Treat `purge` as destructive.
+Not with this tool. Treat `purge` as destructive.
 
 ### Do I need to restart Codex after purging?
 

package/README.md

@@ -4,7 +4,7 @@
   <img alt="npm" src="https://img.shields.io/npm/v/@liuyoumi/codex-history?style=flat-square&color=cb9b27" />
   <img alt="platform" src="https://img.shields.io/badge/platform-macOS%20%7C%20Windows%20%7C%20Linux-2ea043?style=flat-square" />
   <img alt="local only" src="https://img.shields.io/badge/local%20data-only-6e7681?style=flat-square" />
-  <img alt="backup" src="https://img.shields.io/badge/backup-before%20purge-0969da?style=flat-square" />
+  <img alt="confirm" src="https://img.shields.io/badge/confirm-before%20purge-0969da?style=flat-square" />
   <img alt="license" src="https://img.shields.io/npm/l/@liuyoumi/codex-history?style=flat-square" />
 </p>
 
@@ -18,7 +18,7 @@
 
 一个用来查找并删除本地 Codex 对话历史的小型命令行工具。
 
-`codex-history` 只处理你机器上的本地 Codex 数据。它会尽量使用 Codex 对话列表里显示的短标题，支持用 `--grep` 缩小范围，并且只会在你确认目标后删除一条明确解析出来的对话。
+`codex-history` 只处理你机器上的本地 Codex 数据。它会尽量使用 Codex 对话列表里显示的短标题，支持用 `--grep` 缩小范围，并且只会在你确认目标后删除明确解析出来的对话或孤儿数据。
 
 ## 安装
 
@@ -34,7 +34,7 @@ npx @liuyoumi/codex-history doctor
 
 ## 支持平台
 
-`codex-history` 已在 macOS、Windows、Linux 上完成基础流程验证，包括安装、`doctor`、`list` / `--grep`，以及带确认和备份保护的 `purge`。
+`codex-history` 已在 macOS、Windows、Linux 上完成基础流程验证，包括安装、`doctor`、`list` / `--grep`，以及带确认保护的 `purge`。
 
 | 平台 | 状态 |
 | --- | --- |
@@ -51,6 +51,7 @@ codex-history doctor
 codex-history list
 codex-history list --grep "Astro"
 codex-history purge 019e6885
+codex-history purge-orphans
 ```
 
 `purge` 会先展示解析到的对话信息，并要求你输入标准短 id，确认后才会删除：
@@ -63,7 +64,7 @@ id: 019e6885-b5ae-7ae0-a50d-ce5f75b0ac08
 cwd: /Users/me/Projects/example
 updated: 2026-05-28T03:16:01.959Z
 
-A backup will be created before deletion.
+This cannot be undone.
 Type 019e6885 to confirm:
 ```
 
@@ -75,6 +76,7 @@ Type 019e6885 to confirm:
 | `codex-history list` | 列出本地对话。 |
 | `codex-history list --grep <keyword>` | 按标题、id 或 cwd 过滤对话。 |
 | `codex-history purge <id>` | 确认后删除一条解析到的本地对话。 |
+| `codex-history purge-orphans` | 确认后清理本地孤儿数据。 |
 
 ### `doctor`
 
@@ -139,7 +141,27 @@ codex-history purge 019e6885
 codex-history purge 019e6885 --force
 ```
 
-`--force` 只跳过交互式短 id 确认，不会跳过数据结构校验、强制备份、active thread 保护和删除后的验证。
+`--force` 只跳过交互式短 id 确认，不会跳过数据结构校验、active thread 保护和删除后的验证。
+
+### `purge-orphans`
+
+清理本地孤儿数据：包括 `state_5.sqlite.threads.rollout_path` 指向的 session / archived session 文件已经不存在的对话，以及只残留在 `logs_2.sqlite.logs` 中、但 `threads` 表里已经没有对应 thread 的日志记录。
+
+```bash
+codex-history purge-orphans
+```
+
+该命令会先展示清理计划、受影响的 SQLite 行数、将删除的文件数量，以及估算的本地磁盘空间影响。确认后需要输入 `purge-orphans` 才会执行。
+
+脚本或非交互环境可以使用 `--force`：
+
+```bash
+codex-history purge-orphans --force
+```
+
+`--force` 只跳过交互确认，不会跳过数据结构校验、active thread 保护和删除后的验证。`purge-orphans` 不支持 JSON 输出。
+
+空间统计是估算值。SQLite 删除记录后，数据库文件可能不会立刻缩小，直到 Codex 或其他 SQLite 维护步骤执行 vacuum。
 
 ## 选项
 
@@ -151,6 +173,7 @@ codex-history --json purge 019e6885 --force
 
 - `--codex-home` 默认是 `~/.codex`。
 - `--json` 输出机器可读的 JSON。`purge` 使用 JSON 输出时必须加 `--force`，因为交互确认只适合文本模式。
+- `purge-orphans` 不支持 JSON 输出。
 - 颜色只会在交互式终端中启用，并遵守 `NO_COLOR`。
 
 ## 安全机制
@@ -160,7 +183,6 @@ codex-history --json purge 019e6885 --force
 - 校验当前 Codex 本地数据结构是否受支持
 - 将目标解析到唯一一条对话
 - 在可检测时拒绝删除当前 active thread
-- 在 `~/.codex-history/backups` 下创建强制备份
 - 从受支持的本地 Codex 数据中移除已知引用
 - 删除后扫描受支持的数据存储，确认目标引用已经移除
 
@@ -174,13 +196,9 @@ codex-history --json purge 019e6885 --force
 
 不会。它只修改你机器上受支持的本地文件。
 
-### 备份在哪里？
-
-备份会写入 `~/.codex-history/backups`。
-
 ### 删除后还能恢复吗？
 
-工具会在删除前创建备份，但 v0.1 还没有自动恢复命令。请把 `purge` 当作破坏性操作对待。
+不能通过这个工具恢复。请把 `purge` 当作破坏性操作对待。
 
 ### 删除后需要重启 Codex 吗？
 

package/dist/cli.js

@@ -3,11 +3,11 @@
 // src/cli.ts
 import { Command } from "commander";
 import { spawnSync } from "child_process";
+import { readFileSync as readFileSync5 } from "fs";
 import { createInterface } from "readline/promises";
 
 // src/core/schema.ts
-import { mkdirSync, readFileSync } from "fs";
-import { dirname } from "path";
+import { readFileSync } from "fs";
 
 // src/core/paths.ts
 import { existsSync } from "fs";
@@ -22,13 +22,10 @@ function expandHome(input) {
   }
   return input;
 }
-function resolvePaths(codexHomeInput, toolHomeInput) {
+function resolvePaths(codexHomeInput) {
   const codexHome = path.resolve(expandHome(codexHomeInput ?? "~/.codex"));
-  const toolHome = path.resolve(expandHome(toolHomeInput ?? process.env.CODEX_HISTORY_HOME ?? "~/.codex-history"));
   return {
     codexHome,
-    toolHome,
-    backupHome: path.join(toolHome, "backups"),
     stateDb: path.join(codexHome, "state_5.sqlite"),
     logsDb: path.join(codexHome, "logs_2.sqlite"),
     goalsDb: path.join(codexHome, "goals_1.sqlite"),
@@ -122,18 +119,15 @@ function runDoctor(paths) {
   checks.push(checkJsonFile(paths.globalState, "global_state"));
   checks.push(checkJsonFile(paths.globalStateBackup, "global_state_backup"));
   checks.push(checkJsonlFile(paths.sessionIndex, "session_index"));
-  checks.push(checkBackupHome(paths.backupHome));
   return {
     supported: !checks.some((check) => check.status === "error"),
     codexHome: paths.codexHome,
     checks
   };
 }
-function validateSupportedDataModel(paths, options = {}) {
+function validateSupportedDataModel(paths) {
   const report = runDoctor(paths);
-  const errors = report.checks.filter(
-    (check) => check.status === "error" && (options.requireBackupHome || check.name !== "backup_home")
-  );
+  const errors = report.checks.filter((check) => check.status === "error");
   if (errors.length > 0) {
     const details = errors.map((check) => `${check.name}: ${check.detail}`).join("; ");
     throw new Error(`Unsupported Codex data model: ${details}`);
@@ -255,23 +249,6 @@ function checkJsonlFile(filePath, name) {
     };
   }
 }
-function checkBackupHome(backupHome) {
-  try {
-    mkdirSync(dirname(backupHome), { recursive: true });
-    mkdirSync(backupHome, { recursive: true });
-    return {
-      name: "backup_home",
-      status: "ok",
-      detail: backupHome
-    };
-  } catch (error) {
-    return {
-      name: "backup_home",
-      status: "error",
-      detail: error instanceof Error ? error.message : String(error)
-    };
-  }
-}
 
 // src/commands/doctor.ts
 function doctorCommand(paths) {
@@ -393,7 +370,7 @@ function listCommand(paths, options = {}) {
 }
 
 // src/core/executor.ts
-import { existsSync as existsSync9 } from "fs";
+import { existsSync as existsSync8 } from "fs";
 
 // src/safety/active-thread.ts
 import { existsSync as existsSync4, statSync } from "fs";
@@ -450,71 +427,8 @@ function assertThreadIsNotActive(target) {
   return checks;
 }
 
-// src/safety/backup.ts
-import { copyFileSync, existsSync as existsSync5, mkdirSync as mkdirSync2, statSync as statSync2, writeFileSync } from "fs";
-import path2 from "path";
-function createBackup(paths, plan) {
-  const timestamp = (/* @__PURE__ */ new Date()).toISOString().replaceAll(/[:.]/g, "-");
-  const backupDir = path2.join(paths.backupHome, `${timestamp}-${plan.target.id}`);
-  mkdirSync2(backupDir, { recursive: true });
-  const candidates = /* @__PURE__ */ new Set();
-  candidates.add(paths.stateDb);
-  addIfPresent(candidates, `${paths.stateDb}-wal`);
-  addIfPresent(candidates, `${paths.stateDb}-shm`);
-  addIfPresent(candidates, paths.logsDb);
-  addIfPresent(candidates, `${paths.logsDb}-wal`);
-  addIfPresent(candidates, `${paths.logsDb}-shm`);
-  addIfPresent(candidates, paths.goalsDb);
-  addIfPresent(candidates, `${paths.goalsDb}-wal`);
-  addIfPresent(candidates, `${paths.goalsDb}-shm`);
-  addIfPresent(candidates, paths.sessionIndex);
-  addIfPresent(candidates, paths.globalState);
-  addIfPresent(candidates, paths.globalStateBackup);
-  addIfPresent(candidates, plan.target.rolloutPath);
-  for (const store of plan.stores) {
-    if (store.store === "shell_snapshot") {
-      addIfPresent(candidates, store.path);
-    }
-  }
-  const entries = [];
-  for (const originalPath of candidates) {
-    if (!existsSync5(originalPath)) {
-      continue;
-    }
-    const backupPath = uniqueBackupPath(backupDir, originalPath);
-    mkdirSync2(path2.dirname(backupPath), { recursive: true });
-    copyFileSync(originalPath, backupPath);
-    const stats = statSync2(originalPath);
-    entries.push({
-      originalPath,
-      backupPath,
-      size: stats.size,
-      mtimeMs: stats.mtimeMs
-    });
-  }
-  const manifest = {
-    threadId: plan.target.id,
-    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
-    backupDir,
-    entries
-  };
-  writeFileSync(path2.join(backupDir, "manifest.json"), JSON.stringify(manifest, null, 2) + "\n");
-  return manifest;
-}
-function addIfPresent(paths, filePath) {
-  if (existsSync5(filePath)) {
-    paths.add(filePath);
-  }
-}
-function uniqueBackupPath(backupDir, originalPath) {
-  const parsed = path2.parse(originalPath);
-  const safeBase = `${parsed.name}${parsed.ext}`.replaceAll(/[^a-zA-Z0-9._-]/g, "_");
-  const hash = Buffer.from(originalPath).toString("base64url").slice(0, 12);
-  return path2.join(backupDir, `${hash}-${safeBase}`);
-}
-
 // src/safety/verify.ts
-import { existsSync as existsSync6, readFileSync as readFileSync3 } from "fs";
+import { existsSync as existsSync5, readFileSync as readFileSync3 } from "fs";
 function verifyPurge(paths, plan) {
   const remainingReferences = [];
   const threadId = plan.target.id;
@@ -524,7 +438,7 @@ function verifyPurge(paths, plan) {
   checkTextFile(paths.sessionIndex, "session_index", threadId, remainingReferences);
   checkTextFile(paths.globalState, "global_state", threadId, remainingReferences);
   checkTextFile(paths.globalStateBackup, "global_state_backup", threadId, remainingReferences);
-  if (existsSync6(plan.target.rolloutPath)) {
+  if (existsSync5(plan.target.rolloutPath)) {
     remainingReferences.push({
       store: "rollout_jsonl",
       path: plan.target.rolloutPath,
@@ -532,7 +446,7 @@ function verifyPurge(paths, plan) {
     });
   }
   for (const store of plan.stores) {
-    if (store.store === "shell_snapshot" && existsSync6(store.path)) {
+    if (store.store === "shell_snapshot" && existsSync5(store.path)) {
       remainingReferences.push({
         store: "shell_snapshot",
         path: store.path,
@@ -546,7 +460,7 @@ function verifyPurge(paths, plan) {
   };
 }
 function checkSqlite(filePath, store, threadId, remainingReferences) {
-  if (!existsSync6(filePath)) {
+  if (!existsSync5(filePath)) {
     return;
   }
   const db = openReadonlyDatabase(filePath);
@@ -578,7 +492,7 @@ function checkSqlite(filePath, store, threadId, remainingReferences) {
   }
 }
 function checkTextFile(filePath, store, threadId, remainingReferences) {
-  if (!existsSync6(filePath)) {
+  if (!existsSync5(filePath)) {
     return;
   }
   const content = readFileSync3(filePath, "utf8");
@@ -592,9 +506,9 @@ function checkTextFile(filePath, store, threadId, remainingReferences) {
 }
 
 // src/stores/files.ts
-import { existsSync as existsSync7, unlinkSync } from "fs";
+import { existsSync as existsSync6, unlinkSync } from "fs";
 function deleteFileIfExists(filePath) {
-  if (!existsSync7(filePath)) {
+  if (!existsSync6(filePath)) {
     return {
       path: filePath,
       deleted: false
@@ -608,9 +522,9 @@ function deleteFileIfExists(filePath) {
 }
 
 // src/stores/json-state.ts
-import { existsSync as existsSync8, readFileSync as readFileSync4, writeFileSync as writeFileSync2 } from "fs";
+import { existsSync as existsSync7, readFileSync as readFileSync4, writeFileSync } from "fs";
 function removeThreadFromSessionIndex(filePath, threadId) {
-  if (!existsSync8(filePath)) {
+  if (!existsSync7(filePath)) {
     return { path: filePath, changed: false };
   }
   const original = readFileSync4(filePath, "utf8");
@@ -626,12 +540,12 @@ function removeThreadFromSessionIndex(filePath, threadId) {
 ` : "";
   const changed = next !== original;
   if (changed) {
-    writeFileSync2(filePath, next);
+    writeFileSync(filePath, next);
   }
   return { path: filePath, changed };
 }
 function removeThreadFromGlobalState(filePath, threadId) {
-  if (!existsSync8(filePath)) {
+  if (!existsSync7(filePath)) {
     return { path: filePath, changed: false };
   }
   const original = readFileSync4(filePath, "utf8");
@@ -639,7 +553,7 @@ function removeThreadFromGlobalState(filePath, threadId) {
   const nextValue = removeThreadReferences(parsed, threadId);
   const next = JSON.stringify(nextValue.value, null, 2) + "\n";
   if (nextValue.changed) {
-    writeFileSync2(filePath, next);
+    writeFileSync(filePath, next);
   }
   return {
     path: filePath,
@@ -679,9 +593,8 @@ function removeThreadReferences(value, threadId) {
 }
 
 // src/core/executor.ts
-function executePurge(paths, plan) {
-  const activeThreadChecks = assertThreadIsNotActive(plan.target);
-  const backup = createBackup(paths, plan);
+function executePurge(paths, plan, options = {}) {
+  const activeThreadChecks = options.skipActiveThreadCheck ? [] : assertThreadIsNotActive(plan.target);
   const sqlite = purgeSqlite(paths, plan.target.id);
   const json = [
     removeThreadFromSessionIndex(paths.sessionIndex, plan.target.id),
@@ -697,7 +610,6 @@ function executePurge(paths, plan) {
     mode: "executed",
     plan,
     activeThreadChecks,
-    backup,
     sqlite,
     json,
     files,
@@ -706,7 +618,7 @@ function executePurge(paths, plan) {
 }
 function purgeSqlite(paths, threadId) {
   const results = [];
-  if (existsSync9(paths.stateDb)) {
+  if (existsSync8(paths.stateDb)) {
     const db = openWritableDatabase(paths.stateDb);
     try {
       const transaction = db.transaction(() => {
@@ -727,7 +639,7 @@ function purgeSqlite(paths, threadId) {
       db.close();
     }
   }
-  if (existsSync9(paths.logsDb)) {
+  if (existsSync8(paths.logsDb)) {
     const db = openWritableDatabase(paths.logsDb);
     try {
       const transaction = db.transaction(() => {
@@ -738,7 +650,7 @@ function purgeSqlite(paths, threadId) {
       db.close();
     }
   }
-  if (existsSync9(paths.goalsDb)) {
+  if (existsSync8(paths.goalsDb)) {
     const db = openWritableDatabase(paths.goalsDb);
     try {
       const transaction = db.transaction(() => {
@@ -773,8 +685,8 @@ function purgeFiles(plan) {
 }
 
 // src/core/planner.ts
-import { existsSync as existsSync10, readdirSync, statSync as statSync3 } from "fs";
-import path3 from "path";
+import { existsSync as existsSync9, readdirSync, statSync as statSync2 } from "fs";
+import path2 from "path";
 function resolvePurgeTarget(paths, threadId) {
   if (!threadId.trim()) {
     throw new UsageError("Provide a thread id or unique short id prefix.");
@@ -801,7 +713,7 @@ function buildPurgePlan(paths, target) {
   for (const snapshot of findShellSnapshots(paths.shellSnapshotsDir, target.id)) {
     stores.push(planDeleteFile(snapshot, "shell_snapshot"));
   }
-  if (!existsSync10(target.rolloutPath)) {
+  if (!existsSync9(target.rolloutPath)) {
     warnings.push(`rollout file is missing: ${target.rolloutPath}`);
   }
   return {
@@ -812,7 +724,7 @@ function buildPurgePlan(paths, target) {
   };
 }
 function planStateDb(filePath, threadId) {
-  if (!existsSync10(filePath)) {
+  if (!existsSync9(filePath)) {
     return [missingStore("state_db", filePath)];
   }
   const db = openReadonlyDatabase(filePath);
@@ -845,7 +757,7 @@ function planStateDb(filePath, threadId) {
   }
 }
 function planLogsDb(filePath, threadId) {
-  if (!existsSync10(filePath)) {
+  if (!existsSync9(filePath)) {
     return [missingStore("logs_db", filePath)];
   }
   const db = openReadonlyDatabase(filePath);
@@ -856,7 +768,7 @@ function planLogsDb(filePath, threadId) {
   }
 }
 function planGoalsDb(filePath, threadId) {
-  if (!existsSync10(filePath)) {
+  if (!existsSync9(filePath)) {
     return [missingStore("goals_db", filePath)];
   }
   const db = openReadonlyDatabase(filePath);
@@ -874,7 +786,7 @@ function countTable(db, filePath, tableName, columnName, threadId, storeName) {
       path: filePath,
       action: "inspect",
       detail: `table or column unavailable: ${tableName}.${columnName}`,
-      exists: existsSync10(filePath)
+      exists: existsSync9(filePath)
     };
   }
   return countPlan(storeName ?? `state_db.${tableName}`, filePath, count, "delete matching rows");
@@ -895,7 +807,7 @@ function planRewrite(filePath, store, detail) {
     path: filePath,
     action: "rewrite",
     detail,
-    exists: existsSync10(filePath)
+    exists: existsSync9(filePath)
   };
 }
 function planDeleteFile(filePath, store) {
@@ -904,8 +816,8 @@ function planDeleteFile(filePath, store) {
     path: filePath,
     action: "delete_file",
     detail: "delete file",
-    exists: existsSync10(filePath),
-    count: existsSync10(filePath) ? statSync3(filePath).size : 0
+    exists: existsSync9(filePath),
+    count: existsSync9(filePath) ? statSync2(filePath).size : 0
   };
 }
 function missingStore(store, filePath) {
@@ -918,10 +830,10 @@ function missingStore(store, filePath) {
   };
 }
 function findShellSnapshots(shellSnapshotsDir, threadId) {
-  if (!existsSync10(shellSnapshotsDir)) {
+  if (!existsSync9(shellSnapshotsDir)) {
     return [];
   }
-  return readdirSync(shellSnapshotsDir).filter((entry) => entry.startsWith(`${threadId}.`) && entry.endsWith(".sh")).map((entry) => path3.join(shellSnapshotsDir, entry));
+  return readdirSync(shellSnapshotsDir).filter((entry) => entry.startsWith(`${threadId}.`) && entry.endsWith(".sh")).map((entry) => path2.join(shellSnapshotsDir, entry));
 }
 
 // src/commands/purge.ts
@@ -931,10 +843,211 @@ function planPurgeCommand(paths, threadId) {
   return buildPurgePlan(paths, target);
 }
 function executePurgePlanCommand(paths, plan) {
-  validateSupportedDataModel(paths, { requireBackupHome: true });
+  validateSupportedDataModel(paths);
   return executePurge(paths, plan);
 }
 
+// src/core/orphans.ts
+import { existsSync as existsSync10 } from "fs";
+function buildPurgeOrphansPlan(paths) {
+  validateSupportedDataModel(paths);
+  const threads = listThreads(paths, { all: true });
+  const threadIds = new Set(threads.map((thread) => thread.id));
+  const orphanThreads = threads.filter((thread) => !existsSync10(thread.rolloutPath));
+  const threadPlans = orphanThreads.map((thread) => buildPurgePlan(paths, thread));
+  const logThreadRows = readLogThreadRows(paths);
+  const logsOnlyOrphans = findLogsOnlyOrphans(logThreadRows, threadIds);
+  const impact = buildImpact(
+    threadPlans,
+    logsOnlyOrphans,
+    new Set(orphanThreads.map((thread) => thread.id)),
+    logThreadRows
+  );
+  return {
+    mode: "planned",
+    orphanThreads,
+    threadPlans,
+    logsOnlyOrphans,
+    impact,
+    warnings: threadPlans.flatMap((plan) => plan.warnings)
+  };
+}
+function hasPurgeOrphansWork(plan) {
+  return plan.orphanThreads.length > 0 || plan.logsOnlyOrphans.length > 0;
+}
+function executePurgeOrphans(paths, plan) {
+  validateSupportedDataModel(paths);
+  for (const threadPlan of plan.threadPlans) {
+    if (existsSync10(threadPlan.target.rolloutPath)) {
+      throw new SafetyRefusalError(
+        `Refusing to purge orphan candidate because rollout file now exists: ${threadPlan.target.rolloutPath}`
+      );
+    }
+  }
+  const activeThreadChecks = plan.threadPlans.flatMap((threadPlan) => assertThreadIsNotActive(threadPlan.target));
+  const purgeReports = plan.threadPlans.map(
+    (threadPlan) => executePurge(paths, threadPlan, { skipActiveThreadCheck: true })
+  );
+  const logsOnly = purgeLogsOnlyOrphans(paths, plan.logsOnlyOrphans);
+  checkpointWal(paths.logsDb);
+  const remainingReferences = [
+    ...purgeReports.flatMap((report) => report.verification.remainingReferences),
+    ...verifyLogsOnlyOrphans(paths, plan.logsOnlyOrphans)
+  ];
+  return {
+    mode: "executed",
+    plan,
+    activeThreadChecks,
+    purgeReports,
+    logsOnly,
+    verification: {
+      success: remainingReferences.length === 0,
+      remainingReferences
+    }
+  };
+}
+function findLogsOnlyOrphans(rows, threadIds) {
+  return rows.filter((row) => !threadIds.has(row.threadId)).sort((a, b) => a.threadId.localeCompare(b.threadId));
+}
+function readLogThreadRows(paths) {
+  if (!existsSync10(paths.logsDb)) {
+    return [];
+  }
+  const db = openReadonlyDatabase(paths.logsDb);
+  try {
+    if (!tableExists(db, "logs")) {
+      return [];
+    }
+    const columns = tableColumns(db, "logs");
+    if (!columns.includes("thread_id")) {
+      return [];
+    }
+    const estimatedExpr = columns.includes("estimated_bytes") ? "coalesce(sum(estimated_bytes), 0) as estimatedBytes" : "null as estimatedBytes";
+    const rows = db.prepare(
+      `select thread_id as threadId, count(*) as rows, ${estimatedExpr}
+         from logs
+         where thread_id is not null and thread_id != ''
+         group by thread_id`
+    ).all();
+    return rows.map((row) => ({
+      threadId: row.threadId,
+      rows: Number(row.rows),
+      estimatedBytes: row.estimatedBytes === null ? null : Number(row.estimatedBytes)
+    }));
+  } finally {
+    db.close();
+  }
+}
+function buildImpact(threadPlans, logsOnlyOrphans, orphanThreadIds, logThreadRows) {
+  const sqliteRows = /* @__PURE__ */ new Map();
+  let filesToDelete = 0;
+  let fileBytesToDelete = 0;
+  for (const plan of threadPlans) {
+    for (const store of plan.stores) {
+      if (isSqliteRowChange(store) && store.count && store.count > 0) {
+        sqliteRows.set(store.store, (sqliteRows.get(store.store) ?? 0) + store.count);
+      }
+      if (store.action === "delete_file" && store.exists) {
+        filesToDelete += 1;
+        fileBytesToDelete += store.count ?? 0;
+      }
+    }
+  }
+  const logsOnlyRows = logsOnlyOrphans.reduce((sum, orphan) => sum + orphan.rows, 0);
+  if (logsOnlyRows > 0) {
+    sqliteRows.set("logs_db.logs", (sqliteRows.get("logs_db.logs") ?? 0) + logsOnlyRows);
+  }
+  const affectedLogRows = logThreadRows.filter(
+    (row) => orphanThreadIds.has(row.threadId) || logsOnlyOrphans.some((orphan) => orphan.threadId === row.threadId)
+  );
+  const estimatedLogPayloadBytes = sumNullable(affectedLogRows.map((orphan) => orphan.estimatedBytes));
+  const estimatedLocalDiskBytesAffected = estimatedLogPayloadBytes === null ? null : fileBytesToDelete + estimatedLogPayloadBytes;
+  const sqlite = [...sqliteRows.entries()].map(([store, rows]) => ({ store, rows })).sort((a, b) => a.store.localeCompare(b.store));
+  return {
+    sqliteRowsAffected: sqlite.reduce((sum, item) => sum + item.rows, 0),
+    sqlite,
+    filesToDelete,
+    fileBytesToDelete,
+    estimatedLogPayloadBytes,
+    estimatedLocalDiskBytesAffected
+  };
+}
+function isSqliteRowChange(store) {
+  if (store.action === "delete_rows") {
+    return true;
+  }
+  return store.store === "state_db.agent_job_items";
+}
+function sumNullable(values) {
+  if (values.length === 0) {
+    return 0;
+  }
+  if (values.some((value) => value === null)) {
+    return null;
+  }
+  return values.reduce((sum, value) => sum + value, 0);
+}
+function purgeLogsOnlyOrphans(paths, logsOnlyOrphans) {
+  if (logsOnlyOrphans.length === 0 || !existsSync10(paths.logsDb)) {
+    return { store: "logs_db.logs", changedRows: 0 };
+  }
+  const db = openWritableDatabase(paths.logsDb);
+  try {
+    if (!tableExists(db, "logs") || !tableColumns(db, "logs").includes("thread_id")) {
+      return { store: "logs_db.logs", changedRows: 0 };
+    }
+    let changedRows = 0;
+    const transaction = db.transaction(() => {
+      const statement = db.prepare(`delete from ${quoteIdentifier("logs")} where ${quoteIdentifier("thread_id")} = ?`);
+      for (const orphan of logsOnlyOrphans) {
+        const info = statement.run(orphan.threadId);
+        changedRows += Number(info.changes);
+      }
+    });
+    transaction();
+    return { store: "logs_db.logs", changedRows };
+  } finally {
+    db.close();
+  }
+}
+function verifyLogsOnlyOrphans(paths, logsOnlyOrphans) {
+  if (logsOnlyOrphans.length === 0 || !existsSync10(paths.logsDb)) {
+    return [];
+  }
+  const db = openReadonlyDatabase(paths.logsDb);
+  try {
+    if (!tableExists(db, "logs") || !tableColumns(db, "logs").includes("thread_id")) {
+      return [];
+    }
+    const statement = db.prepare(
+      `select count(*) as count from ${quoteIdentifier("logs")} where ${quoteIdentifier("thread_id")} = ?`
+    );
+    return logsOnlyOrphans.flatMap((orphan) => {
+      const row = statement.get(orphan.threadId);
+      if (row.count === 0) {
+        return [];
+      }
+      return [
+        {
+          store: "logs_db.logs",
+          path: paths.logsDb,
+          detail: `${row.count} row(s) still reference logs-only orphan ${orphan.threadId}`
+        }
+      ];
+    });
+  } finally {
+    db.close();
+  }
+}
+
+// src/commands/purge-orphans.ts
+function planPurgeOrphansCommand(paths) {
+  return buildPurgeOrphansPlan(paths);
+}
+function executePurgeOrphansPlanCommand(paths, plan) {
+  return executePurgeOrphans(paths, plan);
+}
+
 // src/core/output.ts
 function printOutput(value, mode) {
   if (mode === "json") {
@@ -962,8 +1075,9 @@ function shortId(id) {
 
 // src/cli.ts
 var TITLE_MAX_LENGTH = 80;
+var packageVersion = JSON.parse(readFileSync5(new URL("../package.json", import.meta.url), "utf8")).version;
 var program = new Command();
-program.name("codex-history").description("Inspect and safely purge local Codex conversation history.").version("0.1.0").option("--codex-home <path>", "Path to Codex home directory", "~/.codex").option("--json", "Print machine-readable JSON output");
+program.name("codex-history").description("Inspect and safely purge local Codex conversation history.").version(packageVersion).option("--codex-home <path>", "Path to Codex home directory", "~/.codex").option("--json", "Print machine-readable JSON output");
 program.command("doctor").description("Check whether the local Codex data model is supported.").action(
   () => runCommand(() => {
     const report = doctorCommand(currentPaths());
@@ -1002,6 +1116,23 @@ program.command("purge").argument("<threadId>", "Codex thread id or unique short
     return formatPurgeResult(executePurgePlanCommand(paths, plan));
   })
 );
+program.command("purge-orphans").option("--force", "Skip interactive confirmation").description("Purge orphaned local Codex data after target confirmation.").action(
+  (options) => runCommand(async () => {
+    if (currentOutputModeIsJson()) {
+      throw new UsageError("purge-orphans does not support JSON output.");
+    }
+    const paths = currentPaths();
+    const plan = planPurgeOrphansCommand(paths);
+    const force = Boolean(options.force);
+    if (!hasPurgeOrphansWork(plan)) {
+      return formatPurgeOrphansPlan(plan);
+    }
+    if (!force) {
+      await confirmPurgeOrphans(plan);
+    }
+    return formatPurgeOrphansResult(executePurgeOrphansPlanCommand(paths, plan));
+  })
+);
 await program.parseAsync();
 function currentOutputMode() {
   return program.opts().json ? "json" : "text";
@@ -1061,6 +1192,25 @@ async function confirmPurge(plan) {
     readline.close();
   }
 }
+async function confirmPurgeOrphans(plan) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    throw new SafetyRefusalError("purge-orphans requires an interactive terminal. Use --force to skip confirmation.");
+  }
+  const expected = "purge-orphans";
+  process.stdout.write(formatPurgeOrphansConfirmation(plan));
+  const readline = createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+  try {
+    const answer = await readline.question(`Type ${colorize("yellow", expected)} to confirm: `);
+    if (answer.trim() !== expected) {
+      throw new SafetyRefusalError("Confirmation did not match. No local Codex data was modified.");
+    }
+  } finally {
+    readline.close();
+  }
+}
 function formatDoctor(report) {
   if (currentOutputMode() === "json") {
     return report;
@@ -1132,7 +1282,6 @@ function formatPurgeResult(result) {
     "",
     `Target: ${displayTitle(result.plan.target.title)}`,
     `Thread id: ${result.plan.target.id}`,
-    `Backup: ${colorize("dim", result.backup.backupDir)}`,
     "",
     "SQLite changes:",
     ...result.sqlite.map((change) => `- ${change.store}: ${change.changedRows} row(s)`),
@@ -1157,6 +1306,46 @@ function formatPurgeResult(result) {
   }
   return lines.join("\n");
 }
+function formatPurgeOrphansPlan(plan) {
+  if (!hasPurgeOrphansWork(plan)) {
+    return "No orphaned local Codex data found.";
+  }
+  return formatPurgeOrphansConfirmation(plan).trimEnd();
+}
+function formatPurgeOrphansResult(result) {
+  const sqliteChanges = aggregateOrphanSqliteChanges(result);
+  const filesDeleted = result.purgeReports.flatMap((report) => report.files).filter((file) => file.deleted).length;
+  const jsonChanged = result.purgeReports.flatMap((report) => report.json).filter((change) => change.changed).length;
+  const lines = [
+    colorize("green", "Purge-orphans executed."),
+    "",
+    "Summary:",
+    `- Orphaned threads purged: ${result.plan.orphanThreads.length}`,
+    `- Logs-only orphan thread ids cleaned: ${result.plan.logsOnlyOrphans.length}`,
+    `- SQLite row changes: ${sqliteChanges.reduce((sum, change) => sum + change.rows, 0)}`,
+    `- JSON/JSONL file changes: ${jsonChanged}`,
+    `- Files deleted: ${filesDeleted}`,
+    `- Estimated local disk space affected: ${formatNullableBytes(result.plan.impact.estimatedLocalDiskBytesAffected)}`,
+    "",
+    "SQLite changes:",
+    ...formatSqliteRows(sqliteChanges),
+    "",
+    colorize("dim", "SQLite database files may not shrink until vacuumed by Codex or another SQLite maintenance step."),
+    "",
+    `Verification: ${result.verification.success ? colorize("green", "passed") : colorize("red", "failed")}`
+  ];
+  if (result.verification.remainingReferences.length > 0) {
+    lines.push(
+      "",
+      "Remaining references:",
+      ...result.verification.remainingReferences.map(
+        (reference) => `- ${reference.store}: ${reference.path} (${reference.detail})`
+      )
+    );
+    process.exitCode = 1;
+  }
+  return lines.join("\n");
+}
 function formatPurgeConfirmation(plan) {
   return [
     "About to purge this local Codex conversation:",
@@ -1166,10 +1355,85 @@ function formatPurgeConfirmation(plan) {
     `cwd: ${colorize("dim", plan.target.cwd)}`,
     `updated: ${formatDate(plan.target.updatedAtMs)}`,
     "",
-    colorize("dim", "A backup will be created before deletion."),
+    colorize("dim", "This cannot be undone."),
+    ""
+  ].join("\n");
+}
+function formatPurgeOrphansConfirmation(plan) {
+  return [
+    "About to purge orphaned local Codex data:",
+    "",
+    `Orphaned threads: ${plan.orphanThreads.length}`,
+    `Logs-only orphan thread ids: ${plan.logsOnlyOrphans.length}`,
+    "",
+    "SQLite row changes:",
+    ...formatSqliteRows(plan.impact.sqlite),
+    "",
+    "Files:",
+    `- files to delete: ${plan.impact.filesToDelete}`,
+    `- file bytes to delete: ${formatBytes(plan.impact.fileBytesToDelete)}`,
+    "",
+    "Estimated cleanup impact:",
+    `- estimated log payload affected: ${formatNullableBytes(plan.impact.estimatedLogPayloadBytes)}`,
+    `- estimated local disk space affected: ${formatNullableBytes(plan.impact.estimatedLocalDiskBytesAffected)}`,
+    "",
+    ...formatOrphanExamples(plan),
+    colorize("dim", "SQLite database files may not shrink until vacuumed by Codex or another SQLite maintenance step."),
+    colorize("dim", "This cannot be undone."),
     ""
   ].join("\n");
 }
+function formatOrphanExamples(plan) {
+  const examples = [
+    ...plan.orphanThreads.slice(0, 5).map(
+      (thread) => `- ${shortId(thread.id)}  ${displayTitle(thread.title)}  ${colorize("dim", thread.cwd)}`
+    ),
+    ...plan.logsOnlyOrphans.slice(0, Math.max(0, 5 - Math.min(plan.orphanThreads.length, 5))).map(
+      (orphan) => `- logs-only: ${shortId(orphan.threadId)} (${orphan.rows} row(s))`
+    )
+  ];
+  if (examples.length === 0) {
+    return [];
+  }
+  const total = plan.orphanThreads.length + plan.logsOnlyOrphans.length;
+  const lines = ["Examples:", ...examples, ""];
+  if (total > examples.length) {
+    lines.push(`Showing ${examples.length} of ${total} orphan candidate(s).`, "");
+  }
+  return lines;
+}
+function aggregateOrphanSqliteChanges(result) {
+  const changes = /* @__PURE__ */ new Map();
+  for (const report of result.purgeReports) {
+    for (const change of report.sqlite) {
+      changes.set(change.store, (changes.get(change.store) ?? 0) + change.changedRows);
+    }
+  }
+  changes.set(result.logsOnly.store, (changes.get(result.logsOnly.store) ?? 0) + result.logsOnly.changedRows);
+  return [...changes.entries()].filter(([, rows]) => rows > 0).map(([store, rows]) => ({ store, rows })).sort((a, b) => a.store.localeCompare(b.store));
+}
+function formatSqliteRows(rows) {
+  if (rows.length === 0) {
+    return ["- none"];
+  }
+  return rows.map((row) => `- ${row.store}: ${row.rows} row(s)`);
+}
+function formatNullableBytes(value) {
+  return value === null ? "unavailable" : formatBytes(value);
+}
+function formatBytes(value) {
+  if (value < 1024) {
+    return `${value} B`;
+  }
+  const units = ["KB", "MB", "GB", "TB"];
+  let size = value / 1024;
+  let unitIndex = 0;
+  while (size >= 1024 && unitIndex < units.length - 1) {
+    size /= 1024;
+    unitIndex += 1;
+  }
+  return `${size.toFixed(size >= 10 ? 1 : 2)} ${units[unitIndex]}`;
+}
 function formatCheckStatus(status) {
   const label = status.toUpperCase().padEnd(7);
   if (status === "ok") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liuyoumi/codex-history",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "CLI for listing and safely purging local Codex conversation history",
   "type": "module",
   "bin": {