@amoghvj/txr 0.1.1 → 0.2.0

package/dist/index.js

@@ -1,11 +1,19 @@
 #!/usr/bin/env node
 import {
-  GitStore,
+  GitStore
+} from "./chunk-MCJNEIJH.js";
+import {
+  HistoryStore
+} from "./chunk-KXCWVEEG.js";
+import {
+  ExternalChangeDetector
+} from "./chunk-6SSBMHMQ.js";
+import {
   __require
-} from "./chunk-XKFFIQXW.js";
+} from "./chunk-3RG5ZIWI.js";
 
 // src/index.ts
-import { Command } from "commander";
+import { Command as Command3 } from "commander";
 
 // src/cli/commands/init.ts
 import * as fs from "fs/promises";
@@ -77,8 +85,8 @@ async function findTxrRoot(startDir) {
   while (true) {
     const candidate = path.join(dir, TXR_DIR);
     try {
-      const stat3 = await fs.stat(candidate);
-      if (stat3.isDirectory()) return dir;
+      const stat4 = await fs.stat(candidate);
+      if (stat4.isDirectory()) return dir;
     } catch {
     }
     const parent = path.dirname(dir);
@@ -126,34 +134,89 @@ var TransactionStore = class _TransactionStore {
     this.filePath = filePath;
     this.data = data;
   }
-  /** Load from disk, or create empty store. */
+  /** Load from disk, migrating v1 → v2 if needed, or create empty store. */
   static async load(metadataDir) {
     const filePath = path2.join(metadataDir, "transactions.json");
     try {
       const raw = await fs2.readFile(filePath, "utf-8");
-      const data = JSON.parse(raw);
-      return new _TransactionStore(filePath, data);
+      const raw_data = JSON.parse(raw);
+      const data = _TransactionStore.migrate(raw_data);
+      const store = new _TransactionStore(filePath, data);
+      store.gc();
+      return store;
     } catch {
       const data = {
-        version: 1,
+        version: 2,
         head: null,
         undoStack: [],
         counter: 0,
+        extCounter: 0,
         transactions: {}
       };
       return new _TransactionStore(filePath, data);
     }
   }
+  /**
+   * Migrate from v1 schema (no `type`, no `extCounter`) to v2.
+   * All v1 transactions are assumed to be type 'U' (undoable).
+   * Migration is in-memory; file is written on next save().
+   */
+  static migrate(raw) {
+    if (raw.version === 2) return raw;
+    const transactions = raw.transactions ?? {};
+    const normalized = Array.isArray(transactions) ? Object.fromEntries(transactions.map((t) => [t.id, t])) : transactions;
+    for (const tx of Object.values(normalized)) {
+      if (!tx.type) tx.type = "U";
+      if (tx.source === void 0) tx.source = "txr-run";
+      if (tx.command === void 0) tx.command = tx.command ?? null;
+      if (tx.exitCode === void 0) tx.exitCode = tx.exitCode ?? null;
+      if (tx.attributionTier === void 0) tx.attributionTier = tx.attributionTier ?? null;
+    }
+    return {
+      version: 2,
+      head: raw.head ?? null,
+      undoStack: raw.undoStack ?? [],
+      counter: raw.counter ?? 0,
+      extCounter: 0,
+      transactions: normalized
+    };
+  }
+  /** Run garbage collection to remove any orphaned transactions not reachable from HEAD or the undo stack. */
+  gc() {
+    const reachable = /* @__PURE__ */ new Set();
+    let current = this.data.head;
+    while (current) {
+      reachable.add(current);
+      current = this.data.transactions[current]?.parent ?? null;
+    }
+    for (const id of this.data.undoStack) {
+      let currentUndo = id;
+      while (currentUndo) {
+        reachable.add(currentUndo);
+        currentUndo = this.data.transactions[currentUndo]?.parent ?? null;
+      }
+    }
+    for (const id of Object.keys(this.data.transactions)) {
+      if (!reachable.has(id)) {
+        delete this.data.transactions[id];
+      }
+    }
+  }
   async save() {
     const tmp = this.filePath + ".tmp";
     await fs2.writeFile(tmp, JSON.stringify(this.data, null, 2), "utf-8");
     await fs2.rename(tmp, this.filePath);
   }
-  /** Generate the next transaction ID (monotonically increasing). */
+  /** Generate the next user transaction ID (monotonically increasing). */
   nextId() {
     this.data.counter += 1;
     return `tx_${String(this.data.counter).padStart(3, "0")}`;
   }
+  /** Generate the next external change (E) transaction ID. */
+  nextExtId() {
+    this.data.extCounter += 1;
+    return `ext_${String(this.data.extCounter).padStart(3, "0")}`;
+  }
   /** Get the current HEAD transaction ID, or null if no transactions exist. */
   get head() {
     return this.data.head;
@@ -170,15 +233,31 @@ var TransactionStore = class _TransactionStore {
   get undoStack() {
     return this.data.undoStack;
   }
-  /** Add a new transaction and set it as HEAD. Clears the undo stack. */
+  /**
+   * Add a new user-initiated transaction (U or P) and set it as HEAD.
+   * Clears the undo stack — new user action invalidates redo history.
+   */
   addTransaction(tx) {
+    const discarded = this.clearUndoStack();
+    this.data.transactions[tx.id] = tx;
+    this.data.head = tx.id;
+    return discarded;
+  }
+  /**
+   * Add an automatically detected external change transaction (E) and set it as HEAD.
+   * Does NOT clear the undo stack.
+   *
+   * Rationale: External changes are not user-initiated. They should not destroy
+   * the user's redo chain. However, if the redo operation itself runs detection
+   * and finds an E, it WILL clear the undo stack at that point (in UndoEngine).
+   */
+  addExternalTransaction(tx) {
     this.data.transactions[tx.id] = tx;
     this.data.head = tx.id;
-    this.data.undoStack = [];
   }
   /**
    * Undo: move HEAD to the parent of the current HEAD.
-   * Pushes the undone transaction ID onto the undo stack.
+   * Pushes the undone transaction ID onto the undo stack for potential redo.
    */
   undoHead() {
     const head = this.data.head;
@@ -203,6 +282,15 @@ var TransactionStore = class _TransactionStore {
     this.data.head = redoId;
     return tx;
   }
+  /** Clear the undo stack, permanently delete detached transactions, and return their IDs. */
+  clearUndoStack() {
+    const discarded = [...this.data.undoStack];
+    for (const id of discarded) {
+      delete this.data.transactions[id];
+    }
+    this.data.undoStack = [];
+    return discarded;
+  }
   /** Get all transactions in chain order (oldest first), up to and including HEAD. */
   getChain() {
     const chain = [];
@@ -225,53 +313,9 @@ var TransactionStore = class _TransactionStore {
   }
 };
 
-// src/core/history-store.ts
+// src/core/file-map.ts
 import * as fs3 from "fs/promises";
 import * as path3 from "path";
-var HistoryStore = class _HistoryStore {
-  data;
-  filePath;
-  constructor(filePath, data) {
-    this.filePath = filePath;
-    this.data = data;
-  }
-  static async load(metadataDir) {
-    const filePath = path3.join(metadataDir, "history.json");
-    try {
-      const raw = await fs3.readFile(filePath, "utf-8");
-      const data = JSON.parse(raw);
-      return new _HistoryStore(filePath, data);
-    } catch {
-      const data = { version: 1, entries: [] };
-      return new _HistoryStore(filePath, data);
-    }
-  }
-  async save() {
-    const tmp = this.filePath + ".tmp";
-    await fs3.writeFile(tmp, JSON.stringify(this.data, null, 2), "utf-8");
-    await fs3.rename(tmp, this.filePath);
-  }
-  /** Append a new history entry. */
-  append(entry) {
-    this.data.entries.push(entry);
-  }
-  /** Get all entries (oldest first). */
-  getAll() {
-    return this.data.entries;
-  }
-  /** Get the N most recent entries. */
-  getRecent(n) {
-    return this.data.entries.slice(-n);
-  }
-  /** Get total entry count. */
-  get count() {
-    return this.data.entries.length;
-  }
-};
-
-// src/core/file-map.ts
-import * as fs4 from "fs/promises";
-import * as path4 from "path";
 import { nanoid } from "nanoid";
 var FileMap = class _FileMap {
   data;
@@ -286,9 +330,9 @@ var FileMap = class _FileMap {
   }
   /** Load mapping from disk, or create empty mapping if file doesn't exist. */
   static async load(metadataDir) {
-    const filePath = path4.join(metadataDir, "mapping.json");
+    const filePath = path3.join(metadataDir, "mapping.json");
     try {
-      const raw = await fs4.readFile(filePath, "utf-8");
+      const raw = await fs3.readFile(filePath, "utf-8");
       const data = JSON.parse(raw);
       return new _FileMap(filePath, data);
     } catch {
@@ -299,12 +343,12 @@ var FileMap = class _FileMap {
   /** Persist current state to disk atomically. */
   async save() {
     const tmp = this.filePath + ".tmp";
-    await fs4.writeFile(tmp, JSON.stringify(this.data, null, 2), "utf-8");
-    await fs4.rename(tmp, this.filePath);
+    await fs3.writeFile(tmp, JSON.stringify(this.data, null, 2), "utf-8");
+    await fs3.rename(tmp, this.filePath);
   }
   /** Normalize a path for consistent lookup (forward slashes, resolved). */
   static normalizePath(p) {
-    return path4.resolve(p).replace(/\\/g, "/");
+    return path3.resolve(p).replace(/\\/g, "/");
   }
   /** Get file ID for a path, or undefined if not mapped. Only returns active (non-deleted) entries. */
   getIdByPath(absolutePath) {
@@ -369,6 +413,35 @@ var FileMap = class _FileMap {
   get activeCount() {
     return this.pathIndex.size;
   }
+  /**
+   * Register a brand-new file discovered externally, with a pre-assigned fileId.
+   * Used by ExternalChangeDetector for files that have never been seen by TXR.
+   */
+  registerNewFile(absolutePath, fileId, transactionId) {
+    const norm = _FileMap.normalizePath(absolutePath);
+    this.data.files[fileId] = {
+      path: norm,
+      createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+      createdByTx: transactionId
+    };
+    this.pathIndex.set(norm, fileId);
+  }
+  /**
+   * Untrack files that were created by the given transaction IDs.
+   * Called when the undo stack is cleared to discard abandoned file histories.
+   */
+  untrackByTransactions(transactionIds) {
+    const txSet = new Set(transactionIds);
+    for (const [id, entry] of Object.entries(this.data.files)) {
+      if (txSet.has(entry.createdByTx)) {
+        delete this.data.files[id];
+        const norm = _FileMap.normalizePath(entry.path);
+        if (this.pathIndex.get(norm) === id) {
+          this.pathIndex.delete(norm);
+        }
+      }
+    }
+  }
   /** Rebuild the in-memory path→ID index from persisted data. */
   rebuildPathIndex() {
     this.pathIndex.clear();
@@ -382,12 +455,12 @@ var FileMap = class _FileMap {
 };
 
 // src/core/transaction-engine.ts
-import * as fs6 from "fs/promises";
-import * as path7 from "path";
+import * as fs5 from "fs/promises";
+import * as path6 from "path";
 
 // src/attribution/tier3-hybrid.ts
-import * as fs5 from "fs/promises";
-import * as path5 from "path";
+import * as fs4 from "fs/promises";
+import * as path4 from "path";
 import * as crypto from "crypto";
 import { spawn } from "child_process";
 import { minimatch } from "minimatch";
@@ -402,7 +475,7 @@ var Tier3HybridProvider = class {
       "Using scoped filesystem diff (Tier 3). Changes by concurrent processes within watch paths may be mis-attributed."
     ];
     const resolvedWatchPaths = options.watchPaths.map(
-      (p) => path5.isAbsolute(p) ? p : path5.resolve(cwd, p)
+      (p) => path4.isAbsolute(p) ? p : path4.resolve(cwd, p)
     );
     const preSnapshot = await this.snapshotPaths(resolvedWatchPaths, options.ignorePaths);
     const exitCode = await this.executeCommand(command, cwd, options);
@@ -428,36 +501,36 @@ var Tier3HybridProvider = class {
     return snapshots;
   }
   async walkAndHash(currentPath, rootPath, ignorePaths, snapshots) {
-    let stat3;
+    let stat4;
     try {
-      stat3 = await fs5.stat(currentPath);
+      stat4 = await fs4.stat(currentPath);
     } catch {
       return;
     }
     const normalized = currentPath.replace(/\\/g, "/");
-    const relativePath = path5.relative(rootPath, currentPath).replace(/\\/g, "/");
+    const relativePath = path4.relative(rootPath, currentPath).replace(/\\/g, "/");
     for (const pattern of ignorePaths) {
-      if (minimatch(relativePath, pattern, { dot: true }) || minimatch(path5.basename(currentPath), pattern, { dot: true })) {
+      if (minimatch(relativePath, pattern, { dot: true }) || minimatch(path4.basename(currentPath), pattern, { dot: true })) {
         return;
       }
     }
-    if (stat3.isFile()) {
+    if (stat4.isFile()) {
       const hash = await this.hashFile(currentPath);
       snapshots.set(normalized, {
         path: normalized,
         hash,
-        size: stat3.size
+        size: stat4.size
       });
-    } else if (stat3.isDirectory()) {
+    } else if (stat4.isDirectory()) {
       let entries;
       try {
-        entries = await fs5.readdir(currentPath);
+        entries = await fs4.readdir(currentPath);
       } catch {
         return;
       }
       for (const entry of entries) {
         await this.walkAndHash(
-          path5.join(currentPath, entry),
+          path4.join(currentPath, entry),
           rootPath,
           ignorePaths,
           snapshots
@@ -466,7 +539,7 @@ var Tier3HybridProvider = class {
     }
   }
   async hashFile(filePath) {
-    const content = await fs5.readFile(filePath);
+    const content = await fs4.readFile(filePath);
     return crypto.createHash("sha256").update(content).digest("hex");
   }
   /**
@@ -500,7 +573,7 @@ var Tier3HybridProvider = class {
    * Uses shell execution to support piping, env expansion, etc.
    */
   executeCommand(command, cwd, options) {
-    return new Promise((resolve6, reject) => {
+    return new Promise((resolve7, reject) => {
       const isWindows = process.platform === "win32";
       const shell = isWindows ? "cmd.exe" : "/bin/sh";
       const shellArgs = isWindows ? ["/c", command] : ["-c", command];
@@ -515,7 +588,7 @@ var Tier3HybridProvider = class {
       });
       child.on("error", reject);
       child.on("close", (code) => {
-        resolve6(code ?? 1);
+        resolve7(code ?? 1);
       });
     });
   }
@@ -549,19 +622,22 @@ function getOrderedProviders() {
 }
 
 // src/classifier/classifier.ts
-import * as path6 from "path";
+import * as path5 from "path";
 var DEFAULT_RULES = [
   // ── Containers & Orchestration ──
-  { pattern: /^docker\b/, type: "non-transactional", category: "container", reason: "Container orchestration \u2014 may modify container/image state" },
-  { pattern: /^docker-compose\b/, type: "non-transactional", category: "container", reason: "Container orchestration" },
-  { pattern: /^docker compose\b/, type: "non-transactional", category: "container", reason: "Container orchestration" },
-  { pattern: /^podman\b/, type: "non-transactional", category: "container", reason: "Container orchestration" },
-  { pattern: /^kubectl\b/, type: "non-transactional", category: "container", reason: "Kubernetes cluster management" },
-  { pattern: /^helm\b/, type: "non-transactional", category: "container", reason: "Helm chart management" },
+  // These commands write to container layers / volumes (filesystem trackable)
+  // but also modify container/network state (not filesystem — partial undo)
+  { pattern: /^docker\b/, type: "partially-transactional", category: "container", reason: "Container orchestration \u2014 modifies container/image state outside TXR rollback boundary" },
+  { pattern: /^docker-compose\b/, type: "partially-transactional", category: "container", reason: "Container orchestration \u2014 modifies container/image state outside TXR rollback boundary" },
+  { pattern: /^docker compose\b/, type: "partially-transactional", category: "container", reason: "Container orchestration \u2014 modifies container/image state outside TXR rollback boundary" },
+  { pattern: /^podman\b/, type: "partially-transactional", category: "container", reason: "Container orchestration \u2014 modifies container/image state outside TXR rollback boundary" },
+  { pattern: /^kubectl\b/, type: "non-transactional", category: "container", reason: "Kubernetes cluster management \u2014 no local filesystem changes" },
+  { pattern: /^helm\b/, type: "non-transactional", category: "container", reason: "Helm chart management \u2014 no local filesystem changes" },
   // ── Databases ──
-  { pattern: /^(mysql|psql|mongosh?|redis-cli|sqlite3)\b/, type: "non-transactional", category: "database", reason: "Database client \u2014 may modify database state" },
-  { pattern: /^prisma\s+(migrate|db\s+push|db\s+seed)/, type: "non-transactional", category: "database", reason: "Database migration/seeding" },
-  { pattern: /^(knex|sequelize|typeorm)\s+migrate/, type: "non-transactional", category: "database", reason: "Database migration" },
+  // Database clients may write local files (e.g., .sql dumps, migration files) but also modify DB state
+  { pattern: /^(mysql|psql|mongosh?|redis-cli|sqlite3)\b/, type: "partially-transactional", category: "database", reason: "Database client \u2014 modifies database state outside TXR rollback boundary" },
+  { pattern: /^prisma\s+(migrate|db\s+push|db\s+seed)/, type: "partially-transactional", category: "database", reason: "Database migration/seeding \u2014 modifies database state outside TXR rollback boundary" },
+  { pattern: /^(knex|sequelize|typeorm)\s+migrate/, type: "partially-transactional", category: "database", reason: "Database migration \u2014 modifies database state outside TXR rollback boundary" },
   // ── Services & Daemons ──
   { pattern: /^(systemctl|service)\b/, type: "non-transactional", category: "service", reason: "System service management" },
   { pattern: /^sc\s+(start|stop|config|create|delete)\b/, type: "non-transactional", category: "service", reason: "Windows service management" },
@@ -635,18 +711,18 @@ function classifyCommand(command, scope = "workspace", projectRoot, extraRules =
   return { type: "transactional" };
 }
 function detectPathEscape(command, projectRoot) {
-  const normalizedRoot = path6.resolve(projectRoot).replace(/\\/g, "/").toLowerCase();
+  const normalizedRoot = path5.resolve(projectRoot).replace(/\\/g, "/").toLowerCase();
   const tokens = command.split(/\s+/);
   for (const token of tokens) {
     const cleaned = token.replace(/["']/g, "");
     if (cleaned.startsWith("/") && !cleaned.startsWith("/dev/null")) {
-      const normalizedToken = path6.resolve(cleaned).replace(/\\/g, "/").toLowerCase();
+      const normalizedToken = path5.resolve(cleaned).replace(/\\/g, "/").toLowerCase();
       if (!normalizedToken.startsWith(normalizedRoot)) {
         return `Path "${cleaned}" is outside the workspace root (${projectRoot})`;
       }
     }
     if (/^[A-Za-z]:[\\/]/.test(cleaned)) {
-      const normalizedToken = path6.resolve(cleaned).replace(/\\/g, "/").toLowerCase();
+      const normalizedToken = path5.resolve(cleaned).replace(/\\/g, "/").toLowerCase();
       if (!normalizedToken.startsWith(normalizedRoot)) {
         return `Path "${cleaned}" is outside the workspace root (${projectRoot})`;
       }
@@ -679,7 +755,19 @@ var TransactionEngine = class {
    */
   async execute(command, cwd, options) {
     const startTime = Date.now();
+    const detector = new ExternalChangeDetector(
+      this.txStore,
+      this.fileMap,
+      this.gitStore,
+      this.config,
+      this.projectRoot
+    );
+    await detector.detectAndRecord();
     const classification = options?.forceTransactional ? { type: "transactional" } : options?.forceNonTransactional ? { type: "non-transactional", reason: "User override" } : classifyCommand(command, this.config.scope, this.projectRoot);
+    let txType = "U";
+    if (classification.type === "partially-transactional") {
+      txType = "P";
+    }
     if (classification.type === "non-transactional" || classification.type === "scope-external") {
       const exitCode = await this.executeDirectly(command, cwd);
       const durationMs2 = Date.now() - startTime;
@@ -691,14 +779,15 @@ var TransactionEngine = class {
         exitCode,
         classification: classification.type,
         attributionTier: null,
-        durationMs: durationMs2
+        durationMs: durationMs2,
+        actionType: null
       });
       await this.historyStore.save();
       return null;
     }
     const provider = await selectProvider(this.config.preferredTier);
     const resolvedWatchPaths = this.config.watchPaths.map(
-      (p) => path7.isAbsolute(p) ? p : path7.resolve(cwd, p)
+      (p) => path6.isAbsolute(p) ? p : path6.resolve(cwd, p)
     );
     const result = await provider.executeAndTrack(command, cwd, {
       watchPaths: resolvedWatchPaths,
@@ -710,7 +799,7 @@ var TransactionEngine = class {
     const scopeWarnings = [];
     let trackedChanges;
     if (this.config.scope === "workspace") {
-      const normalizedRoot = path7.resolve(this.projectRoot).replace(/\\/g, "/").toLowerCase();
+      const normalizedRoot = path6.resolve(this.projectRoot).replace(/\\/g, "/").toLowerCase();
       trackedChanges = [];
       for (const change of result.changes) {
         const normalizedChange = change.absolutePath.replace(/\\/g, "/").toLowerCase();
@@ -740,7 +829,8 @@ var TransactionEngine = class {
         exitCode: result.processExitCode,
         classification: "transactional",
         attributionTier: result.tier,
-        durationMs: durationMs2
+        durationMs: durationMs2,
+        actionType: null
       });
       await this.historyStore.save();
       for (const w of scopeWarnings) {
@@ -749,6 +839,10 @@ var TransactionEngine = class {
       }
       return null;
     }
+    const discarded = this.txStore.clearUndoStack();
+    if (discarded.length > 0) {
+      this.fileMap.untrackByTransactions(discarded);
+    }
     const txId = this.txStore.nextId();
     const touchedFiles = [];
     const changeManifest = {};
@@ -759,7 +853,7 @@ var TransactionEngine = class {
       if (change.type === "deleted" /* Deleted */) {
         await this.gitStore.removeFile(fileId);
       } else {
-        const content = await fs6.readFile(change.absolutePath);
+        const content = await fs5.readFile(change.absolutePath);
         await this.gitStore.writeFile(fileId, content);
       }
     }
@@ -767,19 +861,27 @@ var TransactionEngine = class {
     const commitHash = await this.gitStore.commit(commitMessage);
     const tx = {
       id: txId,
+      type: txType,
       parent: this.txStore.head,
       commit: commitHash,
       timestamp: (/* @__PURE__ */ new Date()).toISOString(),
       command,
+      source: "txr-run",
       touchedFiles,
       changeManifest,
       workingDirectory: cwd,
       exitCode: result.processExitCode,
       attributionTier: result.tier,
       scope: this.config.scope,
-      scopeWarnings
+      scopeWarnings,
+      ...txType === "P" && {
+        partialUndoReason: classification.reason ?? "Command has known side effects outside the filesystem."
+      }
     };
-    this.txStore.addTransaction(tx);
+    const discarded2 = this.txStore.addTransaction(tx);
+    if (discarded2.length > 0) {
+      this.fileMap.untrackByTransactions(discarded2);
+    }
     await this.txStore.save();
     await this.fileMap.save();
     const durationMs = Date.now() - startTime;
@@ -789,18 +891,26 @@ var TransactionEngine = class {
       transactionId: txId,
       workingDirectory: cwd,
       exitCode: result.processExitCode,
-      classification: "transactional",
+      classification: txType === "P" ? "partially-transactional" : "transactional",
       attributionTier: result.tier,
-      durationMs
+      durationMs,
+      actionType: txType
     });
     await this.historyStore.save();
+    if (scopeWarnings.length > 0) {
+      for (const w of scopeWarnings) {
+        process.stderr.write(`\x1B[33m\u26A0\x1B[0m ${w}
+`);
+      }
+    }
     return {
       transactionId: txId,
       commit: commitHash,
       changesCount: trackedChanges.length,
       tier: result.tier,
       durationMs,
-      scopeWarnings
+      scopeWarnings,
+      actionType: txType
     };
   }
   /** Resolve a FileChange to a file ID (creating new IDs as needed). */
@@ -832,16 +942,148 @@ var TransactionEngine = class {
         return "deleted";
       case "renamed" /* Renamed */:
         return "modified";
+      default:
+        return "modified";
     }
   }
   /** Truncate command for commit message. */
   summarizeCommand(command) {
     return command.length > 72 ? command.substring(0, 69) + "..." : command;
   }
+  /**
+   * Commit a passive transaction (driven externally, e.g. by a Python Agent).
+   * 
+   * @param source The tool or origin (e.g., "agent:write_file")
+   * @param changedPaths Absolute paths of files that were modified/created/deleted.
+   */
+  async commitPassive(source, changedPaths) {
+    const startTime = Date.now();
+    const scopeWarnings = [];
+    const inScopePaths = [];
+    if (this.config.scope === "workspace") {
+      const normalizedRoot = path6.resolve(this.projectRoot).replace(/\\/g, "/").toLowerCase();
+      for (const p of changedPaths) {
+        const normalizedPath = path6.resolve(p).replace(/\\/g, "/").toLowerCase();
+        if (normalizedPath.startsWith(normalizedRoot)) {
+          inScopePaths.push(p);
+        } else {
+          scopeWarnings.push(`Out-of-scope change ignored: ${p}`);
+        }
+      }
+    } else {
+      inScopePaths.push(...changedPaths);
+    }
+    if (inScopePaths.length === 0) {
+      if (scopeWarnings.length > 0) {
+        for (const w of scopeWarnings) process.stderr.write(`\x1B[33m\u26A0\x1B[0m ${w}
+`);
+      }
+      return null;
+    }
+    const discarded = this.txStore.clearUndoStack();
+    if (discarded.length > 0) {
+      this.fileMap.untrackByTransactions(discarded);
+    }
+    const txId = this.txStore.nextId();
+    const touchedFiles = [];
+    const changeManifest = {};
+    for (const p of inScopePaths) {
+      const absolutePath = path6.resolve(p);
+      let existsOnDisk = false;
+      let content = null;
+      try {
+        content = await fs5.readFile(absolutePath);
+        existsOnDisk = true;
+      } catch {
+        existsOnDisk = false;
+      }
+      let changeType = "modified";
+      const existingId = this.fileMap.getIdByPath(absolutePath);
+      let fileId;
+      if (!existingId) {
+        if (!existsOnDisk) {
+          continue;
+        }
+        changeType = "created";
+        fileId = this.fileMap.getOrCreateId(absolutePath, txId);
+      } else {
+        fileId = existingId;
+        if (!existsOnDisk) {
+          changeType = "deleted";
+        } else {
+          changeType = "modified";
+        }
+      }
+      touchedFiles.push(fileId);
+      changeManifest[fileId] = changeType;
+      if (changeType === "deleted") {
+        this.fileMap.markDeleted(fileId, txId);
+        await this.gitStore.removeFile(fileId);
+      } else {
+        await this.gitStore.writeFile(fileId, content);
+      }
+    }
+    if (touchedFiles.length === 0) {
+      return null;
+    }
+    const commitMessage = `txr: ${txId} | passive: ${source}`;
+    const commitHash = await this.gitStore.commit(commitMessage);
+    const tx = {
+      id: txId,
+      type: "U",
+      parent: this.txStore.head,
+      commit: commitHash,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      command: source,
+      source,
+      touchedFiles,
+      changeManifest,
+      workingDirectory: this.projectRoot,
+      exitCode: 0,
+      attributionTier: null,
+      scope: this.config.scope,
+      scopeWarnings
+    };
+    const discarded2 = this.txStore.addTransaction(tx);
+    if (discarded2.length > 0) {
+      this.fileMap.untrackByTransactions(discarded2);
+    }
+    await this.txStore.save();
+    await this.fileMap.save();
+    const durationMs = Date.now() - startTime;
+    this.historyStore.append({
+      timestamp: tx.timestamp,
+      command: source,
+      transactionId: txId,
+      workingDirectory: this.projectRoot,
+      exitCode: 0,
+      classification: "transactional",
+      attributionTier: null,
+      durationMs,
+      actionType: "U"
+    });
+    await this.historyStore.save();
+    if (scopeWarnings.length > 0) {
+      for (const w of scopeWarnings) {
+        process.stderr.write(`\x1B[33m\u26A0\x1B[0m ${w}
+`);
+      }
+    }
+    return {
+      transactionId: txId,
+      commit: commitHash,
+      changesCount: touchedFiles.length,
+      tier: 1,
+      // Default base tier for passive
+      durationMs,
+      scopeWarnings,
+      actionType: "U"
+    };
+  }
   /** Execute a command directly without tracking. */
   executeDirectly(command, cwd) {
     const { spawn: spawn2 } = __require("child_process");
-    return new Promise((resolve6, reject) => {
+    return new Promise((resolve7, reject) => {
       const isWindows = process.platform === "win32";
       const shell = isWindows ? "cmd.exe" : "/bin/sh";
       const shellArgs = isWindows ? ["/c", command] : ["-c", command];
@@ -850,7 +1092,7 @@ var TransactionEngine = class {
         stdio: "inherit"
       });
       child.on("error", reject);
-      child.on("close", (code) => resolve6(code ?? 1));
+      child.on("close", (code) => resolve7(code ?? 1));
     });
   }
 };
@@ -866,7 +1108,7 @@ async function runCommand(command, options) {
     if ((classification.type === "non-transactional" || classification.type === "scope-external") && config.confirmUnsafe && !options.yes) {
       const readline = await import("readline");
       const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-      const answer = await new Promise((resolve6) => {
+      const answer = await new Promise((resolve7) => {
         console.log();
         if (classification.type === "scope-external") {
           console.log(`\x1B[33m\u26A0 SCOPE WARNING:\x1B[0m This command may modify files outside your workspace.`);
@@ -878,7 +1120,7 @@ async function runCommand(command, options) {
         console.log();
         console.log("  Rollback guarantees cannot be provided.");
         console.log();
-        rl.question("  Continue without tracking? [y/N] ", resolve6);
+        rl.question("  Continue without tracking? [y/N] ", resolve7);
       });
       rl.close();
       if (answer.toLowerCase() !== "y") {
@@ -913,8 +1155,8 @@ async function runCommand(command, options) {
 }
 
 // src/core/undo-engine.ts
-import * as fs7 from "fs/promises";
-import * as path8 from "path";
+import * as fs6 from "fs/promises";
+import * as path7 from "path";
 import * as crypto2 from "crypto";
 var UndoConflictError = class extends Error {
   conflicts;
@@ -924,28 +1166,64 @@ var UndoConflictError = class extends Error {
     this.conflicts = conflicts;
   }
 };
+var PartialUndoBlockedError = class extends Error {
+  constructor(txId, reason) {
+    super(
+      `Cannot safely undo \x1B[1m${txId}\x1B[0m: This transaction has known side effects outside TXR's rollback boundary.
+Reason: ${reason}
+
+Tracked filesystem effects CAN be reverted.
+Resolve any external side effects manually, then run: \x1B[1mtxr undo --force\x1B[0m`
+    );
+    this.name = "PartialUndoBlockedError";
+  }
+};
+var ExternalUndoBlockedError = class extends Error {
+  constructor(txId) {
+    super(
+      `Cannot undo \x1B[1m${txId}\x1B[0m: This is an automatically recorded external change.
+TXR did not create these changes, so it cannot undo them safely.
+
+If you have already reverted these changes manually, run: \x1B[1mtxr undo --force\x1B[0m`
+    );
+    this.name = "ExternalUndoBlockedError";
+  }
+};
 var UndoEngine = class {
-  constructor(txStore, fileMap, gitStore) {
+  constructor(txStore, fileMap, gitStore, detector) {
     this.txStore = txStore;
     this.fileMap = fileMap;
     this.gitStore = gitStore;
+    this.detector = detector;
   }
   txStore;
   fileMap;
   gitStore;
+  detector;
   /** Undo the current HEAD transaction. */
-  async undo() {
+  async undo(options = {}) {
+    if (!options.force && this.detector) {
+      await this.detector.detectAndRecord();
+    }
     const headTx = this.txStore.getHead();
     if (!headTx) throw new Error("Nothing to undo.");
     const parentTx = headTx.parent ? this.txStore.get(headTx.parent) : void 0;
-    const conflicts = await this.validateForUndo(headTx);
-    if (conflicts.length > 0) {
-      throw new UndoConflictError(
-        `Cannot undo ${headTx.id}: ${conflicts.length} file(s) have been externally modified.
+    if (!options.force) {
+      if (headTx.type === "P") {
+        throw new PartialUndoBlockedError(headTx.id, headTx.partialUndoReason ?? "Unknown side effect.");
+      }
+      if (headTx.type === "E") {
+        throw new ExternalUndoBlockedError(headTx.id);
+      }
+      const conflicts = await this.validateForUndo(headTx);
+      if (conflicts.length > 0) {
+        throw new UndoConflictError(
+          `Cannot undo ${headTx.id}: ${conflicts.length} file(s) have been externally modified.
 
 ` + conflicts.join("\n"),
-        conflicts
-      );
+          conflicts
+        );
+      }
     }
     const ops = [];
     for (const fileId of headTx.touchedFiles) {
@@ -958,18 +1236,31 @@ var UndoEngine = class {
           break;
         case "modified": {
           if (!parentTx) {
-            throw new Error(`Cannot undo ${headTx.id}: File was modified in the very first transaction and its original state is untracked.`);
+            process.stderr.write(`\\x1b[33m\u26A0\\x1b[0m Skipping revert for ${filePath}: original state is untracked.\\n`);
+            break;
+          }
+          try {
+            const prevContent = await this.gitStore.readBlob(parentTx.commit, fileId);
+            ops.push({ type: "write", path: filePath, content: prevContent });
+          } catch (e) {
+            process.stderr.write(`\\x1b[33m\u26A0\\x1b[0m Skipping revert for ${filePath}: original state is untracked.\\n`);
           }
-          const prevContent = await this.gitStore.readBlob(parentTx.commit, fileId);
-          ops.push({ type: "write", path: filePath, content: prevContent });
           break;
         }
         case "deleted": {
           if (!parentTx) {
-            throw new Error(`Cannot undo ${headTx.id}: File was deleted in the very first transaction and its original state is untracked.`);
+            process.stderr.write(`\\x1b[33m\u26A0\\x1b[0m Skipping restore for ${filePath}: original state is untracked.\\n`);
+            break;
+          }
+          try {
+            const restoredContent = await this.gitStore.readBlob(parentTx.commit, fileId);
+            ops.push({ type: "write", path: filePath, content: restoredContent });
+          } catch (e) {
+            process.stderr.write(`\\x1b[33m\u26A0\\x1b[0m Skipping restore for ${filePath}: original state is untracked.\\n`);
           }
-          const restoredContent = await this.gitStore.readBlob(parentTx.commit, fileId);
-          ops.push({ type: "write", path: filePath, content: restoredContent });
+          break;
+        }
+        case "tracked": {
           break;
         }
       }
@@ -978,14 +1269,14 @@ var UndoEngine = class {
     const deletes = ops.filter((o) => o.type === "delete");
     for (const op of writes) {
       if (op.type === "write") {
-        await fs7.mkdir(path8.dirname(op.path), { recursive: true });
-        await fs7.writeFile(op.path, op.content);
+        await fs6.mkdir(path7.dirname(op.path), { recursive: true });
+        await fs6.writeFile(op.path, op.content);
       }
     }
     for (const op of deletes) {
       if (op.type === "delete") {
         try {
-          await fs7.unlink(op.path);
+          await fs6.unlink(op.path);
         } catch {
         }
         await this.removeEmptyParents(op.path);
@@ -993,7 +1284,7 @@ var UndoEngine = class {
     }
     for (const fileId of headTx.touchedFiles) {
       const changeType = headTx.changeManifest[fileId];
-      if (changeType === "created") {
+      if (changeType === "created" || changeType === "tracked") {
         this.fileMap.markDeleted(fileId, `undo:${headTx.id}`);
       } else if (changeType === "deleted") {
         this.fileMap.markRestored(fileId);
@@ -1010,11 +1301,28 @@ var UndoEngine = class {
     return {
       undone: headTx.id,
       newHead: headTx.parent,
-      filesRestored: ops.length
+      filesRestored: ops.length,
+      forced: options.force ?? false
     };
   }
   /** Redo the most recently undone transaction. */
   async redo() {
+    if (this.detector) {
+      const ext = await this.detector.detectAndRecord();
+      if (ext) {
+        const discarded = this.txStore.clearUndoStack();
+        if (discarded.length > 0) {
+          this.fileMap.untrackByTransactions(discarded);
+        }
+        await this.txStore.save();
+        await this.fileMap.save();
+        throw new Error(
+          `Redo cancelled: External changes were detected and recorded as \x1B[1m${ext.id}\x1B[0m.
+The redo chain has been cleared because the filesystem state no longer matches the expected pre-redo state.
+Run \x1B[1mtxr history\x1B[0m to review what changed.`
+        );
+      }
+    }
     if (this.txStore.undoStack.length === 0) {
       throw new Error("Nothing to redo.");
     }
@@ -1040,25 +1348,28 @@ var UndoEngine = class {
         case "created":
         case "modified": {
           const content = await this.gitStore.readBlob(redoTx.commit, fileId);
-          await fs7.mkdir(path8.dirname(filePath), { recursive: true });
-          await fs7.writeFile(filePath, content);
+          await fs6.mkdir(path7.dirname(filePath), { recursive: true });
+          await fs6.writeFile(filePath, content);
           filesChanged++;
           break;
         }
         case "deleted": {
           try {
-            await fs7.unlink(filePath);
+            await fs6.unlink(filePath);
           } catch {
           }
           await this.removeEmptyParents(filePath);
           filesChanged++;
           break;
         }
+        case "tracked": {
+          break;
+        }
       }
     }
     for (const fileId of redoTx.touchedFiles) {
       const changeType = redoTx.changeManifest[fileId];
-      if (changeType === "created") {
+      if (changeType === "created" || changeType === "tracked") {
         this.fileMap.markRestored(fileId);
       } else if (changeType === "deleted") {
         this.fileMap.markDeleted(fileId, `redo:${redoTx.id}`);
@@ -1076,8 +1387,7 @@ var UndoEngine = class {
   }
   /**
    * Validate all touched files for undo.
-   * Returns an array of human-readable conflict descriptions.
-   * Empty array = safe to proceed.
+   * Returns human-readable conflict descriptions. Empty = safe to proceed.
    */
   async validateForUndo(tx) {
     const conflicts = [];
@@ -1105,16 +1415,21 @@ var UndoEngine = class {
         );
         continue;
       }
-      const expectedContent = await this.gitStore.readBlob(tx.commit, fileId);
-      const actualContent = await fs7.readFile(filePath);
-      if (!this.hashEquals(expectedContent, actualContent)) {
-        const expectedHash = this.hash(expectedContent).substring(0, 12);
-        const actualHash = this.hash(actualContent).substring(0, 12);
-        conflicts.push(
-          `  \u2717 ${filePath}
+      try {
+        const expectedContent = await this.gitStore.readBlob(tx.commit, fileId);
+        const actualContent = await fs6.readFile(filePath);
+        if (!this.hashEquals(expectedContent, actualContent)) {
+          const expectedHash = this.hash(expectedContent).substring(0, 12);
+          const actualHash = this.hash(actualContent).substring(0, 12);
+          conflicts.push(
+            `  \u2717 ${filePath}
     Expected hash: ${expectedHash}...
     Actual hash:   ${actualHash}...`
-        );
+          );
+        }
+      } catch {
+        conflicts.push(`  \u2717 ${filePath}
+    Could not read blob from internal store.`);
       }
     }
     return conflicts;
@@ -1148,7 +1463,7 @@ var UndoEngine = class {
       if (parentTx) {
         try {
           const expectedContent = await this.gitStore.readBlob(parentTx.commit, fileId);
-          const actualContent = await fs7.readFile(filePath);
+          const actualContent = await fs6.readFile(filePath);
           if (!this.hashEquals(expectedContent, actualContent)) {
             conflicts.push(
               `  \u2717 ${filePath}
@@ -1163,7 +1478,7 @@ var UndoEngine = class {
   }
   async fileExists(filePath) {
     try {
-      await fs7.access(filePath);
+      await fs6.access(filePath);
       return true;
     } catch {
       return false;
@@ -1177,13 +1492,13 @@ var UndoEngine = class {
   }
   /** Remove empty parent directories up to a reasonable depth. */
   async removeEmptyParents(filePath) {
-    let dir = path8.dirname(filePath);
+    let dir = path7.dirname(filePath);
     for (let i = 0; i < 10; i++) {
       try {
-        const entries = await fs7.readdir(dir);
+        const entries = await fs6.readdir(dir);
         if (entries.length === 0) {
-          await fs7.rmdir(dir);
-          dir = path8.dirname(dir);
+          await fs6.rmdir(dir);
+          dir = path7.dirname(dir);
         } else {
           break;
         }
@@ -1195,18 +1510,25 @@ var UndoEngine = class {
 };
 
 // src/cli/commands/undo.ts
-async function undoCommand() {
+async function undoCommand(options = {}) {
   const cwd = process.cwd();
   const projectRoot = await findTxrRoot(cwd);
   const paths = getTxrPaths(projectRoot);
+  const config = await loadConfig(paths.metadataDir);
   const txStore = await TransactionStore.load(paths.metadataDir);
   const fileMap = await FileMap.load(paths.metadataDir);
   const gitStore = new GitStore(paths.repoDir);
-  const engine = new UndoEngine(txStore, fileMap, gitStore);
+  const detector = new ExternalChangeDetector(txStore, fileMap, gitStore, config, projectRoot);
+  const engine = new UndoEngine(txStore, fileMap, gitStore, detector);
   try {
-    const result = await engine.undo();
+    const result = await engine.undo({ force: options.force });
     console.log();
-    console.log(`\x1B[32m\u2713\x1B[0m Undone: \x1B[1m${result.undone}\x1B[0m`);
+    if (result.forced) {
+      console.log(`\x1B[33m\u26A0 Force undo applied.\x1B[0m Undone: \x1B[1m${result.undone}\x1B[0m`);
+      console.log(`  TXR assumes you have resolved any external side effects.`);
+    } else {
+      console.log(`\x1B[32m\u2713\x1B[0m Undone: \x1B[1m${result.undone}\x1B[0m`);
+    }
     console.log(`  ${result.filesRestored} file operation(s) applied`);
     console.log(`  HEAD: ${result.newHead ?? "(empty)"}`);
   } catch (err) {
@@ -1219,6 +1541,16 @@ async function undoCommand() {
       console.error("To resolve: manually revert the conflicting files, then retry `txr undo`.");
       process.exit(1);
     }
+    if (err instanceof PartialUndoBlockedError) {
+      console.error();
+      console.error(`\x1B[33mBLOCKED [P]:\x1B[0m ${err.message}`);
+      process.exit(1);
+    }
+    if (err instanceof ExternalUndoBlockedError) {
+      console.error();
+      console.error(`\x1B[33mBLOCKED [E]:\x1B[0m ${err.message}`);
+      process.exit(1);
+    }
     throw err;
   }
 }
@@ -1226,10 +1558,12 @@ async function redoCommand() {
   const cwd = process.cwd();
   const projectRoot = await findTxrRoot(cwd);
   const paths = getTxrPaths(projectRoot);
+  const config = await loadConfig(paths.metadataDir);
   const txStore = await TransactionStore.load(paths.metadataDir);
   const fileMap = await FileMap.load(paths.metadataDir);
   const gitStore = new GitStore(paths.repoDir);
-  const engine = new UndoEngine(txStore, fileMap, gitStore);
+  const detector = new ExternalChangeDetector(txStore, fileMap, gitStore, config, projectRoot);
+  const engine = new UndoEngine(txStore, fileMap, gitStore, detector);
   try {
     const result = await engine.redo();
     console.log();
@@ -1244,6 +1578,11 @@ async function redoCommand() {
       console.error("Redo aborted. No files were changed.");
       process.exit(1);
     }
+    if (err instanceof Error && err.message.startsWith("Redo cancelled:")) {
+      console.error();
+      console.error(`\x1B[33m\u26A0\x1B[0m ${err.message}`);
+      process.exit(1);
+    }
     throw err;
   }
 }
@@ -1266,30 +1605,47 @@ async function statusCommand() {
   console.log(`  Redo stack:    ${txStore.undoStack.length} transaction(s)`);
   console.log(`  Watch paths:   ${config.watchPaths.join(", ")}`);
 }
-async function historyCommand(count = 20) {
+async function historyCommand() {
   const cwd = process.cwd();
   const projectRoot = await findTxrRoot(cwd);
   const paths = getTxrPaths(projectRoot);
-  const historyStore = await HistoryStore.load(paths.metadataDir);
-  const entries = historyStore.getRecent(count);
-  if (entries.length === 0) {
-    console.log("\nNo command history yet.");
+  const txStore = await TransactionStore.load(paths.metadataDir);
+  const chain = txStore.getChain();
+  const redoStack = txStore.undoStack;
+  if (chain.length === 0 && redoStack.length === 0) {
+    console.log("\nNo transaction history yet.");
     return;
   }
-  console.log();
-  console.log(`\x1B[1mCommand History\x1B[0m (${entries.length} most recent)
-`);
-  for (const entry of entries) {
-    const txLabel = entry.transactionId ? `\x1B[32m${entry.transactionId}\x1B[0m` : "\x1B[90mno-tx\x1B[0m";
-    const tierLabel = entry.attributionTier ? `T${entry.attributionTier}` : "  ";
-    const timeStr = new Date(entry.timestamp).toLocaleTimeString();
-    console.log(`  ${timeStr}  ${tierLabel}  ${txLabel}  ${entry.command}`);
+  const printTx = (tx) => {
+    const txLabel = `\x1B[32m${tx.id}\x1B[0m`;
+    const tierLabel = tx.attributionTier ? `T${tx.attributionTier}` : "  ";
+    const typeLabel = tx.type === "U" ? "\x1B[32m[U]\x1B[0m" : tx.type === "P" ? "\x1B[33m[P]\x1B[0m" : "\x1B[35m[E]\x1B[0m";
+    const timeStr = new Date(tx.timestamp).toLocaleTimeString();
+    const commandStr = tx.command ?? "\x1B[90m[external change]\x1B[0m";
+    console.log(`  ${timeStr}  ${tierLabel}  ${txLabel}  ${typeLabel}  ${commandStr}`);
+  };
+  console.log("\n\x1B[1m=== Active Timeline (Undoable) ===\x1B[0m\n");
+  if (chain.length === 0) {
+    console.log("  (empty)");
+  } else {
+    for (const tx of chain) {
+      printTx(tx);
+    }
+  }
+  console.log("\n\x1B[1m==== [ CURRENT HEAD ] ====\x1B[0m\n");
+  if (redoStack.length > 0) {
+    console.log("\x1B[1m=== Next Commands (Available to Redo) ===\x1B[0m\n");
+    for (const txId of redoStack) {
+      const tx = txStore.get(txId);
+      if (tx) printTx(tx);
+    }
+    console.log();
   }
 }
 
 // src/cli/commands/clear.ts
-import * as fs8 from "fs/promises";
-import * as path9 from "path";
+import * as fs7 from "fs/promises";
+import * as path8 from "path";
 async function clearCommand(options) {
   const cwd = process.cwd();
   let projectRoot;
@@ -1302,7 +1658,7 @@ async function clearCommand(options) {
   if (!options.yes) {
     const readline = await import("readline");
     const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-    const answer = await new Promise((resolve6) => {
+    const answer = await new Promise((resolve7) => {
       console.log();
       console.log(`\x1B[33mWARNING:\x1B[0m`);
       console.log(`This will permanently delete all transaction history, undo history,`);
@@ -1310,7 +1666,7 @@ async function clearCommand(options) {
       console.log();
       console.log(`This operation cannot be undone.`);
       console.log();
-      rl.question("Continue? [y/N] ", resolve6);
+      rl.question("Continue? [y/N] ", resolve7);
     });
     rl.close();
     if (answer.trim().toLowerCase() !== "y") {
@@ -1318,14 +1674,14 @@ async function clearCommand(options) {
       return;
     }
   }
-  const txrDir = path9.join(projectRoot, ".txr");
-  const repoDir = path9.join(txrDir, "repo");
-  const metadataDir = path9.join(txrDir, "metadata");
+  const txrDir = path8.join(projectRoot, ".txr");
+  const repoDir = path8.join(txrDir, "repo");
+  const metadataDir = path8.join(txrDir, "metadata");
   try {
     let retries = 3;
     while (retries > 0) {
       try {
-        await fs8.rm(repoDir, { recursive: true, force: true });
+        await fs7.rm(repoDir, { recursive: true, force: true });
         break;
       } catch (err) {
         if (err.code === "EBUSY" || err.code === "EPERM") {
@@ -1334,27 +1690,27 @@ async function clearCommand(options) {
             throw new Error(`Files are locked by another process. Please close any IDEs or tools accessing the workspace and try again.
 Details: ${err.message}`);
           }
-          await new Promise((resolve6) => setTimeout(resolve6, 500));
+          await new Promise((resolve7) => setTimeout(resolve7, 500));
         } else {
           throw err;
         }
       }
     }
-    const { GitStore: GitStore2 } = await import("./git-store-XSOIM4KZ.js");
+    const { GitStore: GitStore2 } = await import("./git-store-MUETZYUT.js");
     const gitStore = new GitStore2(repoDir);
     await gitStore.init();
-    await fs8.writeFile(
-      path9.join(metadataDir, "transactions.json"),
+    await fs7.writeFile(
+      path8.join(metadataDir, "transactions.json"),
       JSON.stringify({ version: 1, head: null, undoStack: [], counter: 0, transactions: {} }, null, 2),
       "utf-8"
     );
-    await fs8.writeFile(
-      path9.join(metadataDir, "mapping.json"),
+    await fs7.writeFile(
+      path8.join(metadataDir, "mapping.json"),
       JSON.stringify({ version: 1, files: {} }, null, 2),
       "utf-8"
     );
-    await fs8.writeFile(
-      path9.join(metadataDir, "history.json"),
+    await fs7.writeFile(
+      path8.join(metadataDir, "history.json"),
       JSON.stringify({ version: 1, entries: [] }, null, 2),
       "utf-8"
     );
@@ -1369,9 +1725,133 @@ Details: ${err.message}`);
   }
 }
 
+// src/cli/commands/track.ts
+import { Command } from "commander";
+import * as path9 from "path";
+import * as fs8 from "fs/promises";
+function createTrackCommand() {
+  return new Command("track").description("Manually track an existing file to capture its baseline state").argument("<file>", "File to track").action(async (file) => {
+    try {
+      const cwd = process.cwd();
+      const absolutePath = path9.resolve(cwd, file);
+      try {
+        const stat4 = await fs8.stat(absolutePath);
+        if (!stat4.isFile()) {
+          console.error(`Error: ${file} is not a regular file.`);
+          process.exit(1);
+        }
+      } catch {
+        console.error(`Error: File ${file} does not exist.`);
+        process.exit(1);
+      }
+      const projectRoot = await findTxrRoot(cwd);
+      if (!projectRoot) {
+        console.error("Error: Not in a txr workspace (no .txr directory found).");
+        process.exit(1);
+      }
+      const paths = getTxrPaths(projectRoot);
+      const config = await loadConfig(paths.metadataDir);
+      const [txStore, fileMap, historyStore] = await Promise.all([
+        TransactionStore.load(paths.metadataDir),
+        FileMap.load(paths.metadataDir),
+        HistoryStore.load(paths.metadataDir)
+      ]);
+      const gitStore = new GitStore(paths.repoDir);
+      const existingId = fileMap.getIdByPath(absolutePath);
+      if (existingId) {
+        console.log(`File ${file} is already tracked.`);
+        return;
+      }
+      const discarded = txStore.clearUndoStack();
+      if (discarded.length > 0) {
+        fileMap.untrackByTransactions(discarded);
+      }
+      const txId = txStore.nextId();
+      const fileId = fileMap.getOrCreateId(absolutePath, txId);
+      const content = await fs8.readFile(absolutePath);
+      await gitStore.writeFile(fileId, content);
+      const commitMessage = `txr: ${txId} | txr track ${path9.basename(absolutePath)}`;
+      const commitHash = await gitStore.commit(commitMessage);
+      const tx = {
+        id: txId,
+        type: "U",
+        parent: txStore.head,
+        commit: commitHash,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        command: `txr track ${file}`,
+        source: "txr-run",
+        touchedFiles: [fileId],
+        changeManifest: { [fileId]: "tracked" },
+        workingDirectory: cwd,
+        exitCode: 0,
+        attributionTier: null,
+        scope: config.scope,
+        scopeWarnings: []
+      };
+      const discarded2 = txStore.addTransaction(tx);
+      if (discarded2.length > 0) {
+        fileMap.untrackByTransactions(discarded2);
+      }
+      await txStore.save();
+      await fileMap.save();
+      historyStore.append({
+        timestamp: tx.timestamp,
+        command: tx.command,
+        transactionId: txId,
+        workingDirectory: cwd,
+        exitCode: 0,
+        classification: "transactional",
+        attributionTier: null,
+        durationMs: 0,
+        actionType: "U"
+      });
+      await historyStore.save();
+      console.log(`\u2713 Baseline tracked: ${file}`);
+      console.log(`  Recorded as transaction \x1B[1m${txId}\x1B[0m.`);
+    } catch (error) {
+      console.error(`Error: ${error.message}`);
+      process.exit(1);
+    }
+  });
+}
+
+// src/cli/commands/api.ts
+import { Command as Command2 } from "commander";
+function createApiCommand() {
+  const api = new Command2("api").description("Headless API for agent integration");
+  api.command("sync").description("Detect all filesystem changes since HEAD and commit them as a transaction").requiredOption("--source <string>", "Source of the transaction (e.g. agent:write_file or external)").action(async (opts) => {
+    try {
+      const cwd = process.cwd();
+      const projectRoot = await findTxrRoot(cwd);
+      if (!projectRoot) {
+        console.error(JSON.stringify({ ok: false, error: "Not a txr repository" }));
+        process.exit(1);
+      }
+      const paths = getTxrPaths(projectRoot);
+      const config = await loadConfig(paths.metadataDir);
+      const txStore = await TransactionStore.load(paths.metadataDir);
+      const historyStore = await HistoryStore.load(paths.metadataDir);
+      const fileMap = await FileMap.load(paths.metadataDir);
+      const gitStore = new GitStore(paths.repoDir);
+      const { ExternalChangeDetector: ExternalChangeDetector2 } = await import("./external-detector-5TT634UP.js");
+      const detector = new ExternalChangeDetector2(txStore, fileMap, gitStore, config, projectRoot);
+      const tx = await detector.detectAndRecordWithSource(opts.source);
+      if (tx) {
+        console.log(JSON.stringify({ ok: true, transactionId: tx.id, changesCount: Object.keys(tx.changeManifest).length }));
+      } else {
+        console.log(JSON.stringify({ ok: true, transactionId: null, changesCount: 0 }));
+      }
+    } catch (err) {
+      console.error(JSON.stringify({ ok: false, error: err.stack }));
+      process.exit(1);
+    }
+  });
+  return api;
+}
+
 // src/index.ts
-var program = new Command();
-program.name("txr").description("Transactional command runner \u2014 undo any shell command").version("0.1.0");
+var program = new Command3();
+program.name("txr").description("Transactional command runner \u2014 undo any shell command").version("0.2.0");
 program.command("init").description("Initialize txr in the current directory").option("-g, --global", "Enable global tracking mode (track files outside workspace)").action(async (opts) => {
   try {
     const scope = opts.global ? "global" : "workspace";
@@ -1401,9 +1881,9 @@ program.command("run").description("Execute a command with transactional trackin
     process.exit(1);
   }
 });
-program.command("undo").description("Undo the most recent transaction").action(async () => {
+program.command("undo").description("Undo the most recent transaction").option("--force", "Skip safety checks and force the undo (for P and E transactions)").action(async (opts) => {
   try {
-    await undoCommand();
+    await undoCommand({ force: opts.force });
   } catch (err) {
     console.error(`\x1B[31mError:\x1B[0m ${err.message}`);
     process.exit(1);
@@ -1425,9 +1905,9 @@ program.command("status").description("Show current transaction state").action(a
     process.exit(1);
   }
 });
-program.command("history").description("Show command history").option("-n, --count <number>", "Number of entries to show", "20").action(async (opts) => {
+program.command("history").description("Show command history").option("-n, --count <number>", "Number of entries to show", "20").action(async () => {
   try {
-    await historyCommand(parseInt(opts.count, 10));
+    await historyCommand();
   } catch (err) {
     console.error(`\x1B[31mError:\x1B[0m ${err.message}`);
     process.exit(1);
@@ -1441,4 +1921,6 @@ program.command("clear").description("Reset the internal state and delete all tr
     process.exit(1);
   }
 });
+program.addCommand(createTrackCommand());
+program.addCommand(createApiCommand());
 program.parse();