filemayor 4.0.7 → 4.0.9

package/core/engine/para-engine.js

@@ -0,0 +1,370 @@
+/**
+ * ═══════════════════════════════════════════════════════════════════
+ * FILEMAYOR — PARA ENGINE
+ * Deterministic actionability sorter implementing Tiago Forte's PARA
+ * method (Projects · Areas · Resources · Archives).
+ *
+ * PARA organizes by *actionability*, not by file type. A pure semantic
+ * judgement (is this an active Project or an ongoing Area?) needs a
+ * human or an LLM — so this engine is deliberately honest: it sorts on
+ * the signals it can actually read (recency, category, folder names,
+ * project substrates) and labels every move with the reason it chose.
+ * Where it cannot tell, it says so (warnings) rather than guessing
+ * confidently. Semantic refinement is what the AI path is for.
+ *
+ * Output shape matches the Curative Plan consumed by ApplyEngine:
+ *   { narrative, confidence, warnings, plan: [{ source, destination,
+ *     reason, bucket }], summary }
+ * ═══════════════════════════════════════════════════════════════════
+ */
+
+'use strict';
+
+const path = require('path');
+const { scan } = require('../scanner');
+const { findNearestSubstrate } = require('../security');
+
+// ─── PARA Defaults ────────────────────────────────────────────────
+// Mirrors config.para in cli/core/config.js. Anything passed to the
+// constructor overrides these per-field.
+const DEFAULT_PARA = {
+    archiveAfterMonths: 12,   // not modified in ≥ this many months → Archives
+    activeWithinMonths: 3,    // modified within this window → Projects (active work)
+    defaultBucket: 'resources', // where files with no actionability signal land
+    preserveSubfolders: true, // keep the top-level subfolder name as a grouping
+    folders: {
+        projects: 'Projects',
+        areas: 'Areas',
+        resources: 'Resources',
+        archives: 'Archives',
+    },
+    // Ongoing responsibilities you maintain indefinitely (Areas).
+    areaKeywords: [
+        'finance', 'finances', 'financial', 'tax', 'taxes', 'invoice', 'invoices',
+        'receipt', 'receipts', 'banking', 'payroll', 'payslip', 'insurance',
+        'health', 'medical', 'fitness', 'home', 'house', 'car', 'vehicle',
+        'contract', 'contracts', 'legal', 'admin', 'hr', 'utilities', 'pet', 'pets',
+    ],
+    // File categories that are reference material by nature (Resources).
+    resourceCategories: ['books', 'fonts', 'design'],
+    // Folder names that signal reference/interest material (Resources).
+    resourceKeywords: [
+        'reference', 'references', 'template', 'templates', 'manual', 'manuals',
+        'docs', 'documentation', 'research', 'notes', 'inspiration', 'assets',
+        'library', 'resource', 'resources', 'guide', 'guides', 'cheatsheet',
+    ],
+    // Folder/name signals for active efforts with an end (Projects).
+    projectKeywords: [
+        'project', 'projects', 'client', 'clients', 'launch', 'campaign',
+        'sprint', 'deliverable', 'proposal', 'wip', 'draft', 'milestone',
+    ],
+};
+
+const MONTH_MS = 1000 * 60 * 60 * 24 * 30.44; // average month
+
+class PARAEngine {
+    /**
+     * @param {Object} paraConfig - Overrides for DEFAULT_PARA (typically config.para)
+     */
+    constructor(paraConfig = {}) {
+        this.config = {
+            ...DEFAULT_PARA,
+            ...paraConfig,
+            folders: { ...DEFAULT_PARA.folders, ...(paraConfig.folders || {}) },
+        };
+        // The four bucket folder names, lowercased, for idempotency checks.
+        this._bucketNames = new Set(
+            Object.values(this.config.folders).map(f => f.toLowerCase())
+        );
+    }
+
+    /**
+     * Generate a PARA reorganisation plan for a directory (read-only).
+     * @param {string} dirPath - Directory to organise
+     * @param {Object} [options]
+     * @param {number} [options.now] - Reference timestamp (ms) — injectable for tests
+     * @returns {Object} Curative-plan-shaped result
+     */
+    plan(dirPath, options = {}) {
+        const root = path.resolve(dirPath);
+        const now = options.now || Date.now();
+
+        const scanResult = scan(root, { ...(options.scanOptions || {}), includeDirectories: false });
+
+        const plan = [];
+        const counts = { projects: 0, areas: 0, resources: 0, archives: 0 };
+        const seenDest = new Set();
+        const movedSubstrates = new Set();
+        let noSignalCount = 0;
+        let alreadySorted = 0;
+
+        for (const file of scanResult.files) {
+            const rel = path.relative(root, file.path);
+            const segments = rel.split(path.sep);
+
+            // Idempotency: skip anything already living under a PARA bucket.
+            if (segments.length > 1 && this._bucketNames.has(segments[0].toLowerCase())) {
+                alreadySorted++;
+                continue;
+            }
+
+            // Project substrates (.git, package.json, .als, …) move as one
+            // atomic unit into Projects — never shredded file-by-file.
+            const substrate = findNearestSubstrate(file.path);
+            if (substrate) {
+                const substrateRoot = path.resolve(substrate);
+                // A substrate that IS the target dir can't be PARA-organised.
+                if (substrateRoot === root) continue;
+                if (movedSubstrates.has(substrateRoot)) continue;
+                movedSubstrates.add(substrateRoot);
+
+                const dest = this._dest(root, 'projects', [path.basename(substrateRoot)]);
+                plan.push({
+                    source: substrateRoot,
+                    destination: dest,
+                    bucket: 'projects',
+                    reason: `Active project (contains ${path.basename(substrate) === path.basename(substrateRoot) ? 'a project marker' : 'project files'}) — moved intact. COLLECTION_MOVE`,
+                });
+                counts.projects++;
+                continue;
+            }
+
+            const { bucket, reason, noSignal } = this._classify(file, rel, now);
+            if (noSignal) noSignalCount++;
+            counts[bucket]++;
+
+            // Preserve the top-level subfolder as a grouping inside the bucket.
+            const sub = (this.config.preserveSubfolders && segments.length > 1)
+                ? [segments[0]]
+                : [];
+            let dest = this._dest(root, bucket, [...sub, file.name]);
+
+            // Avoid two sources colliding on one destination within the plan.
+            if (seenDest.has(dest.toLowerCase())) {
+                const parsed = path.parse(dest);
+                dest = path.join(parsed.dir, `${parsed.name}_${counts[bucket]}${parsed.ext}`);
+            }
+            seenDest.add(dest.toLowerCase());
+
+            plan.push({ source: file.path, destination: dest, bucket, reason });
+        }
+
+        const warnings = [];
+        if (noSignalCount > 0) {
+            warnings.push(
+                `${noSignalCount} file(s) had no clear actionability signal and were placed in ` +
+                `${this.config.folders[this.config.defaultBucket]} for you to review.`
+            );
+        }
+        if (alreadySorted > 0) {
+            warnings.push(`${alreadySorted} file(s) were already inside a PARA folder and left untouched.`);
+        }
+
+        return {
+            mode: 'deterministic',
+            method: 'PARA',
+            narrative: this._narrative(counts, plan.length),
+            confidence: 100, // deterministic — every move is rule-derived
+            warnings,
+            plan,
+            summary: {
+                totalMoves: plan.length,
+                buckets: counts,
+                scanned: scanResult.files.length,
+            },
+        };
+    }
+
+    /**
+     * Create and populate the four PARA folders with teaching READMEs.
+     * Idempotent — existing folders/READMEs are left in place.
+     * @param {string} dirPath - Where to scaffold
+     * @returns {{ created: string[], folders: Object }}
+     */
+    scaffold(dirPath) {
+        const fs = require('fs');
+        const root = path.resolve(dirPath);
+        const created = [];
+
+        for (const key of ['projects', 'areas', 'resources', 'archives']) {
+            const folder = path.join(root, this.config.folders[key]);
+            if (!fs.existsSync(folder)) {
+                fs.mkdirSync(folder, { recursive: true });
+                created.push(folder);
+            }
+            const readme = path.join(folder, 'README.md');
+            if (!fs.existsSync(readme)) {
+                fs.writeFileSync(readme, PARA_READMES[key], 'utf8');
+                created.push(readme);
+            }
+        }
+
+        return { created, folders: this.config.folders };
+    }
+
+    // ─── Internals ────────────────────────────────────────────────
+
+    /**
+     * Decide a file's PARA bucket from the signals we can actually read.
+     *
+     * Order is deliberate: EXPLICIT INTENT first (file category and the
+     * folder names the user themselves chose), then INFERRED TIME signals
+     * as the fallback for loose, unfiled files. Rationale — if you already
+     * filed something under finances/ or templates/, honour that meaning
+     * regardless of age; don't fragment a maintained folder by date. The
+     * "stale → Archives" automation then targets exactly the loose junk
+     * where it's most valuable. Every branch states its reason.
+     */
+    _classify(file, rel, now) {
+        const hay = rel.toLowerCase();
+        const cat = file.category || 'other';
+        const ageMonths = this._ageMonths(file, now);
+
+        // ── Explicit intent ──────────────────────────────────────
+        // 1. Reference by nature — books, fonts, design assets.
+        if (this.config.resourceCategories.includes(cat)) {
+            return { bucket: 'resources', reason: `Reference material (${cat})` };
+        }
+
+        // 2. Ongoing responsibility — a maintained Area (finances/, health/…).
+        const areaHit = this._keywordHit(hay, this.config.areaKeywords);
+        if (areaHit) {
+            return { bucket: 'areas', reason: `Ongoing responsibility (matched "${areaHit}")` };
+        }
+
+        // 3. Reference by folder name (reference/, templates/, …).
+        const resourceHit = this._keywordHit(hay, this.config.resourceKeywords);
+        if (resourceHit) {
+            return { bucket: 'resources', reason: `Reference material (matched "${resourceHit}")` };
+        }
+
+        // 4. Explicit active-effort signal (client-*, *-launch, project/…).
+        const projectHit = this._keywordHit(hay, this.config.projectKeywords);
+        if (projectHit) {
+            return { bucket: 'projects', reason: `Active project (matched "${projectHit}")` };
+        }
+
+        // ── Inferred time signals (loose, unfiled files only) ─────
+        // 5. Inactive — not modified in a long time → Archives. The single
+        //    most automatable PARA decision, and the one humans avoid.
+        if (ageMonths !== null && ageMonths >= this.config.archiveAfterMonths) {
+            return { bucket: 'archives', reason: `Not modified in ${Math.round(ageMonths)} months` };
+        }
+
+        // 6. Recently active loose work → Projects.
+        if (ageMonths !== null && ageMonths <= this.config.activeWithinMonths) {
+            return { bucket: 'projects', reason: `Recently active (modified ${Math.round(ageMonths)} month(s) ago)` };
+        }
+
+        // 7. No clear actionability signal — honest fallback, flagged for review.
+        const fallback = this.config.defaultBucket;
+        return {
+            bucket: fallback,
+            reason: 'No clear actionability signal — placed here for review',
+            noSignal: true,
+        };
+    }
+
+    _ageMonths(file, now) {
+        const t = this._mtime(file);
+        if (t === null) return null;
+        return (now - t) / MONTH_MS;
+    }
+
+    _mtime(file) {
+        const m = file.modified || file.created;
+        if (!m) return null;
+        const t = (m instanceof Date) ? m.getTime() : new Date(m).getTime();
+        return Number.isFinite(t) ? t : null;
+    }
+
+    _keywordHit(haystack, keywords) {
+        for (const kw of keywords) {
+            // Word-ish boundary so "car" doesn't match "scary".
+            const re = new RegExp(`(^|[^a-z0-9])${escapeRe(kw)}([^a-z0-9]|$)`, 'i');
+            if (re.test(haystack)) return kw;
+        }
+        return null;
+    }
+
+    _dest(root, bucketKey, parts) {
+        return path.join(root, this.config.folders[bucketKey], ...parts);
+    }
+
+    _narrative(counts, total) {
+        if (total === 0) return 'Nothing to do — this folder is already PARA-organised or empty.';
+        const bits = [];
+        if (counts.projects) bits.push(`${counts.projects} to Projects`);
+        if (counts.areas) bits.push(`${counts.areas} to Areas`);
+        if (counts.resources) bits.push(`${counts.resources} to Resources`);
+        if (counts.archives) bits.push(`${counts.archives} to Archives`);
+        return `PARA plan: ${bits.join(', ')}. Every move is reversible after apply.`;
+    }
+}
+
+function escapeRe(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+// ─── Teaching READMEs (the democratization layer) ─────────────────
+// Plain-English so a first-timer who has never heard of PARA gets it.
+const PARA_READMES = {
+    projects: `# Projects
+
+**Active efforts with a goal and an end.** One folder per project.
+
+A project is anything you are *currently* working toward finishing:
+a trip you're planning, a deliverable due next month, a room you're
+renovating. When a project is done, move its folder to \`Archives\`.
+
+FileMayor places recently-modified files and anything that looks like
+active work here. You stay in control — review before applying.
+
+_PARA is a method created by Tiago Forte (Building a Second Brain).
+FileMayor automates it; it is not affiliated with or endorsed by him._
+`,
+    areas: `# Areas
+
+**Ongoing responsibilities you maintain — with no end date.**
+
+Areas are the standing parts of your life and work: Finances, Health,
+Home, a job role, a car you own. There's no "done" — you just keep them
+in good order. One folder per area (e.g. \`Finances\`, \`Health\`).
+
+FileMayor routes files whose names or folders match common areas
+(taxes, invoices, insurance, health…) here.
+
+_PARA method by Tiago Forte. FileMayor automates it; not affiliated._
+`,
+    resources: `# Resources
+
+**Topics and reference material you may want later.**
+
+Things that aren't tied to a current project or a responsibility, but
+are worth keeping: reference docs, templates, books, fonts, design
+assets, inspiration. One folder per topic.
+
+FileMayor places reference-type files (books, fonts, design) and
+anything in \`reference/\`, \`templates/\`, etc. here.
+
+_PARA method by Tiago Forte. FileMayor automates it; not affiliated._
+`,
+    archives: `# Archives
+
+**Inactive items from the other three categories.**
+
+Nothing is deleted — Archives is cold storage. When a project finishes
+or a resource stops being useful, it moves here, out of the way but
+recoverable.
+
+FileMayor automatically moves files you haven't touched in a long time
+(12+ months by default) here. This is the chore PARA users hate doing
+by hand — so FileMayor does it for you.
+
+_PARA method by Tiago Forte. FileMayor automates it; not affiliated._
+`,
+};
+
+module.exports = PARAEngine;
+module.exports.DEFAULT_PARA = DEFAULT_PARA;
+module.exports.PARA_READMES = PARA_READMES;

package/core/fs-abstraction.js

@@ -2,8 +2,13 @@
 
 /**
  * ═══════════════════════════════════════════════════════════════════
- * FILEMAYOR FS v3.0 — INTENT-READY FILESYSTEM ABSTRACTION
+ * FILEMAYOR FS v4.1 — INTENT-READY FILESYSTEM ABSTRACTION
  * Async, safe, transactional, and fully rollbackable.
+ *
+ * v4.0.9: deletes are trash-based and journaled (undo restores them),
+ * the trash lives in the user's home dir (survives reboots — it used
+ * to sit in os.tmpdir()), and every journal entry carries a sessionId
+ * so `undo` can target a specific past session.
  * ═══════════════════════════════════════════════════════════════════
  */
 
@@ -17,15 +22,23 @@ const crypto = require('crypto');
 const { validatePath, isFileSafe, isDirSafe, canRead, canWrite } = require('./security');
 const { formatBytes } = require('./scanner');
 
+const JOURNAL_PATH = path.join(os.homedir(), '.filemayor-master-journal.ndjson');
+// Durable, FileMayor-managed trash. NOT os.tmpdir() — that gets wiped on
+// reboot, which would silently break the "deletions are reversible" promise.
+const TRASH_PATH = path.join(os.homedir(), '.filemayor-trash');
+
 class FileMayorFS {
     constructor(options = {}) {
         this.options = {
             useJournal: true,
             dryRun: false,
-            trashPath: path.join(os.tmpdir(), 'filemayor_trash'),
-            journalPath: path.join(os.homedir(), '.filemayor-master-journal.ndjson'),
+            trashPath: TRASH_PATH,
+            journalPath: JOURNAL_PATH,
             ...options
         };
+        // One session per FileMayorFS instance — every CLI/MCP/desktop
+        // operation batch gets its own id, so undo can address it later.
+        this.sessionId = crypto.randomUUID().slice(0, 8);
         this.sessionJournal = [];
         this.stats = {
             opsSucceeded: 0,
@@ -81,14 +94,7 @@ class FileMayorFS {
             const opId = crypto.randomUUID();
             await this._journalPending(opId, source, destination, 'move', snapshot);
 
-            try {
-                await fs.rename(source, destination);
-            } catch (err) {
-                if (err.code === 'EXDEV') {
-                    await fs.copyFile(source, destination);
-                    await fs.unlink(source);
-                } else throw err;
-            }
+            await this._rename(source, destination);
 
             // WAL: record completion AFTER the operation
             await this._journalDone(opId);
@@ -109,26 +115,56 @@ class FileMayorFS {
     }
 
     /** ------------------------
-     * Safe Delete with Trash
+     * Safe Delete → Trash (journaled, undoable)
      * -------------------------*/
     async delete(target) {
-        const check = isFileSafe(target);
+        let isDir = false;
+        try {
+            isDir = (await fs.stat(target)).isDirectory();
+        } catch { /* stat below via snapshot; safety checks will surface errors */ }
+
+        const check = isDir ? isDirSafe(target) : isFileSafe(target);
         if (!check.safe) throw new Error(`Target unsafe: ${check.reason}`);
 
         const snapshot = await this.createSnapshot(target);
 
         if (this.options.dryRun) return { target, status: 'dry-run' };
 
-        const trashFile = path.join(this.options.trashPath, path.basename(target) + '-' + Date.now());
-        await fs.rename(target, trashFile);
+        // Unique trash destination — timestamp + random slug prevents
+        // collisions when many same-named files are trashed in one batch.
+        const slug = `${Date.now()}-${crypto.randomUUID().slice(0, 8)}`;
+        const trashFile = path.join(this.options.trashPath, `${slug}-${path.basename(target)}`);
+
+        // WAL: journal BEFORE the move so a crash mid-delete is recoverable.
+        // Journaled as a normal source→destination pair: rollback's generic
+        // "rename(destination, source)" restores the file from the trash.
+        const opId = crypto.randomUUID();
+        await this._journalPending(opId, target, trashFile, 'delete', snapshot);
+        await this._rename(target, trashFile);
+        await this._journalDone(opId);
 
         this.stats.opsSucceeded++;
         this.stats.filesDeleted++;
         this.stats.totalBytesProcessed += snapshot.size || 0;
 
-        await this._logToJournal(target, trashFile, 'delete', snapshot);
+        return { target, trashFile, status: 'success' };
+    }
 
-        return { target, status: 'success' };
+    /** Rename with cross-device fallback (files and directories). */
+    async _rename(source, destination) {
+        try {
+            await fs.rename(source, destination);
+        } catch (err) {
+            if (err.code !== 'EXDEV') throw err;
+            const st = await fs.stat(source);
+            if (st.isDirectory()) {
+                await fs.cp(source, destination, { recursive: true });
+                await fs.rm(source, { recursive: true, force: true });
+            } else {
+                await fs.copyFile(source, destination);
+                await fs.unlink(source);
+            }
+        }
     }
 
     /** ------------------------
@@ -144,15 +180,10 @@ class FileMayorFS {
         }
     }
 
-    async _logToJournal(source, destination, action, snapshot) {
-        // WAL: record intent BEFORE operation (called pre-move),
-        // then update to 'done' AFTER (called post-move).
-        // This is handled by _journalPending / _journalDone.
-    }
-
     async _journalPending(id, source, destination, action, snapshot) {
         const entry = {
             id,
+            sessionId: this.sessionId,
             timestamp: new Date().toISOString(),
             action,
             source,
@@ -170,32 +201,20 @@ class FileMayorFS {
     }
 
     /** ------------------------
-     * Rollback
+     * Crash-recovery rollback: reverses operations that never completed
+     * (pending but not done). For undoing COMPLETED sessions, use the
+     * standalone rollback()/listSessions() below.
      * -------------------------*/
     async rollback() {
-        const entries = new Map();
-        const done = new Set();
-
-        if (fssync.existsSync(this.options.journalPath)) {
-            const lines = fssync.readFileSync(this.options.journalPath, 'utf8').split('\n');
-            for (const line of lines) {
-                if (!line.trim()) continue;
-                try {
-                    const rec = JSON.parse(line);
-                    if (rec.status === 'pending') entries.set(rec.id, rec);
-                    if (rec.status === 'done')    done.add(rec.id);
-                } catch { /* skip malformed lines */ }
-            }
-        }
+        const { entries, done, rolledBack } = _readJournal(this.options.journalPath);
 
         // Add session-only pending entries not yet on disk
         for (const e of this.sessionJournal) {
             if (!entries.has(e.id)) entries.set(e.id, e);
         }
 
-        // Reverse-order rollback of moves that never completed
         const toRollback = [...entries.values()]
-            .filter(e => !done.has(e.id))
+            .filter(e => !done.has(e.id) && !rolledBack.has(e.id))
             .sort((a, b) => b.timestamp.localeCompare(a.timestamp));
 
         console.log(`[SYS] Rolling back ${toRollback.length} incomplete operations...`);
@@ -220,16 +239,11 @@ class FileMayorFS {
     }
 }
 
-const JOURNAL_PATH = path.join(os.homedir(), '.filemayor-master-journal.ndjson');
-
-/**
- * Standalone rollback function that reads the master journal on disk
- * and reverses all completed operations (status === 'done').
- * Returns { reversed: Array<entry>, count: number }.
- */
-async function rollback(journalPath) {
+/** Parse the NDJSON master journal into pending entries + status sets. */
+function _readJournal(journalPath) {
     const entries = new Map();
     const done = new Set();
+    const rolledBack = new Set();
 
     if (fssync.existsSync(journalPath)) {
         const lines = fssync.readFileSync(journalPath, 'utf8').split('\n');
@@ -237,21 +251,76 @@ async function rollback(journalPath) {
             if (!line.trim()) continue;
             try {
                 const rec = JSON.parse(line);
-                if (rec.status === 'pending') entries.set(rec.id, rec);
-                if (rec.status === 'done')    done.add(rec.id);
+                if (rec.status === 'pending')     entries.set(rec.id, rec);
+                if (rec.status === 'done')        done.add(rec.id);
+                if (rec.status === 'rolled-back') rolledBack.add(rec.id);
             } catch { /* skip malformed lines */ }
         }
     }
+    return { entries, done, rolledBack };
+}
 
-    // Rollback moves that completed successfully (status === 'done')
-    const toRollback = [...entries.values()]
-        .filter(e => done.has(e.id))
+/** Completed-and-not-yet-undone entries, newest first. */
+function _completedEntries(journalPath) {
+    const { entries, done, rolledBack } = _readJournal(journalPath);
+    return [...entries.values()]
+        .filter(e => done.has(e.id) && !rolledBack.has(e.id))
         .sort((a, b) => b.timestamp.localeCompare(a.timestamp));
+}
+
+/**
+ * List undoable sessions from the master journal, newest first.
+ * Entries written before v4.0.9 (no sessionId) group under 'legacy'.
+ * @returns {Array<{sessionId, start, end, ops, moves, deletes}>}
+ */
+function listSessions(journalPath = JOURNAL_PATH) {
+    const sessions = new Map();
+    for (const e of _completedEntries(journalPath)) {
+        const sid = e.sessionId || 'legacy';
+        if (!sessions.has(sid)) {
+            sessions.set(sid, { sessionId: sid, start: e.timestamp, end: e.timestamp, ops: 0, moves: 0, deletes: 0 });
+        }
+        const s = sessions.get(sid);
+        s.ops++;
+        if (e.action === 'delete') s.deletes++;
+        else s.moves++;
+        if (e.timestamp < s.start) s.start = e.timestamp;
+        if (e.timestamp > s.end) s.end = e.timestamp;
+    }
+    return [...sessions.values()].sort((a, b) => b.end.localeCompare(a.end));
+}
+
+/**
+ * Undo completed operations from the master journal.
+ * @param {string} journalPath
+ * @param {Object} [options]
+ * @param {boolean} [options.all]      Undo every completed session (pre-4.0.9 behaviour).
+ * @param {string}  [options.sessionId] Undo one specific session.
+ * Default (no options): undo only the MOST RECENT session.
+ * Returns { reversed, count, sessionId }.
+ */
+async function rollback(journalPath = JOURNAL_PATH, options = {}) {
+    let toRollback = _completedEntries(journalPath);
+    let targetSession = null;
+
+    if (options.sessionId) {
+        targetSession = options.sessionId;
+        toRollback = toRollback.filter(e => (e.sessionId || 'legacy') === options.sessionId);
+    } else if (!options.all) {
+        // Latest session only — "undo" means "undo what just happened",
+        // not "unwind everything FileMayor has ever done".
+        const sessions = listSessions(journalPath);
+        if (sessions.length > 0) {
+            targetSession = sessions[0].sessionId;
+            toRollback = toRollback.filter(e => (e.sessionId || 'legacy') === targetSession);
+        }
+    }
 
     const reversed = [];
     for (const entry of toRollback) {
         try {
             if (fssync.existsSync(entry.destination)) {
+                await fs.mkdir(path.dirname(entry.source), { recursive: true });
                 await fs.rename(entry.destination, entry.source);
                 fssync.appendFileSync(journalPath,
                     JSON.stringify({ id: entry.id, status: 'rolled-back', rolledBackAt: new Date().toISOString() }) + '\n',
@@ -263,9 +332,33 @@ async function rollback(journalPath) {
         }
     }
 
-    return { reversed, count: reversed.length };
+    return { reversed, count: reversed.length, sessionId: targetSession };
+}
+
+/**
+ * Permanently remove trashed files older than `olderThanDays`.
+ * Never wired to an automatic timer — explicit calls only.
+ */
+async function emptyTrash(olderThanDays = 30, trashPath = TRASH_PATH) {
+    let removed = 0;
+    const cutoff = Date.now() - olderThanDays * 24 * 60 * 60 * 1000;
+    if (!fssync.existsSync(trashPath)) return { removed };
+    for (const name of await fs.readdir(trashPath)) {
+        const full = path.join(trashPath, name);
+        try {
+            const st = await fs.stat(full);
+            if (st.mtimeMs < cutoff) {
+                await fs.rm(full, { recursive: true, force: true });
+                removed++;
+            }
+        } catch { /* skip entries we cannot stat */ }
+    }
+    return { removed };
 }
 
 module.exports = FileMayorFS;
 module.exports.JOURNAL_PATH = JOURNAL_PATH;
+module.exports.TRASH_PATH = TRASH_PATH;
 module.exports.rollback = rollback;
+module.exports.listSessions = listSessions;
+module.exports.emptyTrash = emptyTrash;