@liuyoumi/codex-history 0.1.3 → 0.1.4

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # 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

package/README.en.md

@@ -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
 
@@ -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:
@@ -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`
 
@@ -141,6 +143,26 @@ codex-history purge 019e6885 --force
 
 `--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
 
 ```bash
@@ -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

package/README.md

@@ -18,7 +18,7 @@
 
 一个用来查找并删除本地 Codex 对话历史的小型命令行工具。
 
-`codex-history` 只处理你机器上的本地 Codex 数据。它会尽量使用 Codex 对话列表里显示的短标题，支持用 `--grep` 缩小范围，并且只会在你确认目标后删除一条明确解析出来的对话。
+`codex-history` 只处理你机器上的本地 Codex 数据。它会尽量使用 Codex 对话列表里显示的短标题，支持用 `--grep` 缩小范围，并且只会在你确认目标后删除明确解析出来的对话或孤儿数据。
 
 ## 安装
 
@@ -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，确认后才会删除：
@@ -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`
 
@@ -141,6 +143,26 @@ codex-history purge 019e6885 --force
 
 `--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。
+
 ## 选项
 
 ```bash
@@ -151,6 +173,7 @@ codex-history --json purge 019e6885 --force
 
 - `--codex-home` 默认是 `~/.codex`。
 - `--json` 输出机器可读的 JSON。`purge` 使用 JSON 输出时必须加 `--force`，因为交互确认只适合文本模式。
+- `purge-orphans` 不支持 JSON 输出。
 - 颜色只会在交互式终端中启用，并遵守 `NO_COLOR`。
 
 ## 安全机制

package/dist/cli.js

@@ -593,8 +593,8 @@ function removeThreadReferences(value, threadId) {
 }
 
 // src/core/executor.ts
-function executePurge(paths, plan) {
-  const activeThreadChecks = assertThreadIsNotActive(plan.target);
+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),
@@ -847,6 +847,207 @@ function executePurgePlanCommand(paths, plan) {
   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") {
@@ -915,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";
@@ -974,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;
@@ -1069,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:",
@@ -1082,6 +1359,81 @@ function formatPurgeConfirmation(plan) {
     ""
   ].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.3",
+  "version": "0.1.4",
   "description": "CLI for listing and safely purging local Codex conversation history",
   "type": "module",
   "bin": {