@liuyoumi/codex-history 0.1.0

package/dist/cli.js

@@ -0,0 +1,1244 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { Command } from "commander";
+import { spawnSync } from "child_process";
+import { createInterface } from "readline/promises";
+
+// src/core/schema.ts
+import { mkdirSync, readFileSync } from "fs";
+import { dirname } from "path";
+
+// src/core/paths.ts
+import { existsSync } from "fs";
+import { homedir } from "os";
+import path from "path";
+function expandHome(input) {
+  if (input === "~") {
+    return homedir();
+  }
+  if (input.startsWith("~/")) {
+    return path.join(homedir(), input.slice(2));
+  }
+  return input;
+}
+function resolvePaths(codexHomeInput, toolHomeInput) {
+  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"),
+    sessionIndex: path.join(codexHome, "session_index.jsonl"),
+    globalState: path.join(codexHome, ".codex-global-state.json"),
+    globalStateBackup: path.join(codexHome, ".codex-global-state.json.bak"),
+    shellSnapshotsDir: path.join(codexHome, "shell_snapshots")
+  };
+}
+function fileStatus(filePath) {
+  return existsSync(filePath) ? "present" : "missing";
+}
+
+// src/stores/sqlite.ts
+import Database from "better-sqlite3";
+import { existsSync as existsSync2 } from "fs";
+function openReadonlyDatabase(filePath) {
+  return new Database(filePath, {
+    readonly: true,
+    fileMustExist: true
+  });
+}
+function openWritableDatabase(filePath) {
+  return new Database(filePath, {
+    fileMustExist: true
+  });
+}
+function sqliteFileExists(filePath) {
+  return existsSync2(filePath);
+}
+function tableExists(db, tableName) {
+  const row = db.prepare("select 1 as ok from sqlite_master where type = 'table' and name = ?").get(tableName);
+  return row?.ok === 1;
+}
+function tableColumns(db, tableName) {
+  const rows = db.prepare(`pragma table_info(${quoteIdentifier(tableName)})`).all();
+  return rows.map((row) => row.name);
+}
+function countWhereThreadId(db, tableName, columnName, threadId) {
+  if (!tableExists(db, tableName)) {
+    return null;
+  }
+  const columns = tableColumns(db, tableName);
+  if (!columns.includes(columnName)) {
+    return null;
+  }
+  const row = db.prepare(
+    `select count(*) as count from ${quoteIdentifier(tableName)} where ${quoteIdentifier(
+      columnName
+    )} = ?`
+  ).get(threadId);
+  return row.count;
+}
+function quoteIdentifier(value) {
+  return `"${value.replaceAll('"', '""')}"`;
+}
+function checkpointWal(filePath) {
+  if (!sqliteFileExists(filePath)) {
+    return;
+  }
+  const db = openWritableDatabase(filePath);
+  try {
+    db.pragma("wal_checkpoint(TRUNCATE)");
+  } finally {
+    db.close();
+  }
+}
+
+// src/core/schema.ts
+var REQUIRED_THREAD_COLUMNS = [
+  "id",
+  "title",
+  "rollout_path",
+  "created_at",
+  "updated_at",
+  "cwd",
+  "archived",
+  "first_user_message",
+  "preview"
+];
+function runDoctor(paths) {
+  const checks = [];
+  checks.push({
+    name: "codex_home",
+    status: fileStatus(paths.codexHome) === "present" ? "ok" : "error",
+    detail: paths.codexHome
+  });
+  checks.push(checkStateDatabase(paths.stateDb));
+  checks.push(checkOptionalSqlite(paths.logsDb, "logs_db"));
+  checks.push(checkOptionalSqlite(paths.goalsDb, "goals_db"));
+  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 = {}) {
+  const report = runDoctor(paths);
+  const errors = report.checks.filter(
+    (check) => check.status === "error" && (options.requireBackupHome || check.name !== "backup_home")
+  );
+  if (errors.length > 0) {
+    const details = errors.map((check) => `${check.name}: ${check.detail}`).join("; ");
+    throw new Error(`Unsupported Codex data model: ${details}`);
+  }
+}
+function checkStateDatabase(filePath) {
+  if (!sqliteFileExists(filePath)) {
+    return {
+      name: "state_db",
+      status: "error",
+      detail: `${filePath} is missing`
+    };
+  }
+  try {
+    const db = openReadonlyDatabase(filePath);
+    try {
+      if (!tableExists(db, "threads")) {
+        return {
+          name: "state_db",
+          status: "error",
+          detail: "missing threads table"
+        };
+      }
+      const columns = tableColumns(db, "threads");
+      const missingColumns = REQUIRED_THREAD_COLUMNS.filter((column) => !columns.includes(column));
+      if (missingColumns.length > 0) {
+        return {
+          name: "state_db",
+          status: "error",
+          detail: `missing threads columns: ${missingColumns.join(", ")}`
+        };
+      }
+      return {
+        name: "state_db",
+        status: "ok",
+        detail: filePath
+      };
+    } finally {
+      db.close();
+    }
+  } catch (error) {
+    return {
+      name: "state_db",
+      status: "error",
+      detail: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+function checkOptionalSqlite(filePath, name) {
+  if (!sqliteFileExists(filePath)) {
+    return {
+      name,
+      status: "warning",
+      detail: `${filePath} is missing`
+    };
+  }
+  try {
+    const db = openReadonlyDatabase(filePath);
+    db.close();
+    return {
+      name,
+      status: "ok",
+      detail: filePath
+    };
+  } catch (error) {
+    return {
+      name,
+      status: "error",
+      detail: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+function checkJsonFile(filePath, name) {
+  if (fileStatus(filePath) === "missing") {
+    return {
+      name,
+      status: "warning",
+      detail: `${filePath} is missing`
+    };
+  }
+  try {
+    JSON.parse(readFileSync(filePath, "utf8"));
+    return {
+      name,
+      status: "ok",
+      detail: filePath
+    };
+  } catch (error) {
+    return {
+      name,
+      status: "error",
+      detail: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+function checkJsonlFile(filePath, name) {
+  if (fileStatus(filePath) === "missing") {
+    return {
+      name,
+      status: "warning",
+      detail: `${filePath} is missing`
+    };
+  }
+  try {
+    const lines = readFileSync(filePath, "utf8").split("\n").filter((line) => line.trim().length > 0);
+    for (const line of lines) {
+      JSON.parse(line);
+    }
+    return {
+      name,
+      status: "ok",
+      detail: `${filePath} (${lines.length} entries)`
+    };
+  } catch (error) {
+    return {
+      name,
+      status: "error",
+      detail: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+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) {
+  return runDoctor(paths);
+}
+
+// src/stores/session-index.ts
+import { existsSync as existsSync3, readFileSync as readFileSync2 } from "fs";
+function readSessionIndex(filePath) {
+  const entries = /* @__PURE__ */ new Map();
+  if (!existsSync3(filePath)) {
+    return entries;
+  }
+  const lines = readFileSync2(filePath, "utf8").split("\n").filter((line) => line.trim().length > 0);
+  for (const line of lines) {
+    const raw = JSON.parse(line);
+    if (typeof raw.id !== "string" || typeof raw.thread_name !== "string") {
+      continue;
+    }
+    entries.set(raw.id, {
+      id: raw.id,
+      threadName: raw.thread_name,
+      updatedAt: typeof raw.updated_at === "string" ? raw.updated_at : void 0
+    });
+  }
+  return entries;
+}
+
+// src/core/threads.ts
+function listThreads(paths, options = {}) {
+  const limit = options.limit;
+  const where = [];
+  const params = [];
+  if (!options.all) {
+    where.push(`${quoteIdentifier("archived")} = ?`);
+    params.push(options.archived ? 1 : 0);
+  } else if (options.archived) {
+    where.push(`${quoteIdentifier("archived")} = ?`);
+    params.push(1);
+  }
+  if (options.cwd) {
+    where.push(`${quoteIdentifier("cwd")} = ?`);
+    params.push(options.cwd);
+  }
+  const whereClause = where.length > 0 ? `where ${where.join(" and ")}` : "";
+  const hasLimit = typeof limit === "number" && Number.isFinite(limit) && limit > 0;
+  const shouldFilterAfterLoad = Boolean(options.grep);
+  const limitClause = hasLimit && !shouldFilterAfterLoad ? "limit ?" : "";
+  if (limitClause) {
+    params.push(limit);
+  }
+  const sessionIndex = readSessionIndex(paths.sessionIndex);
+  const db = openReadonlyDatabase(paths.stateDb);
+  try {
+    const rows = db.prepare(
+      `select id, title, rollout_path, created_at, updated_at, created_at_ms, updated_at_ms, cwd, archived, first_user_message, preview
+         from threads
+         ${whereClause}
+         order by coalesce(updated_at_ms, updated_at * 1000) desc, id desc
+         ${limitClause}`
+    ).all(...params);
+    const threads = rows.map((row) => mapThreadRow(row, sessionIndex));
+    const filteredThreads = options.grep ? filterThreads(threads, options.grep) : threads;
+    return hasLimit && shouldFilterAfterLoad ? filteredThreads.slice(0, limit) : filteredThreads;
+  } finally {
+    db.close();
+  }
+}
+function filterThreads(threads, keyword) {
+  const normalizedKeyword = keyword.toLocaleLowerCase();
+  return threads.filter((thread) => {
+    const haystack = [
+      thread.id,
+      thread.title,
+      thread.cwd
+    ].join("\n").toLocaleLowerCase();
+    return haystack.includes(normalizedKeyword);
+  });
+}
+function getThreadsByIdPrefix(paths, idPrefix) {
+  const sessionIndex = readSessionIndex(paths.sessionIndex);
+  const db = openReadonlyDatabase(paths.stateDb);
+  try {
+    const rows = db.prepare(
+      `select id, title, rollout_path, created_at, updated_at, created_at_ms, updated_at_ms, cwd, archived, first_user_message, preview
+         from threads
+         where id like ?
+         order by coalesce(updated_at_ms, updated_at * 1000) desc, id desc`
+    ).all(`${escapeLike(idPrefix)}%`);
+    return rows.map((row) => mapThreadRow(row, sessionIndex));
+  } finally {
+    db.close();
+  }
+}
+function mapThreadRow(row, sessionIndex) {
+  const sourceTitle = row.title;
+  const displayTitle2 = sessionIndex.get(row.id)?.threadName || sourceTitle;
+  return {
+    id: row.id,
+    title: displayTitle2,
+    sourceTitle,
+    rolloutPath: row.rollout_path,
+    createdAtMs: row.created_at_ms ?? row.created_at * 1e3,
+    updatedAtMs: row.updated_at_ms ?? row.updated_at * 1e3,
+    cwd: row.cwd,
+    archived: row.archived === 1,
+    firstUserMessage: row.first_user_message,
+    preview: row.preview
+  };
+}
+function escapeLike(value) {
+  return value.replaceAll("\\", "\\\\").replaceAll("%", "\\%").replaceAll("_", "\\_");
+}
+
+// src/commands/list.ts
+function listCommand(paths, options = {}) {
+  validateSupportedDataModel(paths);
+  return listThreads(paths, options);
+}
+
+// src/core/executor.ts
+import { existsSync as existsSync9 } from "fs";
+
+// src/safety/active-thread.ts
+import { existsSync as existsSync4, statSync } from "fs";
+
+// src/core/errors.ts
+var CodexHistoryError = class extends Error {
+  constructor(message, exitCode = 1) {
+    super(message);
+    this.exitCode = exitCode;
+    this.name = "CodexHistoryError";
+  }
+  exitCode;
+};
+var UsageError = class extends CodexHistoryError {
+  constructor(message) {
+    super(message, 2);
+    this.name = "UsageError";
+  }
+};
+var SafetyRefusalError = class extends CodexHistoryError {
+  constructor(message) {
+    super(message, 3);
+    this.name = "SafetyRefusalError";
+  }
+};
+
+// src/safety/active-thread.ts
+function assertThreadIsNotActive(target) {
+  const checks = [];
+  const currentThreadId = process.env.CODEX_THREAD_ID;
+  if (currentThreadId && currentThreadId === target.id) {
+    throw new SafetyRefusalError(`Refusing to purge active Codex thread: ${target.id}`);
+  }
+  checks.push({
+    status: "ok",
+    detail: "CODEX_THREAD_ID does not match target thread"
+  });
+  if (existsSync4(target.rolloutPath)) {
+    const before = statSync(target.rolloutPath).mtimeMs;
+    const after = statSync(target.rolloutPath).mtimeMs;
+    if (before !== after) {
+      throw new SafetyRefusalError(`Refusing to purge a changing rollout file: ${target.rolloutPath}`);
+    }
+    checks.push({
+      status: "ok",
+      detail: "rollout file does not appear to be changing"
+    });
+  } else {
+    checks.push({
+      status: "warning",
+      detail: `rollout file is missing: ${target.rolloutPath}`
+    });
+  }
+  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";
+function verifyPurge(paths, plan) {
+  const remainingReferences = [];
+  const threadId = plan.target.id;
+  checkSqlite(paths.stateDb, "state_db", threadId, remainingReferences);
+  checkSqlite(paths.logsDb, "logs_db", threadId, remainingReferences);
+  checkSqlite(paths.goalsDb, "goals_db", threadId, remainingReferences);
+  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)) {
+    remainingReferences.push({
+      store: "rollout_jsonl",
+      path: plan.target.rolloutPath,
+      detail: "rollout file still exists"
+    });
+  }
+  for (const store of plan.stores) {
+    if (store.store === "shell_snapshot" && existsSync6(store.path)) {
+      remainingReferences.push({
+        store: "shell_snapshot",
+        path: store.path,
+        detail: "shell snapshot still exists"
+      });
+    }
+  }
+  return {
+    success: remainingReferences.length === 0,
+    remainingReferences
+  };
+}
+function checkSqlite(filePath, store, threadId, remainingReferences) {
+  if (!existsSync6(filePath)) {
+    return;
+  }
+  const db = openReadonlyDatabase(filePath);
+  try {
+    const tables = db.prepare("select name from sqlite_master where type = 'table'").all();
+    for (const table of tables) {
+      if (!tableExists(db, table.name)) {
+        continue;
+      }
+      const columns = tableColumns(db, table.name);
+      for (const column of columns) {
+        if (!column.endsWith("thread_id") && column !== "id") {
+          continue;
+        }
+        const row = db.prepare(
+          `select count(*) as count from ${quoteIdentifier(table.name)} where ${quoteIdentifier(column)} = ?`
+        ).get(threadId);
+        if (row.count > 0) {
+          remainingReferences.push({
+            store: `${store}.${table.name}`,
+            path: filePath,
+            detail: `${row.count} row(s) still reference ${column}`
+          });
+        }
+      }
+    }
+  } finally {
+    db.close();
+  }
+}
+function checkTextFile(filePath, store, threadId, remainingReferences) {
+  if (!existsSync6(filePath)) {
+    return;
+  }
+  const content = readFileSync3(filePath, "utf8");
+  if (content.includes(threadId)) {
+    remainingReferences.push({
+      store,
+      path: filePath,
+      detail: "text file still contains thread id"
+    });
+  }
+}
+
+// src/stores/files.ts
+import { existsSync as existsSync7, unlinkSync } from "fs";
+function deleteFileIfExists(filePath) {
+  if (!existsSync7(filePath)) {
+    return {
+      path: filePath,
+      deleted: false
+    };
+  }
+  unlinkSync(filePath);
+  return {
+    path: filePath,
+    deleted: true
+  };
+}
+
+// src/stores/json-state.ts
+import { existsSync as existsSync8, readFileSync as readFileSync4, writeFileSync as writeFileSync2 } from "fs";
+function removeThreadFromSessionIndex(filePath, threadId) {
+  if (!existsSync8(filePath)) {
+    return { path: filePath, changed: false };
+  }
+  const original = readFileSync4(filePath, "utf8");
+  const lines = original.split("\n");
+  const kept = lines.filter((line) => {
+    if (line.trim().length === 0) {
+      return false;
+    }
+    const parsed = JSON.parse(line);
+    return parsed.id !== threadId;
+  });
+  const next = kept.length > 0 ? `${kept.join("\n")}
+` : "";
+  const changed = next !== original;
+  if (changed) {
+    writeFileSync2(filePath, next);
+  }
+  return { path: filePath, changed };
+}
+function removeThreadFromGlobalState(filePath, threadId) {
+  if (!existsSync8(filePath)) {
+    return { path: filePath, changed: false };
+  }
+  const original = readFileSync4(filePath, "utf8");
+  const parsed = JSON.parse(original);
+  const nextValue = removeThreadReferences(parsed, threadId);
+  const next = JSON.stringify(nextValue.value, null, 2) + "\n";
+  if (nextValue.changed) {
+    writeFileSync2(filePath, next);
+  }
+  return {
+    path: filePath,
+    changed: nextValue.changed
+  };
+}
+function removeThreadReferences(value, threadId) {
+  if (Array.isArray(value)) {
+    let changed = false;
+    const next = [];
+    for (const item of value) {
+      if (item === threadId) {
+        changed = true;
+        continue;
+      }
+      const result = removeThreadReferences(item, threadId);
+      changed ||= result.changed;
+      next.push(result.value);
+    }
+    return { value: next, changed };
+  }
+  if (value && typeof value === "object") {
+    let changed = false;
+    const next = {};
+    for (const [key, child] of Object.entries(value)) {
+      if (key === threadId) {
+        changed = true;
+        continue;
+      }
+      const result = removeThreadReferences(child, threadId);
+      changed ||= result.changed;
+      next[key] = result.value;
+    }
+    return { value: next, changed };
+  }
+  return { value, changed: false };
+}
+
+// src/core/executor.ts
+function executePurge(paths, plan) {
+  const activeThreadChecks = assertThreadIsNotActive(plan.target);
+  const backup = createBackup(paths, plan);
+  const sqlite = purgeSqlite(paths, plan.target.id);
+  const json = [
+    removeThreadFromSessionIndex(paths.sessionIndex, plan.target.id),
+    removeThreadFromGlobalState(paths.globalState, plan.target.id),
+    removeThreadFromGlobalState(paths.globalStateBackup, plan.target.id)
+  ];
+  const files = purgeFiles(plan);
+  checkpointWal(paths.stateDb);
+  checkpointWal(paths.logsDb);
+  checkpointWal(paths.goalsDb);
+  const verification = verifyPurge(paths, plan);
+  return {
+    mode: "executed",
+    plan,
+    activeThreadChecks,
+    backup,
+    sqlite,
+    json,
+    files,
+    verification
+  };
+}
+function purgeSqlite(paths, threadId) {
+  const results = [];
+  if (existsSync9(paths.stateDb)) {
+    const db = openWritableDatabase(paths.stateDb);
+    try {
+      const transaction = db.transaction(() => {
+        results.push(deleteRows(db, "thread_dynamic_tools", "thread_id", threadId, "state_db.thread_dynamic_tools"));
+        results.push(deleteRows(db, "stage1_outputs", "thread_id", threadId, "state_db.stage1_outputs"));
+        if (tableExists(db, "thread_spawn_edges")) {
+          const info = db.prepare("delete from thread_spawn_edges where parent_thread_id = ? or child_thread_id = ?").run(threadId, threadId);
+          results.push({ store: "state_db.thread_spawn_edges", changedRows: Number(info.changes) });
+        }
+        if (tableExists(db, "agent_job_items")) {
+          const info = db.prepare("update agent_job_items set assigned_thread_id = null where assigned_thread_id = ?").run(threadId);
+          results.push({ store: "state_db.agent_job_items", changedRows: Number(info.changes) });
+        }
+        results.push(deleteRows(db, "threads", "id", threadId, "state_db.threads"));
+      });
+      transaction();
+    } finally {
+      db.close();
+    }
+  }
+  if (existsSync9(paths.logsDb)) {
+    const db = openWritableDatabase(paths.logsDb);
+    try {
+      const transaction = db.transaction(() => {
+        results.push(deleteRows(db, "logs", "thread_id", threadId, "logs_db.logs"));
+      });
+      transaction();
+    } finally {
+      db.close();
+    }
+  }
+  if (existsSync9(paths.goalsDb)) {
+    const db = openWritableDatabase(paths.goalsDb);
+    try {
+      const transaction = db.transaction(() => {
+        results.push(deleteRows(db, "thread_goals", "thread_id", threadId, "goals_db.thread_goals"));
+      });
+      transaction();
+    } finally {
+      db.close();
+    }
+  }
+  return results;
+}
+function deleteRows(db, tableName, columnName, threadId, store) {
+  if (!tableExists(db, tableName)) {
+    return { store, changedRows: 0 };
+  }
+  const info = db.prepare(`delete from "${tableName}" where "${columnName}" = ?`).run(threadId);
+  return {
+    store,
+    changedRows: Number(info.changes)
+  };
+}
+function purgeFiles(plan) {
+  const results = [];
+  results.push(deleteFileIfExists(plan.target.rolloutPath));
+  for (const store of plan.stores) {
+    if (store.store === "shell_snapshot") {
+      results.push(deleteFileIfExists(store.path));
+    }
+  }
+  return results;
+}
+
+// src/core/planner.ts
+import { existsSync as existsSync10, readdirSync, statSync as statSync3 } from "fs";
+import path3 from "path";
+function resolvePurgeTarget(paths, threadId) {
+  if (!threadId.trim()) {
+    throw new UsageError("Provide a thread id or unique short id prefix.");
+  }
+  const matches = getThreadsByIdPrefix(paths, threadId);
+  if (matches.length === 0) {
+    throw new UsageError(`No Codex thread found for id: ${threadId}`);
+  }
+  if (matches.length > 1) {
+    throw new SafetyRefusalError(`ID prefix matched ${matches.length} threads. Use a longer id prefix or full id.`);
+  }
+  return matches[0];
+}
+function buildPurgePlan(paths, target) {
+  const stores = [];
+  const warnings = [];
+  stores.push(...planStateDb(paths.stateDb, target.id));
+  stores.push(...planLogsDb(paths.logsDb, target.id));
+  stores.push(...planGoalsDb(paths.goalsDb, target.id));
+  stores.push(planRewrite(paths.sessionIndex, "session_index", "remove matching JSONL entry"));
+  stores.push(planRewrite(paths.globalState, "global_state", "remove known thread references"));
+  stores.push(planRewrite(paths.globalStateBackup, "global_state_backup", "remove known thread references"));
+  stores.push(planDeleteFile(target.rolloutPath, "rollout_jsonl"));
+  for (const snapshot of findShellSnapshots(paths.shellSnapshotsDir, target.id)) {
+    stores.push(planDeleteFile(snapshot, "shell_snapshot"));
+  }
+  if (!existsSync10(target.rolloutPath)) {
+    warnings.push(`rollout file is missing: ${target.rolloutPath}`);
+  }
+  return {
+    mode: "planned",
+    target,
+    stores,
+    warnings
+  };
+}
+function planStateDb(filePath, threadId) {
+  if (!existsSync10(filePath)) {
+    return [missingStore("state_db", filePath)];
+  }
+  const db = openReadonlyDatabase(filePath);
+  try {
+    const plans = [];
+    plans.push(countPlan("state_db.threads", filePath, 1, "delete target thread row"));
+    plans.push(countTable(db, filePath, "thread_dynamic_tools", "thread_id", threadId));
+    plans.push(countTable(db, filePath, "stage1_outputs", "thread_id", threadId));
+    if (tableExists(db, "thread_spawn_edges")) {
+      const row = db.prepare(
+        "select count(*) as count from thread_spawn_edges where parent_thread_id = ? or child_thread_id = ?"
+      ).get(threadId, threadId);
+      plans.push(countPlan("state_db.thread_spawn_edges", filePath, row.count, "delete parent/child edges"));
+    }
+    if (tableExists(db, "agent_job_items")) {
+      const row = db.prepare("select count(*) as count from agent_job_items where assigned_thread_id = ?").get(threadId);
+      plans.push(
+        countPlan(
+          "state_db.agent_job_items",
+          filePath,
+          row.count,
+          "inspect assigned thread references before purge execution",
+          "inspect"
+        )
+      );
+    }
+    return plans;
+  } finally {
+    db.close();
+  }
+}
+function planLogsDb(filePath, threadId) {
+  if (!existsSync10(filePath)) {
+    return [missingStore("logs_db", filePath)];
+  }
+  const db = openReadonlyDatabase(filePath);
+  try {
+    return [countTable(db, filePath, "logs", "thread_id", threadId, "logs_db.logs")];
+  } finally {
+    db.close();
+  }
+}
+function planGoalsDb(filePath, threadId) {
+  if (!existsSync10(filePath)) {
+    return [missingStore("goals_db", filePath)];
+  }
+  const db = openReadonlyDatabase(filePath);
+  try {
+    return [countTable(db, filePath, "thread_goals", "thread_id", threadId, "goals_db.thread_goals")];
+  } finally {
+    db.close();
+  }
+}
+function countTable(db, filePath, tableName, columnName, threadId, storeName) {
+  const count = countWhereThreadId(db, tableName, columnName, threadId);
+  if (count === null) {
+    return {
+      store: storeName ?? `state_db.${tableName}`,
+      path: filePath,
+      action: "inspect",
+      detail: `table or column unavailable: ${tableName}.${columnName}`,
+      exists: existsSync10(filePath)
+    };
+  }
+  return countPlan(storeName ?? `state_db.${tableName}`, filePath, count, "delete matching rows");
+}
+function countPlan(store, filePath, count, detail, action = "delete_rows") {
+  return {
+    store,
+    path: filePath,
+    action,
+    detail,
+    count,
+    exists: true
+  };
+}
+function planRewrite(filePath, store, detail) {
+  return {
+    store,
+    path: filePath,
+    action: "rewrite",
+    detail,
+    exists: existsSync10(filePath)
+  };
+}
+function planDeleteFile(filePath, store) {
+  return {
+    store,
+    path: filePath,
+    action: "delete_file",
+    detail: "delete file",
+    exists: existsSync10(filePath),
+    count: existsSync10(filePath) ? statSync3(filePath).size : 0
+  };
+}
+function missingStore(store, filePath) {
+  return {
+    store,
+    path: filePath,
+    action: "inspect",
+    detail: "store is missing",
+    exists: false
+  };
+}
+function findShellSnapshots(shellSnapshotsDir, threadId) {
+  if (!existsSync10(shellSnapshotsDir)) {
+    return [];
+  }
+  return readdirSync(shellSnapshotsDir).filter((entry) => entry.startsWith(`${threadId}.`) && entry.endsWith(".sh")).map((entry) => path3.join(shellSnapshotsDir, entry));
+}
+
+// src/commands/purge.ts
+function planPurgeCommand(paths, threadId) {
+  validateSupportedDataModel(paths);
+  const target = resolvePurgeTarget(paths, threadId);
+  return buildPurgePlan(paths, target);
+}
+function executePurgePlanCommand(paths, plan) {
+  validateSupportedDataModel(paths, { requireBackupHome: true });
+  return executePurge(paths, plan);
+}
+
+// src/core/output.ts
+function printOutput(value, mode) {
+  if (mode === "json") {
+    console.log(JSON.stringify(value, null, 2));
+    return;
+  }
+  if (typeof value === "string") {
+    if (value.length === 0) {
+      return;
+    }
+    console.log(value);
+    return;
+  }
+  console.log(JSON.stringify(value, null, 2));
+}
+function formatDate(valueMs) {
+  if (valueMs === null || Number.isNaN(valueMs)) {
+    return "-";
+  }
+  return new Date(valueMs).toISOString();
+}
+function shortId(id) {
+  return id.length <= 8 ? id : id.slice(0, 8);
+}
+
+// src/cli.ts
+var TITLE_MAX_LENGTH = 80;
+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.command("doctor").description("Check whether the local Codex data model is supported.").action(
+  () => runCommand(() => {
+    const report = doctorCommand(currentPaths());
+    if (!report.supported) {
+      process.exitCode = 1;
+    }
+    return formatDoctor(report);
+  })
+);
+program.command("list").description("List local Codex conversations.").option("--limit <number>", "Maximum rows to show", parseInteger).option("--all", "Include archived and non-archived threads").option("--archived", "Show archived threads").option("--cwd <path>", "Filter by exact working directory").option("--grep <keyword>", "Filter by title, id, or cwd keyword").option("--pretty <format>", "Output format: oneline, medium, full", parsePretty, "oneline").action(
+  (options) => runCommand(
+    () => formatThreads(
+      listCommand(currentPaths(), {
+        limit: options.limit,
+        all: options.all,
+        archived: options.archived,
+        cwd: options.cwd,
+        grep: options.grep
+      }),
+      options.pretty,
+      shouldUsePager(options)
+    )
+  )
+);
+program.command("purge").argument("<threadId>", "Codex thread id or unique short id prefix to purge").option("--force", "Skip interactive confirmation").description("Purge one local Codex conversation after target confirmation.").action(
+  (threadId, options) => runCommand(async () => {
+    const paths = currentPaths();
+    const plan = planPurgeCommand(paths, threadId);
+    const force = Boolean(options.force);
+    if (currentOutputModeIsJson() && !force) {
+      throw new UsageError("JSON purge output requires --force because interactive confirmation is text-only.");
+    }
+    if (!force) {
+      await confirmPurge(plan);
+    }
+    return formatPurgeResult(executePurgePlanCommand(paths, plan));
+  })
+);
+await program.parseAsync();
+function currentOutputMode() {
+  return program.opts().json ? "json" : "text";
+}
+function currentPaths() {
+  return resolvePaths(program.opts().codexHome);
+}
+async function runCommand(produce) {
+  try {
+    printOutput(await produce(), currentOutputMode());
+  } catch (error) {
+    const exitCode = error instanceof CodexHistoryError ? error.exitCode : 1;
+    const message = error instanceof Error ? error.message : String(error);
+    if (currentOutputMode() === "json") {
+      console.error(JSON.stringify({ error: message, exitCode }, null, 2));
+    } else {
+      console.error(`${colorizeError("red", "Error:")} ${message}`);
+    }
+    process.exitCode = exitCode;
+  }
+}
+function parseInteger(value) {
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isFinite(parsed) || parsed < 1) {
+    throw new Error(`Expected positive integer, got: ${value}`);
+  }
+  return parsed;
+}
+function parsePretty(value) {
+  if (value === "oneline" || value === "medium" || value === "full") {
+    return value;
+  }
+  throw new Error(`Expected pretty format oneline, medium, or full; got: ${value}`);
+}
+function shouldUsePager(options) {
+  return Boolean(options.limit === void 0 && process.stdout.isTTY && !currentOutputModeIsJson());
+}
+function currentOutputModeIsJson() {
+  return currentOutputMode() === "json";
+}
+async function confirmPurge(plan) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    throw new SafetyRefusalError("Purge requires an interactive terminal. Use --force to skip confirmation.");
+  }
+  const expected = shortId(plan.target.id);
+  process.stdout.write(formatPurgeConfirmation(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;
+  }
+  const lines = [
+    `${colorize("dim", "Codex home:")} ${colorize("dim", report.codexHome)}`,
+    `${colorize("dim", "Supported:")} ${report.supported ? colorize("green", "yes") : colorize("red", "no")}`,
+    "",
+    ...report.checks.map(
+      (check) => `${formatCheckStatus(check.status)} ${check.name}: ${check.detail}`
+    )
+  ];
+  return lines.join("\n");
+}
+function formatThreads(threads, pretty = "oneline", usePager = false) {
+  if (currentOutputMode() === "json") {
+    return { count: threads.length, threads: threads.map(toPublicThread) };
+  }
+  if (threads.length === 0) {
+    return "No Codex conversations found.";
+  }
+  const text = threads.map((thread) => formatThread(thread, pretty)).join(pretty === "oneline" ? "\n" : "\n\n");
+  return usePager ? pageText(text) : text;
+}
+function formatThread(thread, pretty) {
+  const header = `${colorize("yellow", shortId(thread.id))}  ${displayTitle(thread.title)}`;
+  if (pretty === "oneline") {
+    return header;
+  }
+  const mediumLines = [
+    header,
+    `  ${colorize("dim", "id:")} ${colorize("yellow", thread.id)}`,
+    `  ${colorize("dim", "updated:")} ${formatDate(thread.updatedAtMs)}`,
+    `  ${colorize("dim", "cwd:")} ${colorize("dim", thread.cwd)}`
+  ];
+  if (pretty === "medium") {
+    return mediumLines.join("\n");
+  }
+  return [
+    ...mediumLines,
+    `  ${colorize("dim", "created:")} ${formatDate(thread.createdAtMs)}`,
+    `  ${colorize("dim", "archived:")} ${thread.archived}`,
+    `  ${colorize("dim", "rollout:")} ${colorize("dim", thread.rolloutPath)}`
+  ].join("\n");
+}
+function pageText(text) {
+  const pagerCommand = process.env.PAGER || "less";
+  const [pager, ...configuredArgs] = pagerCommand.split(/\s+/).filter(Boolean);
+  const pagerArgs = configuredArgs.length === 0 && pager?.endsWith("less") ? ["-FRX"] : configuredArgs;
+  if (!pager) {
+    return text;
+  }
+  const result = spawnSync(pager, pagerArgs, {
+    input: text,
+    stdio: ["pipe", "inherit", "inherit"],
+    encoding: "utf8"
+  });
+  if (result.error) {
+    return text;
+  }
+  return "";
+}
+function formatPurgeResult(result) {
+  if (currentOutputMode() === "json") {
+    return sanitizePurgeResult(result);
+  }
+  const lines = [
+    colorize("green", "Purge executed."),
+    "",
+    `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)`),
+    "",
+    "JSON changes:",
+    ...result.json.map((change) => `- ${change.changed ? "changed" : "unchanged"}: ${colorize("dim", change.path)}`),
+    "",
+    "File changes:",
+    ...result.files.map((change) => `- ${change.deleted ? "deleted" : "missing"}: ${colorize("dim", change.path)}`),
+    "",
+    `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:",
+    "",
+    `title: ${displayTitle(plan.target.title)}`,
+    `id: ${plan.target.id}`,
+    `cwd: ${colorize("dim", plan.target.cwd)}`,
+    `updated: ${formatDate(plan.target.updatedAtMs)}`,
+    "",
+    colorize("dim", "A backup will be created before deletion."),
+    ""
+  ].join("\n");
+}
+function formatCheckStatus(status) {
+  const label = status.toUpperCase().padEnd(7);
+  if (status === "ok") {
+    return colorize("green", label);
+  }
+  if (status === "warning") {
+    return colorize("yellow", label);
+  }
+  if (status === "error") {
+    return colorize("red", label);
+  }
+  return label;
+}
+function colorize(color, value) {
+  return applyColor(color, value, colorsEnabled());
+}
+function colorizeError(color, value) {
+  return applyColor(color, value, errorColorsEnabled());
+}
+function applyColor(color, value, enabled) {
+  if (!enabled) {
+    return value;
+  }
+  const codes = {
+    dim: [2, 22],
+    green: [32, 39],
+    red: [31, 39],
+    yellow: [33, 39]
+  };
+  const [open, close] = codes[color];
+  return `\x1B[${open}m${value}\x1B[${close}m`;
+}
+function colorsEnabled() {
+  return streamColorsEnabled(process.stdout);
+}
+function errorColorsEnabled() {
+  return streamColorsEnabled(process.stderr);
+}
+function streamColorsEnabled(stream) {
+  return !currentOutputModeIsJson() && !("NO_COLOR" in process.env) && Boolean(stream.isTTY);
+}
+function displayTitle(title) {
+  const normalized = title.trim().replaceAll(/\s+/g, " ");
+  if (!normalized) {
+    return "(untitled)";
+  }
+  if (normalized.length <= TITLE_MAX_LENGTH) {
+    return normalized;
+  }
+  return `${normalized.slice(0, TITLE_MAX_LENGTH - 3)}...`;
+}
+function toPublicThread(thread) {
+  return {
+    id: thread.id,
+    title: displayTitle(thread.title),
+    titleTruncated: thread.title.trim().replaceAll(/\s+/g, " ").length > TITLE_MAX_LENGTH,
+    rolloutPath: thread.rolloutPath,
+    createdAtMs: thread.createdAtMs,
+    updatedAtMs: thread.updatedAtMs,
+    cwd: thread.cwd,
+    archived: thread.archived
+  };
+}
+function sanitizePurgeResult(result) {
+  return {
+    ...result,
+    plan: {
+      ...result.plan,
+      target: toPublicThread(result.plan.target)
+    }
+  };
+}