@ulpi/cli 0.1.0

package/dist/chunk-NNUWU6CV.js

@@ -0,0 +1,1610 @@
+import {
+  JsonSessionStore,
+  readEvents
+} from "./chunk-YM2HV4IA.js";
+import {
+  DEFAULT_AI_MODEL,
+  REVIEWS_DIR,
+  REVIEW_IMAGES_DIR,
+  getHistoryBranch,
+  projectGuardsFile,
+  projectGuardsFileAlt
+} from "./chunk-7LXY5UVC.js";
+
+// ../../packages/history-engine/dist/index.js
+import { execFileSync } from "child_process";
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+import * as fs2 from "fs";
+import * as path2 from "path";
+import * as os2 from "os";
+import * as fs3 from "fs";
+import * as path3 from "path";
+import { createHash } from "crypto";
+import * as fs4 from "fs";
+import * as fs5 from "fs";
+import * as path4 from "path";
+var EXEC_TIMEOUT = 1e4;
+var MAX_BUFFER = 5e7;
+function validateSha(sha) {
+  if (!/^[0-9a-f]{4,40}$/i.test(sha)) {
+    throw new Error("Invalid SHA");
+  }
+}
+function validateWorktreeDir(dir) {
+  if (!dir || !path.isAbsolute(dir)) {
+    throw new Error("Invalid worktree directory: must be absolute path");
+  }
+}
+function validateBranchPath(filePath) {
+  if (filePath.includes("..") || filePath.startsWith("/")) {
+    throw new Error("Invalid branch path");
+  }
+}
+function gitExec(projectDir, args, opts) {
+  const timeout = opts?.timeout ?? EXEC_TIMEOUT;
+  return execFileSync("git", args, {
+    cwd: projectDir,
+    encoding: "utf-8",
+    timeout,
+    stdio: ["pipe", "pipe", "pipe"],
+    input: opts?.input,
+    maxBuffer: MAX_BUFFER
+  }).trim();
+}
+function historyBranchExists(projectDir, branchName) {
+  branchName ??= getHistoryBranch();
+  try {
+    gitExec(projectDir, ["rev-parse", "--verify", `refs/heads/${branchName}`]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function initHistoryBranch(projectDir, projectName, ulpiVersion, branchName) {
+  branchName ??= getHistoryBranch();
+  if (historyBranchExists(projectDir, branchName)) {
+    throw new Error(`Branch "${branchName}" already exists`);
+  }
+  const readme = [
+    `# ULPI History: ${projectName}`,
+    "",
+    "This branch is maintained by [ULPI](https://github.com/nicholasgriffintn/ulpi).",
+    "It stores session metadata for each commit \u2014 separately from your code.",
+    "",
+    "## How It Works",
+    "",
+    "- Each commit on your code branches gets a corresponding entry here",
+    "- Entries include: git metadata, diff stats, session state, events, active rules",
+    "- AI enrichment can be added with `ulpi history enrich`",
+    "",
+    "## Browse",
+    "",
+    "| Date | Commit | Branch | Summary | Files | Session | Review | AI |",
+    "|------|--------|--------|---------|-------|---------|--------|----|",
+    "| _(no entries yet)_ | | | | | | | |",
+    "",
+    `_Last updated: ${(/* @__PURE__ */ new Date()).toISOString()}_`
+  ].join("\n");
+  const meta = JSON.stringify(
+    {
+      version: 1,
+      createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+      projectDir,
+      projectName,
+      totalEntries: 0,
+      ulpiVersion,
+      config: {
+        enabled: true,
+        branchName,
+        aiEnrichment: true,
+        aiModel: DEFAULT_AI_MODEL,
+        maxDiffSize: 5e4,
+        maxAiDiffSize: 1e4,
+        collectReviewPlans: false,
+        captureTranscript: true,
+        maxTranscriptSize: 5242880,
+        captureStrategy: "session-end"
+      }
+    },
+    null,
+    2
+  );
+  const timeline = JSON.stringify(
+    {
+      version: 1,
+      updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      projectDir,
+      entries: []
+    },
+    null,
+    2
+  );
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "ulpi-init-"));
+  try {
+    const readmePath = path.join(tmpDir, "README.md");
+    const metaPath = path.join(tmpDir, "meta.json");
+    const timelinePath = path.join(tmpDir, "timeline.json");
+    fs.writeFileSync(readmePath, readme, "utf-8");
+    fs.writeFileSync(metaPath, meta, "utf-8");
+    fs.writeFileSync(timelinePath, timeline, "utf-8");
+    const readmeHash = gitExec(projectDir, [
+      "hash-object",
+      "-w",
+      readmePath
+    ]);
+    const metaHash = gitExec(projectDir, ["hash-object", "-w", metaPath]);
+    const timelineHash = gitExec(projectDir, [
+      "hash-object",
+      "-w",
+      timelinePath
+    ]);
+    const emptyTreeHash = gitExec(projectDir, ["mktree", "--missing"], { input: "" });
+    const treeContent = [
+      `100644 blob ${readmeHash}	README.md`,
+      `100644 blob ${metaHash}	meta.json`,
+      `100644 blob ${timelineHash}	timeline.json`,
+      `040000 tree ${emptyTreeHash}	entries`
+    ].join("\n");
+    const treeHash = gitExec(projectDir, ["mktree"], { input: treeContent });
+    const commitHash = gitExec(projectDir, [
+      "commit-tree",
+      treeHash,
+      "-m",
+      "chore: initialize ulpi history branch"
+    ]);
+    gitExec(projectDir, [
+      "update-ref",
+      `refs/heads/${branchName}`,
+      commitHash
+    ]);
+  } finally {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  }
+}
+function getCommitMetadata(projectDir, sha) {
+  validateSha(sha);
+  const format = "%H%n%h%n%s%n%B%n%an%n%ae%n%aI";
+  const raw = gitExec(projectDir, [
+    "log",
+    "-1",
+    `--format=${format}`,
+    sha
+  ]);
+  const lines = raw.split("\n");
+  const fullSha = lines[0];
+  const shortSha = lines[1];
+  const subject = lines[2];
+  const authorName = lines[lines.length - 3];
+  const authorEmail = lines[lines.length - 2];
+  const authorDate = lines[lines.length - 1];
+  const message = lines.slice(3, lines.length - 3).join("\n").trim();
+  const parentsRaw = gitExec(projectDir, [
+    "log",
+    "-1",
+    "--format=%P",
+    sha
+  ]);
+  const parents = parentsRaw ? parentsRaw.split(" ").filter(Boolean) : [];
+  let branch = "unknown";
+  try {
+    const refs = gitExec(projectDir, [
+      "log",
+      "-1",
+      "--format=%D",
+      sha
+    ]);
+    if (refs) {
+      const branchRef = refs.split(",").map((r) => r.trim()).find((r) => r.startsWith("HEAD -> "));
+      if (branchRef) {
+        branch = branchRef.replace("HEAD -> ", "");
+      } else {
+        const localRef = refs.split(",").map((r) => r.trim()).find((r) => !r.startsWith("origin/") && !r.startsWith("tag:") && r !== "HEAD");
+        if (localRef) branch = localRef;
+      }
+    }
+  } catch {
+  }
+  return {
+    sha: fullSha,
+    shortSha,
+    message: message || subject,
+    subject,
+    authorName,
+    authorEmail,
+    authorDate,
+    branch,
+    parents
+  };
+}
+function getCommitDiffStats(projectDir, sha) {
+  validateSha(sha);
+  let raw;
+  try {
+    raw = gitExec(projectDir, [
+      "diff-tree",
+      "--numstat",
+      "-r",
+      "--no-commit-id",
+      sha
+    ]);
+  } catch {
+    return { filesChanged: 0, insertions: 0, deletions: 0, files: [] };
+  }
+  if (!raw) {
+    return { filesChanged: 0, insertions: 0, deletions: 0, files: [] };
+  }
+  const files = [];
+  let totalInsertions = 0;
+  let totalDeletions = 0;
+  for (const line of raw.split("\n")) {
+    if (!line.trim()) continue;
+    const parts = line.split("	");
+    if (parts.length < 3) continue;
+    const additions = parts[0] === "-" ? 0 : parseInt(parts[0], 10);
+    const deletions = parts[1] === "-" ? 0 : parseInt(parts[1], 10);
+    const filePath = parts[2];
+    let status = "modified";
+    let oldPathValue;
+    if (filePath.includes(" => ")) {
+      status = "renamed";
+      const match = filePath.match(/^(.+) => (.+)$/);
+      if (match) {
+        oldPathValue = match[1];
+      }
+    }
+    totalInsertions += additions;
+    totalDeletions += deletions;
+    files.push({
+      path: filePath,
+      status,
+      additions,
+      deletions,
+      oldPath: oldPathValue
+    });
+  }
+  try {
+    const statusRaw = gitExec(projectDir, [
+      "diff-tree",
+      "-r",
+      "--no-commit-id",
+      "--name-status",
+      sha
+    ]);
+    const statusMap = /* @__PURE__ */ new Map();
+    for (const line of statusRaw.split("\n")) {
+      if (!line.trim()) continue;
+      const [flag, ...rest] = line.split("	");
+      const fPath = rest[rest.length - 1];
+      if (flag && fPath) statusMap.set(fPath, flag[0]);
+    }
+    for (const file of files) {
+      const flag = statusMap.get(file.path);
+      if (flag === "A") file.status = "added";
+      else if (flag === "D") file.status = "deleted";
+      else if (flag === "R") file.status = "renamed";
+      else if (flag === "C") file.status = "copied";
+    }
+  } catch {
+  }
+  return {
+    filesChanged: files.length,
+    insertions: totalInsertions,
+    deletions: totalDeletions,
+    files
+  };
+}
+function getCommitRawDiff(projectDir, sha, maxSize = 5e4) {
+  validateSha(sha);
+  let raw;
+  try {
+    raw = gitExec(projectDir, ["diff-tree", "-p", "--no-commit-id", sha]);
+  } catch {
+    return { diff: "", truncated: false };
+  }
+  if (raw.length > maxSize) {
+    return {
+      diff: raw.slice(0, maxSize) + "\n\n... (truncated)",
+      truncated: true
+    };
+  }
+  return { diff: raw, truncated: false };
+}
+function getCurrentHead(projectDir) {
+  try {
+    return gitExec(projectDir, ["rev-parse", "HEAD"]);
+  } catch {
+    return null;
+  }
+}
+function listCommitsBetween(projectDir, startSha, endSha) {
+  validateSha(startSha);
+  validateSha(endSha);
+  try {
+    const raw = gitExec(projectDir, [
+      "rev-list",
+      "--reverse",
+      `${startSha}..${endSha}`
+    ]);
+    return raw ? raw.split("\n").filter(Boolean) : [];
+  } catch {
+    return [];
+  }
+}
+function listRecentCommits(projectDir, maxCount = 20) {
+  try {
+    const raw = gitExec(projectDir, [
+      "rev-list",
+      "--reverse",
+      "HEAD",
+      `--max-count=${maxCount}`
+    ]);
+    return raw ? raw.split("\n").filter(Boolean) : [];
+  } catch {
+    return [];
+  }
+}
+function readFromBranch(projectDir, filePath, branchName) {
+  branchName ??= getHistoryBranch();
+  validateBranchPath(filePath);
+  try {
+    return gitExec(projectDir, [
+      "show",
+      `${branchName}:${filePath}`
+    ]);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (message.includes("does not exist") || message.includes("not found") || message.includes("exists on disk, but not in")) {
+      return null;
+    }
+    if (typeof process !== "undefined" && process.env?.ULPI_DEBUG) {
+      console.error(`[ulpi] readFromBranch error for "${filePath}":`, message);
+    }
+    return null;
+  }
+}
+function listBranchDir(projectDir, dirPath, branchName) {
+  branchName ??= getHistoryBranch();
+  validateBranchPath(dirPath);
+  try {
+    const raw = gitExec(projectDir, [
+      "ls-tree",
+      "--name-only",
+      `${branchName}:${dirPath}`
+    ]);
+    return raw ? raw.split("\n").filter(Boolean) : [];
+  } catch {
+    return [];
+  }
+}
+function getWorktreeId(projectDir) {
+  try {
+    const gitPath = path.join(projectDir, ".git");
+    const stat = fs.statSync(gitPath);
+    if (stat.isDirectory()) return null;
+    const content = fs.readFileSync(gitPath, "utf-8").trim();
+    const match = content.match(/worktrees\/([^/\s]+)/);
+    return match ? match[1] : null;
+  } catch {
+    return null;
+  }
+}
+var LOCK_TIMEOUT_MS = 1e4;
+var LOCK_RETRY_MS = 200;
+var LOCK_STALE_MS = 6e4;
+function getLockPath(branchName, projectDir) {
+  const safeName = branchName.replace(/\//g, "-");
+  const worktreeId = projectDir ? getWorktreeId(projectDir) : null;
+  const suffix = worktreeId ? `-${worktreeId}` : "";
+  return path.join(os.tmpdir(), `ulpi-worktree-${safeName}${suffix}.lock`);
+}
+function acquireLock(branchName, projectDir) {
+  const lockPath = getLockPath(branchName, projectDir);
+  const deadline = Date.now() + LOCK_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    try {
+      const fd = fs.openSync(lockPath, "wx");
+      const info = JSON.stringify({ pid: process.pid, ts: Date.now() });
+      fs.writeSync(fd, info);
+      fs.closeSync(fd);
+      return;
+    } catch (err) {
+      if (err.code !== "EEXIST") throw err;
+      try {
+        const raw = fs.readFileSync(lockPath, "utf-8");
+        const lock = JSON.parse(raw);
+        const isStale = Date.now() - lock.ts > LOCK_STALE_MS || !isProcessAlive(lock.pid);
+        if (isStale) {
+          fs.unlinkSync(lockPath);
+          continue;
+        }
+      } catch {
+        try {
+          fs.unlinkSync(lockPath);
+        } catch {
+        }
+        continue;
+      }
+      const waitMs = Math.min(LOCK_RETRY_MS, deadline - Date.now());
+      if (waitMs > 0) {
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, waitMs);
+      }
+    }
+  }
+  throw new Error(`Timed out waiting for worktree lock on ${branchName}`);
+}
+function releaseLock(branchName, projectDir) {
+  try {
+    fs.unlinkSync(getLockPath(branchName, projectDir));
+  } catch {
+  }
+}
+function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function withWorktree(projectDir, branchName, callback) {
+  const worktreeDir = path.join(
+    os.tmpdir(),
+    `ulpi-worktree-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
+  );
+  acquireLock(branchName, projectDir);
+  let worktreeAdded = false;
+  try {
+    gitExec(projectDir, [
+      "worktree",
+      "add",
+      worktreeDir,
+      branchName
+    ]);
+    worktreeAdded = true;
+    return await callback(worktreeDir);
+  } finally {
+    if (worktreeAdded) {
+      try {
+        gitExec(projectDir, ["worktree", "remove", "--force", worktreeDir]);
+      } catch {
+        try {
+          fs.rmSync(worktreeDir, { recursive: true, force: true });
+          gitExec(projectDir, ["worktree", "prune"]);
+        } catch {
+        }
+      }
+    } else {
+      try {
+        fs.rmSync(worktreeDir, { recursive: true, force: true });
+      } catch {
+      }
+    }
+    releaseLock(branchName, projectDir);
+  }
+}
+function writeAndStage(worktreeDir, relativePath, content) {
+  validateWorktreeDir(worktreeDir);
+  validateBranchPath(relativePath);
+  const fullPath = path.join(worktreeDir, relativePath);
+  fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+  if (typeof content === "string") {
+    fs.writeFileSync(fullPath, content, "utf-8");
+  } else {
+    fs.writeFileSync(fullPath, content);
+  }
+  gitExec(worktreeDir, ["add", relativePath]);
+}
+function copyAndStage(worktreeDir, relativePath, sourcePath) {
+  validateWorktreeDir(worktreeDir);
+  validateBranchPath(relativePath);
+  const fullPath = path.join(worktreeDir, relativePath);
+  fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+  fs.copyFileSync(sourcePath, fullPath);
+  gitExec(worktreeDir, ["add", relativePath]);
+}
+function commitInWorktree(worktreeDir, message) {
+  validateWorktreeDir(worktreeDir);
+  try {
+    gitExec(worktreeDir, ["diff", "--cached", "--quiet"]);
+    return gitExec(worktreeDir, ["rev-parse", "HEAD"]);
+  } catch {
+  }
+  gitExec(worktreeDir, ["commit", "-m", message]);
+  return gitExec(worktreeDir, ["rev-parse", "HEAD"]);
+}
+function buildSessionSummary(state, events) {
+  const eventCounts = countEventsByType(events);
+  const blockedTools = /* @__PURE__ */ new Set();
+  const autoApproved = /* @__PURE__ */ new Set();
+  const preconditionsFired = /* @__PURE__ */ new Set();
+  const postconditionsRun = /* @__PURE__ */ new Set();
+  const skillsInjected = /* @__PURE__ */ new Set();
+  for (const ev of events) {
+    if (ev.event === "tool_blocked" && ev.toolName) {
+      blockedTools.add(ev.toolName);
+    }
+    if (ev.event === "permission_allow" && ev.toolName) {
+      autoApproved.add(ev.command ?? ev.toolName);
+    }
+    if (ev.event === "tool_blocked" && ev.ruleName && ev.hookEvent === "PreToolUse") {
+      preconditionsFired.add(ev.ruleName);
+    }
+    if ((ev.event === "postcondition_run" || ev.event === "postcondition_failed") && ev.command) {
+      postconditionsRun.add(ev.command);
+    }
+    if (ev.event === "skill_injected" && ev.message) {
+      skillsInjected.add(ev.message);
+    }
+  }
+  return {
+    sessionId: state.sessionId,
+    sessionName: state.sessionName,
+    totalEvents: events.length,
+    eventCounts,
+    blockedTools: [...blockedTools],
+    autoApproved: [...autoApproved],
+    preconditionsFired: [...preconditionsFired],
+    postconditionsRun: [...postconditionsRun],
+    skillsInjected: [...skillsInjected],
+    stats: {
+      filesRead: state.filesRead.length,
+      filesWritten: state.filesWritten.length,
+      filesDeleted: state.filesDeleted.length,
+      commandsRun: state.commandsRun.length,
+      rulesEnforced: state.rulesEnforced,
+      actionsBlocked: state.actionsBlocked,
+      autoActionsRun: state.autoActionsRun,
+      testsRun: state.testsRun,
+      testsPassed: state.testsPassed,
+      lintRun: state.lintRun,
+      buildRun: state.buildRun
+    }
+  };
+}
+function countEventsByType(events) {
+  const counts = {};
+  for (const ev of events) {
+    counts[ev.event] = (counts[ev.event] ?? 0) + 1;
+  }
+  return counts;
+}
+function findSessionForCommit(projectDir, commitDate) {
+  const commitTime = new Date(commitDate).getTime();
+  if (isNaN(commitTime)) return null;
+  const store = new JsonSessionStore(void 0, projectDir);
+  const sessionIds = store.listByProject(projectDir);
+  let bestMatch = null;
+  let bestDistance = Infinity;
+  for (const id of sessionIds) {
+    const state = store.load(id);
+    if (!state) continue;
+    const startTime = new Date(state.startedAt).getTime();
+    if (isNaN(startTime) || startTime > commitTime) continue;
+    const events = readEvents(id, projectDir);
+    if (events.length === 0) continue;
+    const lastEventTs = new Date(events[events.length - 1].ts).getTime();
+    if (startTime <= commitTime && lastEventTs >= commitTime) {
+      const distance = commitTime - startTime;
+      if (distance < bestDistance) {
+        bestDistance = distance;
+        bestMatch = { state, events };
+      }
+    }
+  }
+  if (bestMatch) return bestMatch;
+  const legacyBase = path2.join(os2.homedir(), ".ulpi", "hooks");
+  try {
+    const legacyStore = new JsonSessionStore(legacyBase);
+    const legacyIds = legacyStore.list();
+    for (const id of legacyIds) {
+      const state = legacyStore.load(id);
+      if (!state) continue;
+      const startTime = new Date(state.startedAt).getTime();
+      if (isNaN(startTime) || startTime > commitTime) continue;
+      const events = readEvents(id, void 0, legacyBase);
+      if (events.length === 0) continue;
+      const lastEventTs = new Date(events[events.length - 1].ts).getTime();
+      if (startTime <= commitTime && lastEventTs >= commitTime) {
+        const distance = commitTime - startTime;
+        if (distance < bestDistance) {
+          bestDistance = distance;
+          bestMatch = { state, events };
+        }
+      }
+    }
+  } catch {
+  }
+  return bestMatch;
+}
+function loadActiveGuards(projectDir) {
+  const paths = [
+    projectGuardsFile(projectDir),
+    projectGuardsFileAlt(projectDir)
+  ];
+  for (const p of paths) {
+    try {
+      return fs2.readFileSync(p, "utf-8");
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+function findReviewPlansForCommit(commitDate, sessionStartDate, projectDir) {
+  const reviewPlansDir = REVIEWS_DIR;
+  if (!fs2.existsSync(reviewPlansDir)) return null;
+  const commitTime = new Date(commitDate).getTime();
+  const startTime = sessionStartDate ? new Date(sessionStartDate).getTime() : commitTime - 24 * 60 * 60 * 1e3;
+  if (isNaN(commitTime) || isNaN(startTime)) return null;
+  const snapshots = [];
+  const rawData = [];
+  let entries;
+  try {
+    entries = fs2.readdirSync(reviewPlansDir, { withFileTypes: true });
+  } catch {
+    return null;
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const planDir = path2.join(reviewPlansDir, entry.name);
+    const planJsonPath = path2.join(planDir, "plan.json");
+    let planContent;
+    try {
+      planContent = fs2.readFileSync(planJsonPath, "utf-8");
+    } catch {
+      continue;
+    }
+    let plan;
+    try {
+      plan = JSON.parse(planContent);
+    } catch {
+      continue;
+    }
+    if (!plan.title || !plan.slug || !plan.version) continue;
+    if (projectDir) {
+      const planProjectPath = plan.projectPath;
+      if (!planProjectPath) {
+        continue;
+      }
+      if (path2.resolve(planProjectPath) !== path2.resolve(projectDir)) {
+        continue;
+      }
+    }
+    let matched = false;
+    if (plan.version.createdAt >= startTime && plan.version.createdAt <= commitTime) {
+      matched = true;
+    }
+    const versions = [];
+    try {
+      const planFiles = fs2.readdirSync(planDir);
+      for (const f of planFiles) {
+        if (/^v\d+\.json$/.test(f)) {
+          try {
+            const vContent = fs2.readFileSync(path2.join(planDir, f), "utf-8");
+            versions.push({ filename: f, content: vContent });
+            const vData = JSON.parse(vContent);
+            if (vData.createdAt && vData.createdAt >= startTime && vData.createdAt <= commitTime) {
+              matched = true;
+            }
+          } catch {
+            continue;
+          }
+        }
+      }
+    } catch {
+    }
+    if (!matched) continue;
+    const imageFiles = [];
+    const imageRawData = [];
+    const allAnnotations = [
+      ...plan.version.annotations ?? []
+    ];
+    for (const v of versions) {
+      try {
+        const vData = JSON.parse(v.content);
+        if (vData.annotations) {
+          allAnnotations.push(...vData.annotations);
+        }
+      } catch {
+      }
+    }
+    for (const ann of allAnnotations) {
+      if (!ann.imagePaths) continue;
+      for (const imgPath of ann.imagePaths) {
+        const filename = path2.basename(imgPath);
+        if (fs2.existsSync(imgPath)) {
+          imageFiles.push(filename);
+          imageRawData.push({ filename, sourcePath: imgPath });
+        }
+      }
+    }
+    const planImagesDir = path2.join(planDir, "images");
+    const topImagesDir = path2.join(REVIEW_IMAGES_DIR, entry.name);
+    for (const imgDir of [planImagesDir, topImagesDir]) {
+      if (!fs2.existsSync(imgDir)) continue;
+      try {
+        for (const imgFile of fs2.readdirSync(imgDir)) {
+          if (imgFile.endsWith(".png") || imgFile.endsWith(".jpg")) {
+            if (!imageFiles.includes(imgFile)) {
+              imageFiles.push(imgFile);
+              imageRawData.push({
+                filename: imgFile,
+                sourcePath: path2.join(imgDir, imgFile)
+              });
+            }
+          }
+        }
+      } catch {
+      }
+    }
+    snapshots.push({
+      title: plan.title,
+      slug: plan.slug,
+      plan: plan.plan ?? "",
+      version: plan.version,
+      imageFiles
+    });
+    rawData.push({
+      slug: plan.slug,
+      planJson: planContent,
+      versions,
+      images: imageRawData
+    });
+  }
+  return snapshots.length > 0 ? { snapshots, rawData } : null;
+}
+function buildHookDerivedData(events) {
+  const ruleMap = /* @__PURE__ */ new Map();
+  for (const ev of events) {
+    if (!ev.ruleName) continue;
+    const key = `${ev.ruleName}:${ev.hookEvent}`;
+    let entry = ruleMap.get(key);
+    if (!entry) {
+      entry = {
+        ruleName: ev.ruleName,
+        hookEvent: ev.hookEvent,
+        blockedCount: 0,
+        allowedCount: 0,
+        sampleTools: /* @__PURE__ */ new Set()
+      };
+      ruleMap.set(key, entry);
+    }
+    if (ev.event === "tool_blocked" || ev.event === "permission_deny") {
+      entry.blockedCount++;
+    } else {
+      entry.allowedCount++;
+    }
+    if (ev.toolName && entry.sampleTools.size < 5) {
+      entry.sampleTools.add(ev.toolName);
+    }
+  }
+  const ruleEvaluations = [...ruleMap.values()].map(
+    (r) => ({
+      ruleName: r.ruleName,
+      hookEvent: r.hookEvent,
+      blockedCount: r.blockedCount,
+      allowedCount: r.allowedCount,
+      sampleTools: [...r.sampleTools]
+    })
+  );
+  const permMap = /* @__PURE__ */ new Map();
+  for (const ev of events) {
+    if (ev.hookEvent !== "PermissionRequest") continue;
+    let decision;
+    if (ev.event === "permission_allow") {
+      decision = "allow";
+    } else if (ev.event === "permission_deny") {
+      decision = "deny";
+    } else {
+      continue;
+    }
+    const key = `${decision}:${ev.toolName ?? ""}:${ev.command ?? ""}`;
+    let entry = permMap.get(key);
+    if (!entry) {
+      entry = {
+        decision,
+        toolName: ev.toolName ?? "unknown",
+        command: ev.command,
+        ruleName: ev.ruleName,
+        count: 0
+      };
+      permMap.set(key, entry);
+    }
+    entry.count++;
+  }
+  const permissionDecisions = [
+    ...permMap.values()
+  ];
+  const postconditionResults = [];
+  for (const ev of events) {
+    if (ev.event !== "postcondition_run" && ev.event !== "postcondition_failed") {
+      continue;
+    }
+    if (!ev.command) continue;
+    postconditionResults.push({
+      command: ev.command,
+      succeeded: ev.event === "postcondition_run",
+      durationMs: ev.durationMs,
+      ruleName: ev.ruleName
+    });
+  }
+  const toolMap = /* @__PURE__ */ new Map();
+  for (const ev of events) {
+    if (!ev.toolName) continue;
+    let entry = toolMap.get(ev.toolName);
+    if (!entry) {
+      entry = { allowed: 0, blocked: 0, total: 0 };
+      toolMap.set(ev.toolName, entry);
+    }
+    entry.total++;
+    if (ev.event === "tool_blocked" || ev.event === "permission_deny") {
+      entry.blocked++;
+    } else {
+      entry.allowed++;
+    }
+  }
+  const toolUsageProfile = [...toolMap.entries()].map(([toolName, counts]) => ({ toolName, ...counts })).sort((a, b) => b.total - a.total);
+  let totalMs = 0;
+  let maxMs = 0;
+  let timedCount = 0;
+  const countByHook = {};
+  for (const ev of events) {
+    countByHook[ev.hookEvent] = (countByHook[ev.hookEvent] ?? 0) + 1;
+    if (ev.durationMs !== void 0) {
+      totalMs += ev.durationMs;
+      timedCount++;
+      if (ev.durationMs > maxMs) maxMs = ev.durationMs;
+    }
+  }
+  const hookTiming = {
+    totalMs,
+    averageMs: timedCount > 0 ? Math.round(totalMs / timedCount) : 0,
+    maxMs,
+    countByHook
+  };
+  const userMessages = [];
+  for (const ev of events) {
+    if (ev.event === "user_message" && ev.message) {
+      userMessages.push({
+        ts: ev.ts,
+        message: ev.message
+      });
+    }
+  }
+  const conversationFlow = [];
+  let currentTurn = null;
+  for (const ev of events) {
+    if (ev.event === "user_message") {
+      currentTurn = {
+        userMessage: ev.message,
+        ts: ev.ts,
+        toolsInvoked: [],
+        blocked: false
+      };
+      conversationFlow.push(currentTurn);
+    } else if (currentTurn) {
+      if (ev.toolName && !currentTurn.toolsInvoked.includes(ev.toolName)) {
+        currentTurn.toolsInvoked.push(ev.toolName);
+      }
+      if (ev.event === "tool_blocked" || ev.event === "permission_deny") {
+        currentTurn.blocked = true;
+      }
+    }
+  }
+  return {
+    ruleEvaluations,
+    permissionDecisions,
+    postconditionResults,
+    toolUsageProfile,
+    hookTiming,
+    userMessages,
+    conversationFlow
+  };
+}
+function buildPrePromptSnapshot(state) {
+  if (!state.headAtStart) return null;
+  return {
+    head: state.headAtStart,
+    branch: state.branch ?? "unknown",
+    untrackedFiles: state.untrackedFilesAtStart ?? [],
+    workingTreeDirty: state.workingTreeDirtyAtStart ?? false,
+    capturedAt: state.startedAt
+  };
+}
+function generateReadme(meta, timeline) {
+  const lines = [];
+  lines.push(`# ULPI History: ${meta.projectName}`);
+  lines.push("");
+  lines.push(
+    "This branch is maintained by [ULPI](https://github.com/nicholasgriffintn/ulpi)."
+  );
+  lines.push(
+    "It stores session metadata for each commit \u2014 separately from your code."
+  );
+  lines.push("");
+  lines.push("## Overview");
+  lines.push("");
+  lines.push(`| Stat | Value |`);
+  lines.push(`|------|-------|`);
+  lines.push(`| Total entries | ${meta.totalEntries} |`);
+  lines.push(`| Branch created | ${formatDate(meta.createdAt)} |`);
+  if (meta.lastCaptureAt) {
+    lines.push(`| Last capture | ${formatDate(meta.lastCaptureAt)} |`);
+  }
+  lines.push(`| ULPI version | ${meta.ulpiVersion} |`);
+  if (meta.config.collectReviewPlans) {
+    lines.push(`| Review plan collection | Enabled |`);
+  }
+  lines.push("");
+  const recentEntries = timeline.entries.slice(0, 50);
+  lines.push("## Recent Activity");
+  lines.push("");
+  if (recentEntries.length === 0) {
+    lines.push("_No entries yet. Commits will appear here after capture._");
+  } else {
+    lines.push(
+      "| Date | Commit | Branch | Summary | Files | Session | Review | AI | Transcript |"
+    );
+    lines.push(
+      "|------|--------|--------|---------|-------|---------|--------|----|------------|"
+    );
+    for (const entry of recentEntries) {
+      lines.push(formatTimelineRow(entry));
+    }
+    if (timeline.entries.length > 50) {
+      lines.push("");
+      lines.push(
+        `_Showing 50 of ${timeline.entries.length} entries. See \`timeline.json\` for the full list._`
+      );
+    }
+  }
+  lines.push("");
+  lines.push("## What's in Each Entry");
+  lines.push("");
+  lines.push("Each `entries/<sha>/` directory contains:");
+  lines.push("");
+  lines.push("| File | Description |");
+  lines.push("|------|-------------|");
+  lines.push(
+    "| `entry.json` | Core entry: git metadata, diff stats, session summary |"
+  );
+  lines.push("| `state.json` | Full session state snapshot |");
+  lines.push("| `events.jsonl` | Raw session events (complete audit trail) |");
+  lines.push("| `guards.yml` | Active rules at time of commit |");
+  lines.push(
+    "| `enrichment.json` | AI analysis (if enriched via `history enrich`) |"
+  );
+  lines.push(
+    "| `review/` | ULPI Review plans authored during the session |"
+  );
+  lines.push(
+    "| `transcript.jsonl` | Claude Code conversation transcript (if captured) |"
+  );
+  lines.push("");
+  lines.push("## CLI Commands");
+  lines.push("");
+  lines.push("```bash");
+  lines.push(
+    "ulpi history init          # Initialize this branch"
+  );
+  lines.push(
+    "ulpi history capture       # Capture current HEAD"
+  );
+  lines.push(
+    "ulpi history backfill 20   # Backfill last 20 commits"
+  );
+  lines.push(
+    "ulpi history list          # List entries"
+  );
+  lines.push(
+    "ulpi history show <sha>    # Show entry details"
+  );
+  lines.push(
+    "ulpi history enrich        # AI-enrich unenriched entries"
+  );
+  lines.push(
+    "ulpi history rewind <sha>  # Rewind to a captured commit"
+  );
+  lines.push("```");
+  lines.push("");
+  lines.push(`_Last updated: ${(/* @__PURE__ */ new Date()).toISOString()}_`);
+  return lines.join("\n") + "\n";
+}
+function formatDate(iso) {
+  try {
+    const d = new Date(iso);
+    return d.toLocaleDateString("en-US", {
+      month: "short",
+      day: "numeric",
+      year: "numeric"
+    });
+  } catch {
+    return iso;
+  }
+}
+function formatShortDate(iso) {
+  try {
+    const d = new Date(iso);
+    return d.toLocaleDateString("en-US", {
+      month: "short",
+      day: "numeric"
+    });
+  } catch {
+    return iso;
+  }
+}
+function formatTimelineRow(entry) {
+  const date = formatShortDate(entry.date);
+  const commit = `[\`${entry.shortSha}\`](entries/${entry.shortSha}/)`;
+  const branch = entry.branch === "unknown" ? "" : `\`${entry.branch}\``;
+  const subject = truncate(entry.subject, 50);
+  const files = String(entry.filesChanged);
+  const session = entry.hasSession ? "yes" : "--";
+  const review = entry.hasReviewPlans ? "yes" : "--";
+  const ai = entry.hasEnrichment ? "yes" : "--";
+  const transcript = entry.hasTranscript ? "yes" : "--";
+  return `| ${date} | ${commit} | ${branch} | ${subject} | ${files} | ${session} | ${review} | ${ai} | ${transcript} |`;
+}
+function truncate(str, maxLen) {
+  if (str.length <= maxLen) return str;
+  return str.slice(0, maxLen - 3) + "...";
+}
+function resolveShortSha(projectDir, sha, branchName) {
+  branchName ??= getHistoryBranch();
+  if (sha.length <= 8) return sha;
+  const timeline = readTimeline(projectDir, branchName);
+  if (timeline) {
+    const entry = timeline.entries.find(
+      (e) => e.sha === sha || sha.startsWith(e.sha)
+    );
+    if (entry) return entry.shortSha;
+  }
+  return sha.slice(0, 7);
+}
+function computeContentHash(entry) {
+  const significant = {
+    sha: entry.commit.sha,
+    diff: {
+      filesChanged: entry.diff.filesChanged,
+      insertions: entry.diff.insertions,
+      deletions: entry.diff.deletions
+    },
+    session: entry.session ? {
+      totalEvents: entry.session.totalEvents,
+      stats: entry.session.stats
+    } : null
+  };
+  return createHash("sha256").update(JSON.stringify(significant)).digest("hex");
+}
+function normalizeEntry(entry) {
+  return {
+    ...entry,
+    tags: entry.tags ?? {},
+    metadata: entry.metadata ?? {},
+    hookData: entry.hookData ?? null,
+    prePromptSnapshot: entry.prePromptSnapshot ?? null
+  };
+}
+var DEFAULT_HISTORY_CONFIG = {
+  enabled: true,
+  branchName: "ulpi/history",
+  // Legacy default; actual branch resolved via getHistoryBranch()
+  aiEnrichment: true,
+  aiModel: DEFAULT_AI_MODEL,
+  maxDiffSize: 5e4,
+  maxAiDiffSize: 1e4,
+  collectReviewPlans: false,
+  captureTranscript: true,
+  maxTranscriptSize: 5242880,
+  captureStrategy: "session-end"
+};
+async function writeHistoryEntry(projectDir, entry, rawData, branchName) {
+  branchName ??= getHistoryBranch();
+  const contentHash = computeContentHash(entry);
+  entry.contentHash = contentHash;
+  await withWorktree(projectDir, branchName, (worktreeDir) => {
+    const existing = readHistoryEntry(projectDir, entry.commit.sha, branchName);
+    if (existing?.contentHash === contentHash) return;
+    const shortSha = entry.commit.shortSha;
+    const entryDir = `entries/${shortSha}`;
+    writeAndStage(
+      worktreeDir,
+      `${entryDir}/entry.json`,
+      JSON.stringify(entry, null, 2)
+    );
+    if (rawData.state) {
+      writeAndStage(
+        worktreeDir,
+        `${entryDir}/state.json`,
+        JSON.stringify(rawData.state, null, 2)
+      );
+    }
+    if (rawData.events.length > 0) {
+      const eventsContent = rawData.events.map((e) => JSON.stringify(e)).join("\n") + "\n";
+      writeAndStage(worktreeDir, `${entryDir}/events.jsonl`, eventsContent);
+    }
+    if (rawData.guardsYaml) {
+      writeAndStage(worktreeDir, `${entryDir}/guards.yml`, rawData.guardsYaml);
+    }
+    if (rawData.reviewPlans && rawData.reviewPlans.length > 0) {
+      for (const plan of rawData.reviewPlans) {
+        const reviewDir = `${entryDir}/review/${plan.slug}`;
+        writeAndStage(worktreeDir, `${reviewDir}/plan.json`, plan.planJson);
+        for (const v of plan.versions) {
+          writeAndStage(worktreeDir, `${reviewDir}/${v.filename}`, v.content);
+        }
+        for (const img of plan.images) {
+          try {
+            copyAndStage(
+              worktreeDir,
+              `${reviewDir}/images/${img.filename}`,
+              img.sourcePath
+            );
+          } catch {
+          }
+        }
+      }
+    }
+    if (rawData.transcript) {
+      writeAndStage(worktreeDir, `${entryDir}/transcript.jsonl`, rawData.transcript);
+      entry.transcriptSize = Buffer.byteLength(rawData.transcript, "utf-8");
+    }
+    const timeline = readTimelineFromWorktree(worktreeDir) ?? {
+      version: 1,
+      updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      projectDir,
+      entries: []
+    };
+    const newTimelineEntry = toTimelineEntry(entry);
+    timeline.entries = [
+      newTimelineEntry,
+      ...timeline.entries.filter((e) => e.sha !== entry.commit.sha)
+    ];
+    timeline.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+    writeAndStage(
+      worktreeDir,
+      "timeline.json",
+      JSON.stringify(timeline, null, 2)
+    );
+    const meta = readMetaFromWorktree(worktreeDir);
+    if (meta) {
+      meta.totalEntries = timeline.entries.length;
+      meta.lastCaptureAt = (/* @__PURE__ */ new Date()).toISOString();
+      writeAndStage(worktreeDir, "meta.json", JSON.stringify(meta, null, 2));
+      const readme = generateReadme(meta, timeline);
+      writeAndStage(worktreeDir, "README.md", readme);
+    }
+    commitInWorktree(
+      worktreeDir,
+      `chore(history): capture ${shortSha} \u2014 ${truncate2(entry.commit.subject, 60)}`
+    );
+  });
+}
+function readHistoryEntry(projectDir, sha, branchName) {
+  branchName ??= getHistoryBranch();
+  const shortSha = resolveShortSha(projectDir, sha, branchName);
+  const raw = readFromBranch(
+    projectDir,
+    `entries/${shortSha}/entry.json`,
+    branchName
+  );
+  if (!raw) return null;
+  try {
+    const entry = normalizeEntry(JSON.parse(raw));
+    if (entry.transcriptSize == null || entry.transcriptSize === 0) {
+      const transcript = readFromBranch(
+        projectDir,
+        `entries/${shortSha}/transcript.jsonl`,
+        branchName
+      );
+      if (transcript && transcript.length > 0) {
+        entry.transcriptSize = Buffer.byteLength(transcript, "utf-8");
+      }
+    }
+    return entry;
+  } catch {
+    return null;
+  }
+}
+function readEntryRawData(projectDir, sha, branchName) {
+  branchName ??= getHistoryBranch();
+  const shortSha = resolveShortSha(projectDir, sha, branchName);
+  const base = `entries/${shortSha}`;
+  return {
+    state: readFromBranch(projectDir, `${base}/state.json`, branchName),
+    events: readFromBranch(projectDir, `${base}/events.jsonl`, branchName),
+    guards: readFromBranch(projectDir, `${base}/guards.yml`, branchName)
+  };
+}
+function readEntryTranscript(projectDir, sha, branchName) {
+  branchName ??= getHistoryBranch();
+  const shortSha = resolveShortSha(projectDir, sha, branchName);
+  return readFromBranch(
+    projectDir,
+    `entries/${shortSha}/transcript.jsonl`,
+    branchName
+  );
+}
+function readTimeline(projectDir, branchName) {
+  branchName ??= getHistoryBranch();
+  const raw = readFromBranch(projectDir, "timeline.json", branchName);
+  if (!raw) return null;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+function readBranchMeta(projectDir, branchName) {
+  branchName ??= getHistoryBranch();
+  const raw = readFromBranch(projectDir, "meta.json", branchName);
+  if (!raw) return null;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+function toTimelineEntry(entry) {
+  return {
+    sha: entry.commit.sha,
+    shortSha: entry.commit.shortSha,
+    subject: entry.commit.subject,
+    date: entry.commit.authorDate,
+    branch: entry.commit.branch,
+    hasSession: entry.session !== null,
+    hasEnrichment: entry.enrichment !== null,
+    hasReviewPlans: entry.reviewPlans !== null && entry.reviewPlans.length > 0,
+    filesChanged: entry.diff.filesChanged,
+    contentHash: entry.contentHash,
+    hasTranscript: (entry.transcriptSize ?? 0) > 0
+  };
+}
+function entryExists(projectDir, sha, branchName) {
+  branchName ??= getHistoryBranch();
+  const timeline = readTimeline(projectDir, branchName);
+  if (!timeline) return false;
+  return timeline.entries.some(
+    (e) => e.sha === sha || e.shortSha === sha || e.sha.startsWith(sha)
+  );
+}
+async function updateEntryEnrichment(projectDir, sha, enrichment, branchName) {
+  branchName ??= getHistoryBranch();
+  const shortSha = resolveShortSha(projectDir, sha, branchName);
+  await withWorktree(projectDir, branchName, (worktreeDir) => {
+    const entryDir = `entries/${shortSha}`;
+    writeAndStage(
+      worktreeDir,
+      `${entryDir}/enrichment.json`,
+      JSON.stringify(enrichment, null, 2)
+    );
+    const entryRaw = readFromBranch(
+      projectDir,
+      `${entryDir}/entry.json`,
+      branchName
+    );
+    if (entryRaw) {
+      try {
+        const entry = JSON.parse(entryRaw);
+        entry.enrichment = enrichment;
+        writeAndStage(
+          worktreeDir,
+          `${entryDir}/entry.json`,
+          JSON.stringify(entry, null, 2)
+        );
+      } catch {
+      }
+    }
+    const timeline = readTimelineFromWorktree(worktreeDir);
+    if (timeline) {
+      for (const e of timeline.entries) {
+        if (e.sha === sha || e.shortSha === shortSha) {
+          e.hasEnrichment = true;
+        }
+      }
+      timeline.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+      writeAndStage(
+        worktreeDir,
+        "timeline.json",
+        JSON.stringify(timeline, null, 2)
+      );
+      const meta = readMetaFromWorktree(worktreeDir);
+      if (meta) {
+        const readme = generateReadme(meta, timeline);
+        writeAndStage(worktreeDir, "README.md", readme);
+      }
+    }
+    commitInWorktree(
+      worktreeDir,
+      `chore(history): enrich ${shortSha}`
+    );
+  });
+}
+async function updateEntryTags(projectDir, sha, tags, branchName) {
+  branchName ??= getHistoryBranch();
+  const shortSha = resolveShortSha(projectDir, sha, branchName);
+  await withWorktree(projectDir, branchName, (worktreeDir) => {
+    const entryDir = `entries/${shortSha}`;
+    const entryPath = path3.join(worktreeDir, entryDir, "entry.json");
+    if (fs3.existsSync(entryPath)) {
+      try {
+        const entry = JSON.parse(fs3.readFileSync(entryPath, "utf-8"));
+        const tagRecord = {};
+        for (const t of tags) tagRecord[t] = "";
+        entry.tags = tagRecord;
+        writeAndStage(worktreeDir, `${entryDir}/entry.json`, JSON.stringify(entry, null, 2));
+      } catch {
+      }
+    }
+    const timeline = readTimelineFromWorktree(worktreeDir);
+    if (timeline) {
+      for (const e of timeline.entries) {
+        if (e.sha === sha || e.shortSha === shortSha) {
+          e.tags = tags;
+        }
+      }
+      timeline.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+      writeAndStage(worktreeDir, "timeline.json", JSON.stringify(timeline, null, 2));
+    }
+    commitInWorktree(worktreeDir, `chore(history): tag ${shortSha}`);
+  });
+}
+async function updateEntryTranscript(projectDir, sha, transcript, branchName) {
+  branchName ??= getHistoryBranch();
+  const shortSha = resolveShortSha(projectDir, sha, branchName);
+  const transcriptSize = Buffer.byteLength(transcript, "utf-8");
+  await withWorktree(projectDir, branchName, (worktreeDir) => {
+    const entryDir = `entries/${shortSha}`;
+    writeAndStage(worktreeDir, `${entryDir}/transcript.jsonl`, transcript);
+    const entryPath = path3.join(worktreeDir, entryDir, "entry.json");
+    if (fs3.existsSync(entryPath)) {
+      try {
+        const entry = JSON.parse(
+          fs3.readFileSync(entryPath, "utf-8")
+        );
+        entry.transcriptSize = transcriptSize;
+        writeAndStage(
+          worktreeDir,
+          `${entryDir}/entry.json`,
+          JSON.stringify(entry, null, 2)
+        );
+      } catch {
+      }
+    }
+    const timeline = readTimelineFromWorktree(worktreeDir);
+    if (timeline) {
+      for (const e of timeline.entries) {
+        if (e.sha === sha || e.shortSha === shortSha) {
+          e.hasTranscript = true;
+        }
+      }
+      timeline.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+      writeAndStage(
+        worktreeDir,
+        "timeline.json",
+        JSON.stringify(timeline, null, 2)
+      );
+    }
+    commitInWorktree(
+      worktreeDir,
+      `chore(history): attach transcript to ${shortSha}`
+    );
+  });
+}
+function readTimelineFromWorktree(worktreeDir) {
+  try {
+    const raw = fs3.readFileSync(
+      path3.join(worktreeDir, "timeline.json"),
+      "utf-8"
+    );
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+function readMetaFromWorktree(worktreeDir) {
+  try {
+    const raw = fs3.readFileSync(
+      path3.join(worktreeDir, "meta.json"),
+      "utf-8"
+    );
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+function truncate2(str, maxLen) {
+  if (str.length <= maxLen) return str;
+  return str.slice(0, maxLen - 3) + "...";
+}
+function readTranscript(transcriptPath, maxSize = 5242880) {
+  try {
+    const stat = fs4.statSync(transcriptPath);
+    const size = stat.size;
+    if (size <= maxSize) {
+      const content = fs4.readFileSync(transcriptPath, "utf-8");
+      return { content, size, truncated: false };
+    }
+    const fd = fs4.openSync(transcriptPath, "r");
+    try {
+      const buffer = Buffer.alloc(maxSize);
+      const offset = size - maxSize;
+      fs4.readSync(fd, buffer, 0, maxSize, offset);
+      let content = buffer.toString("utf-8");
+      const firstNewline = content.indexOf("\n");
+      if (firstNewline !== -1 && firstNewline < content.length - 1) {
+        content = content.slice(firstNewline + 1);
+      }
+      return { content, size, truncated: true };
+    } finally {
+      fs4.closeSync(fd);
+    }
+  } catch {
+    return null;
+  }
+}
+function getTranscriptSize(transcriptPath) {
+  try {
+    return fs4.statSync(transcriptPath).size;
+  } catch {
+    return null;
+  }
+}
+var HOOK_MARKER_START = "# ulpi-history";
+var HOOK_MARKER_END = "# ulpi-history-end";
+function installGitHooks(projectDir, binaryPath) {
+  const gitDir = resolveGitDir(projectDir);
+  if (!gitDir) return { installed: [], skipped: [] };
+  const hooksDir = path4.join(gitDir, "hooks");
+  fs5.mkdirSync(hooksDir, { recursive: true });
+  const installed = [];
+  const skipped = [];
+  const hooks = {
+    "prepare-commit-msg": generatePrepareCommitMsg(),
+    "post-commit": generatePostCommit(binaryPath),
+    "pre-push": generatePrePush()
+  };
+  for (const [name, content] of Object.entries(hooks)) {
+    const hookPath = path4.join(hooksDir, name);
+    if (fs5.existsSync(hookPath)) {
+      const existing = fs5.readFileSync(hookPath, "utf-8");
+      if (existing.includes(HOOK_MARKER_START)) {
+        skipped.push(name);
+        continue;
+      }
+      fs5.appendFileSync(hookPath, `
+
+${content}
+`);
+    } else {
+      fs5.writeFileSync(hookPath, `#!/bin/sh
+
+${content}
+`, { mode: 493 });
+    }
+    try {
+      fs5.chmodSync(hookPath, 493);
+    } catch {
+    }
+    installed.push(name);
+  }
+  return { installed, skipped };
+}
+function uninstallGitHooks(projectDir) {
+  const gitDir = resolveGitDir(projectDir);
+  if (!gitDir) return [];
+  const hooksDir = path4.join(gitDir, "hooks");
+  const removed = [];
+  for (const name of ["prepare-commit-msg", "post-commit", "pre-push"]) {
+    const hookPath = path4.join(hooksDir, name);
+    if (!fs5.existsSync(hookPath)) continue;
+    const content = fs5.readFileSync(hookPath, "utf-8");
+    if (!content.includes(HOOK_MARKER_START)) continue;
+    const startIdx = content.indexOf(HOOK_MARKER_START);
+    const endIdx = content.indexOf(HOOK_MARKER_END);
+    if (startIdx === -1) continue;
+    const endOfMarker = endIdx !== -1 ? endIdx + HOOK_MARKER_END.length : content.length;
+    let cleaned = content.slice(0, startIdx) + content.slice(endOfMarker);
+    cleaned = cleaned.replace(/\n{3,}/g, "\n\n").trim();
+    if (cleaned === "#!/bin/sh" || cleaned.trim() === "") {
+      fs5.unlinkSync(hookPath);
+    } else {
+      fs5.writeFileSync(hookPath, cleaned + "\n");
+    }
+    removed.push(name);
+  }
+  return removed;
+}
+function resolveGitDir(projectDir) {
+  const gitPath = path4.join(projectDir, ".git");
+  try {
+    const stat = fs5.statSync(gitPath);
+    if (stat.isDirectory()) {
+      return gitPath;
+    }
+    const content = fs5.readFileSync(gitPath, "utf-8").trim();
+    const match = content.match(/^gitdir:\s*(.+)$/);
+    if (match) {
+      const resolvedGitDir = path4.resolve(projectDir, match[1]);
+      const commonDir = path4.join(resolvedGitDir, "..", "..");
+      return fs5.existsSync(path4.join(commonDir, "hooks")) ? commonDir : resolvedGitDir;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+function generatePrepareCommitMsg() {
+  return `${HOOK_MARKER_START}
+# Add ULPI-History trailer to commit messages
+COMMIT_MSG_FILE="$1"
+COMMIT_SOURCE="$2"
+if [ "$COMMIT_SOURCE" = "" ] || [ "$COMMIT_SOURCE" = "message" ]; then
+  SHORT_SHA=$(git rev-parse --short HEAD 2>/dev/null || echo "pending")
+  if ! grep -q "ULPI-History:" "$COMMIT_MSG_FILE" 2>/dev/null; then
+    printf "\\nULPI-History: %s\\n" "$SHORT_SHA" >> "$COMMIT_MSG_FILE"
+  fi
+fi
+${HOOK_MARKER_END}`;
+}
+function generatePostCommit(binaryPath) {
+  const cmd = binaryPath.includes(" ") ? binaryPath : `"${binaryPath}"`;
+  return `${HOOK_MARKER_START}
+# Trigger on-commit history capture (fail-open)
+${cmd} history capture HEAD 2>/dev/null || true
+${HOOK_MARKER_END}`;
+}
+function generatePrePush() {
+  return `${HOOK_MARKER_START}
+# Auto-push ulpi/history branch alongside user push
+REMOTE="$1"
+if git rev-parse --verify ulpi/history >/dev/null 2>&1; then
+  git push "$REMOTE" ulpi/history 2>/dev/null || true
+fi
+${HOOK_MARKER_END}`;
+}
+
+export {
+  historyBranchExists,
+  initHistoryBranch,
+  getCommitMetadata,
+  getCommitDiffStats,
+  getCommitRawDiff,
+  getCurrentHead,
+  listCommitsBetween,
+  listRecentCommits,
+  readFromBranch,
+  listBranchDir,
+  getWorktreeId,
+  withWorktree,
+  writeAndStage,
+  copyAndStage,
+  commitInWorktree,
+  buildSessionSummary,
+  countEventsByType,
+  findSessionForCommit,
+  loadActiveGuards,
+  findReviewPlansForCommit,
+  buildHookDerivedData,
+  buildPrePromptSnapshot,
+  generateReadme,
+  normalizeEntry,
+  DEFAULT_HISTORY_CONFIG,
+  writeHistoryEntry,
+  readHistoryEntry,
+  readEntryRawData,
+  readEntryTranscript,
+  readTimeline,
+  readBranchMeta,
+  toTimelineEntry,
+  entryExists,
+  updateEntryEnrichment,
+  updateEntryTags,
+  updateEntryTranscript,
+  readTranscript,
+  getTranscriptSize,
+  installGitHooks,
+  uninstallGitHooks
+};