filemayor 4.0.8 → 4.0.9

package/core/ai/planner.js

@@ -30,10 +30,21 @@ class CurativePlanner {
             cwd: process.cwd()
         };
 
+        // PARA (v4.0.9): give every provider the same hard contract so the
+        // plan lands in the four buckets and survives validation.
+        let prompt = rawPrompt;
+        if (intent.strategy === 'para_actionability') {
+            prompt = `${rawPrompt}\n\nSort by ACTIONABILITY using the PARA method. HARD RULES:\n` +
+                `- Every destination path MUST begin with exactly one of: Projects/, Areas/, Resources/, Archives/.\n` +
+                `- Projects = active efforts with an end; Areas = ongoing responsibilities (finances, health, home); ` +
+                `Resources = reference material; Archives = anything inactive or untouched for 12+ months.\n` +
+                `- Keep project folders intact (never split a code or media project).`;
+        }
+
         // Standardized Bridge: Telemetry is passed as clusters
         return await this.interpreter.interpret(
-            rawPrompt,
-            sentryData.clusters, 
+            prompt,
+            sentryData.clusters,
             context
         );
     }

package/core/ai/strategist.js

@@ -67,6 +67,14 @@ const ARCHETYPES = {
         nameSignals: ['book', 'chapter', 'isbn', 'edition', 'vol_', 'author'],
         strategy: 'ancestry_matching',
         hierarchy: 'Genre / Subject → Author → Title'
+    },
+    para: {
+        label: 'PARA (actionability)',
+        extSignals: [],
+        nameSignals: ['para'],
+        strategy: 'para_actionability',
+        hierarchy: 'Projects / Areas / Resources / Archives',
+        folders: ['Projects', 'Areas', 'Resources', 'Archives']
     }
 };
 
@@ -83,7 +91,13 @@ class IntentStrategist {
 
         const isRefine = p.includes('refine') || p.includes('structure') || p.includes('within');
 
-        if (p.includes('clean') || p.includes('space') || p.includes('junk')) {
+        // PARA must be detected FIRST — its prompts contain "projects",
+        // which the technical/codebase branch below would otherwise claim.
+        if (p.includes('para') || p.includes('actionability') || (p.includes('areas') && p.includes('archives'))) {
+            intent = 'para_sort';
+            strategy = 'para_actionability';
+            archetype = 'para';
+        } else if (p.includes('clean') || p.includes('space') || p.includes('junk')) {
             intent = 'cleanup';
             strategy = 'retention';
         } else if (p.includes('tax') || p.includes('invoice') || p.includes('receipt')) {

package/core/ai/validator.js

@@ -29,6 +29,11 @@ class SecurityArchitect {
         }
 
         const domainTriggerFolders = ['books', 'library', 'projects', 'music', 'work', 'downloads'];
+        // PARA buckets (v4.0.9): a deliberate re-filing INTO one of the four
+        // actionability buckets is not "domain scattering" — it is the point
+        // of a PARA plan. Destinations rooted in a bucket bypass only the
+        // domain-preservation rule; path-safety and bundle locks still apply.
+        const paraBuckets = new Set(['projects', 'areas', 'resources', 'archives']);
         const clusters = sentryData?.clusters || {};
         const allSamples = Object.values(clusters).flatMap(c => c.samples || []);
         const homeParts = this._homePrefixParts;
@@ -54,14 +59,15 @@ class SecurityArchitect {
                 const destParts = normalize(step.destination);
 
                 const triggerFound = srcParts.find(p => domainTriggerFolders.includes(p));
+                const destIsParaBucket = destParts.some(p => paraBuckets.has(p));
 
-                if (triggerFound) {
+                if (triggerFound && !destIsParaBucket) {
                     // A move is valid if the EXACT trigger folder is present in the destination path
                     const preserved = destParts.includes(triggerFound);
 
-                    if (!preserved && !step.reason.includes('COLLECTION_MOVE')) {
+                    if (!preserved && !(step.reason || '').includes('COLLECTION_MOVE')) {
                         console.warn(`[ARCHITECTURE] Blocked domain scattering for ${step.source} -> ${step.destination}`);
-                        return false; 
+                        return false;
                     }
                 }
 

package/core/cleaner.js

@@ -394,18 +394,24 @@ class Cleaner {
 // ─── Deletion ─────────────────────────────────────────────────────
 
 /**
- * Delete junk files and directories
+ * Delete junk files and directories — trash-based and journaled, so
+ * `filemayor undo` restores anything removed by mistake (v4.0.9; this
+ * used to unlink/rmSync permanently).
  * @param {Object[]} junkItems - Items from findJunk
  * @param {Object} options - Deletion options
- * @returns {{ deleted: number, freed: number, freedHuman: string, errors: Object[] }}
+ * @returns {Promise<{ deleted: number, freed: number, freedHuman: string, errors: Object[] }>}
  */
-function deleteJunk(junkItems, options = {}) {
+async function deleteJunk(junkItems, options = {}) {
     const {
         onProgress = null,
         onError = null,
         filterCategories = null, // Only delete these categories
+        fmfs = null,             // Shared FileMayorFS (one undo session per clean run)
     } = options;
 
+    const FileMayorFS = require('./fs-abstraction');
+    const trashFs = fmfs || new FileMayorFS();
+
     let deleted = 0;
     let freed = 0;
     const errors = [];
@@ -437,7 +443,7 @@ function deleteJunk(junkItems, options = {}) {
             if (!canWrite(path.dirname(item.path))) {
                 throw new Error('Permission denied');
             }
-            fs.unlinkSync(item.path);
+            await trashFs.delete(item.path);
             deleted++;
             freed += item.size;
         } catch (err) {
@@ -447,7 +453,7 @@ function deleteJunk(junkItems, options = {}) {
         }
     }
 
-    // Delete directories (sort by depth descending — deepest first)
+    // Trash directories (sort by depth descending — deepest first)
     const sortedDirs = dirs.sort((a, b) => {
         const depthA = a.path.split(path.sep).length;
         const depthB = b.path.split(path.sep).length;
@@ -456,11 +462,7 @@ function deleteJunk(junkItems, options = {}) {
 
     for (const dir of sortedDirs) {
         try {
-            if (dir.type === 'empty_directory') {
-                fs.rmdirSync(dir.path);
-            } else {
-                fs.rmSync(dir.path, { recursive: true, force: true });
-            }
+            await trashFs.delete(dir.path);
             deleted++;
             freed += dir.size;
         } catch (err) {
@@ -473,7 +475,10 @@ function deleteJunk(junkItems, options = {}) {
         freed,
         freedHuman: formatBytes(freed),
         errors,
-        total: toDelete.length
+        total: toDelete.length,
+        reversible: true,
+        trashPath: trashFs.options.trashPath,
+        sessionId: trashFs.sessionId
     };
 }
 
@@ -488,9 +493,9 @@ function findJunk(dirPath, options = {}) {
 }
 
 /**
- * Quick clean: scan + delete in one call
+ * Quick clean: scan + trash in one call (reversible with undo)
  */
-function clean(dirPath, options = {}) {
+async function clean(dirPath, options = {}) {
     const { dryRun = false, filterCategories = null, ...scanOptions } = options;
 
     const result = findJunk(dirPath, scanOptions);
@@ -504,7 +509,7 @@ function clean(dirPath, options = {}) {
         };
     }
 
-    const deleteResult = deleteJunk(result.junk, {
+    const deleteResult = await deleteJunk(result.junk, {
         filterCategories,
         onProgress: scanOptions.onProgress,
         onError: scanOptions.onError,

package/core/config.js

@@ -534,14 +534,14 @@ security:
 
 /**
  * Generate a PARA-method .filemayor.yml template.
- * PARA (Projects, Areas, Resources, Archives) is a method by Tiago Forte;
- * FileMayor automates it — this preset tunes the actionability sorter.
+ * PARA (Projects, Areas, Resources, Archives) is an actionability-based
+ * organizing method; this preset tunes the sorter.
  * @returns {string} YAML config template
  */
 function generateParaTemplate() {
     return `# ═══════════════════════════════════════════════════════════
 # FileMayor Configuration — PARA preset
-# PARA = Projects · Areas · Resources · Archives (method by Tiago Forte).
+# PARA = Projects · Areas · Resources · Archives.
 # FileMayor automates it by sorting files on actionability signals.
 # Run:  filemayor para .        (preview the plan)
 #       filemayor apply         (execute, fully reversible)

package/core/engine/dedupe-engine.js

@@ -3,43 +3,125 @@
 const { scan, formatBytes } = require('../scanner');
 const crypto = require('crypto');
 const fs = require('fs');
+const fsp = require('fs').promises;
+const FileMayorFS = require('../fs-abstraction');
+
+const PARTIAL_BYTES = 64 * 1024; // head sample for the cheap pass
+const HASH_CONCURRENCY = 8;      // parallel file reads for hashing
+
+/** Run an async mapper over items with bounded concurrency. */
+async function pooled(items, limit, fn) {
+    const results = new Array(items.length);
+    let next = 0;
+    async function worker() {
+        while (next < items.length) {
+            const i = next++;
+            results[i] = await fn(items[i], i);
+        }
+    }
+    await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+    return results;
+}
+
+/** SHA-1 of the first PARTIAL_BYTES of a file (cheap collision filter). */
+async function partialHash(filePath) {
+    const fd = await fsp.open(filePath, 'r');
+    try {
+        const buf = Buffer.alloc(PARTIAL_BYTES);
+        const { bytesRead } = await fd.read(buf, 0, PARTIAL_BYTES, 0);
+        return crypto.createHash('sha1').update(buf.subarray(0, bytesRead)).digest('hex');
+    } finally {
+        await fd.close();
+    }
+}
+
+/** Streaming SHA-1 of the whole file — constant memory at any size. */
+function fullHash(filePath) {
+    return new Promise((resolve, reject) => {
+        const hash = crypto.createHash('sha1');
+        fs.createReadStream(filePath)
+            .on('data', (chunk) => hash.update(chunk))
+            .on('end', () => resolve(hash.digest('hex')))
+            .on('error', reject);
+    });
+}
 
 /**
- * DedupeEngine — specialized engine for finding and removing duplicates
+ * DedupeEngine — finds and removes duplicate files.
+ *
+ * v4.0.9: detection is genuinely content-based (it used to match on
+ * size+name, despite the docs saying "hash-based"). Three-stage pipeline
+ * keeps it fast on huge folders:
+ *   1. size buckets   — only sizes shared by 2+ files go further
+ *   2. partial hash   — first 64 KB, eliminates most collisions cheaply
+ *   3. full hash      — streamed, only for files whose heads collide
+ * Removal is trash-based and journaled: `filemayor undo` restores.
  */
 class DedupeEngine {
-    constructor() {}
+    constructor(options = {}) {
+        this.fmfs = options.fmfs || new FileMayorFS(options.fsOptions || {});
+    }
 
     /**
-     * Find duplicates in a directory
-     * @param {string} dirPath 
-     * @returns {Object} Duplicate report
+     * Find duplicates in a directory (content-hash based).
+     * @param {string} dirPath
+     * @returns {Promise<Object>} Duplicate report
      */
-    find(dirPath) {
+    async find(dirPath) {
         const result = scan(dirPath, { maxDepth: 10 });
-        const map = new Map();
-        const duplicates = [];
-        let totalWasted = 0;
 
+        // Stage 1 — size buckets. A file can only duplicate a same-sized file.
+        const bySize = new Map();
         for (const file of result.files) {
-            // Heuristic-based match (size + name)
-            // In a real pro version, we might do checksums here, 
-            // but for a fast CLI, this is the "Viral" speed way.
-            const key = `${file.size}-${file.name}`;
-            if (map.has(key)) {
-                const original = map.get(key);
-                duplicates.push({
-                    original,
-                    duplicate: file
-                });
-                totalWasted += file.size;
-            } else {
-                map.set(key, file);
+            if (!file.size) continue; // zero-byte files: skip (all "identical", rarely useful)
+            if (!bySize.has(file.size)) bySize.set(file.size, []);
+            bySize.get(file.size).push(file);
+        }
+        const candidates = [...bySize.values()].filter(g => g.length > 1).flat();
+
+        // Stage 2 — partial hash over candidates only.
+        const partials = await pooled(candidates, HASH_CONCURRENCY, async (f) => {
+            try { return `${f.size}:${await partialHash(f.path)}`; } catch { return null; }
+        });
+        const byPartial = new Map();
+        candidates.forEach((f, i) => {
+            const key = partials[i];
+            if (!key) return;
+            if (!byPartial.has(key)) byPartial.set(key, []);
+            byPartial.get(key).push(f);
+        });
+        const finalists = [...byPartial.values()].filter(g => g.length > 1).flat();
+
+        // Stage 3 — full streamed hash for head-colliders.
+        const fulls = await pooled(finalists, HASH_CONCURRENCY, async (f) => {
+            try { return `${f.size}:${await fullHash(f.path)}`; } catch { return null; }
+        });
+        const byFull = new Map();
+        finalists.forEach((f, i) => {
+            const key = fulls[i];
+            if (!key) return;
+            if (!byFull.has(key)) byFull.set(key, []);
+            byFull.get(key).push(f);
+        });
+
+        const duplicates = [];
+        let totalWasted = 0;
+        for (const group of byFull.values()) {
+            if (group.length < 2) continue;
+            // Keep the oldest copy as the original; the rest are duplicates.
+            group.sort((a, b) => new Date(a.modified) - new Date(b.modified));
+            const original = group[0];
+            for (const dupe of group.slice(1)) {
+                duplicates.push({ original, duplicate: dupe });
+                totalWasted += dupe.size;
             }
         }
 
         return {
             path: dirPath,
+            method: 'content-hash',
+            scanned: result.files.length,
+            hashed: finalists.length,
             sets: duplicates.length,
             totalWasted,
             totalWastedHuman: formatBytes(totalWasted),
@@ -48,7 +130,8 @@ class DedupeEngine {
     }
 
     /**
-     * Remove duplicates based on a report
+     * Remove duplicates from a report. Trash-based: every removal is
+     * journaled and reversible with `filemayor undo`.
      */
     async clean(report) {
         let deleted = 0;
@@ -57,7 +140,7 @@ class DedupeEngine {
 
         for (const set of report.duplicates) {
             try {
-                fs.unlinkSync(set.duplicate.path);
+                await this.fmfs.delete(set.duplicate.path);
                 deleted++;
                 freed += set.duplicate.size;
             } catch (err) {
@@ -69,7 +152,10 @@ class DedupeEngine {
             deleted,
             freed,
             freedHuman: formatBytes(freed),
-            errors
+            errors,
+            reversible: true,
+            trashPath: this.fmfs.options.trashPath,
+            sessionId: this.fmfs.sessionId
         };
     }
 }

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;

package/core/watcher.js

@@ -80,8 +80,15 @@ class FileWatcher extends EventEmitter {
             maxLogEntries: options.maxLogEntries || 10000,
             autoOrganize: options.autoOrganize || false,
             organizeOptions: options.organizeOptions || {},
+            // PARA mode (v4.0.9): route each new file into Projects/Areas/
+            // Resources/Archives by actionability as it lands. Journaled.
+            paraMode: options.paraMode || false,
+            paraConfig: options.paraConfig || {},
         };
 
+        this._fmfs = null;       // lazy — shared journal session for this watcher
+        this._paraEngine = null; // lazy — built on first PARA routing
+
         this._watchers = new Map();
         this._debounceTimers = new Map();
         this._running = false;
@@ -338,6 +345,11 @@ class FileWatcher extends EventEmitter {
             break; // First match wins
         }
 
+        // PARA mode — route the new file into its actionability bucket
+        if (this.options.paraMode && eventType === 'rename') {
+            this._routePara(fullPath, filename, watchDir, stats);
+        }
+
         // Auto-organize if enabled
         if (this.options.autoOrganize && eventType === 'rename') {
             // A new file appeared — organize the directory
@@ -353,6 +365,65 @@ class FileWatcher extends EventEmitter {
         }
     }
 
+    /** Lazy shared FileMayorFS — one journal session per watcher run. */
+    _getFmfs() {
+        if (!this._fmfs) {
+            const FileMayorFS = require('./fs-abstraction');
+            this._fmfs = new FileMayorFS();
+        }
+        return this._fmfs;
+    }
+
+    /**
+     * PARA mode: classify one new file by actionability and move it into
+     * Projects/Areas/Resources/Archives. Skips files already inside a
+     * bucket (no loops — the move itself fires another watch event).
+     */
+    _routePara(fullPath, filename, watchDir, stats) {
+        try {
+            if (!this._paraEngine) {
+                const PARAEngine = require('./engine/para-engine');
+                this._paraEngine = new PARAEngine(this.options.paraConfig);
+            }
+            const engine = this._paraEngine;
+            const folders = engine.config.folders;
+
+            const rel = path.relative(watchDir, fullPath);
+            const firstSegment = rel.split(path.sep)[0].toLowerCase();
+            const bucketNames = new Set(Object.values(folders).map(f => f.toLowerCase()));
+            if (bucketNames.has(firstSegment)) return; // already sorted
+
+            const fileInfo = {
+                name: filename,
+                path: fullPath,
+                category: categorize(path.extname(filename).toLowerCase()),
+                size: stats.size,
+                modified: stats.mtime,
+            };
+            const { bucket, reason } = engine._classify(fileInfo, rel, Date.now());
+            const destination = path.join(watchDir, folders[bucket], filename);
+
+            this._getFmfs().move(fullPath, destination)
+                .then(() => {
+                    this._stats.filesActioned++;
+                    this.emit('action', {
+                        action: 'para-route',
+                        source: fullPath,
+                        destination,
+                        bucket,
+                        reason,
+                    });
+                })
+                .catch((err) => {
+                    this._stats.errors++;
+                    this.emit('error', { action: 'para-route', path: fullPath, error: err.message });
+                });
+        } catch (err) {
+            this._stats.errors++;
+            this.emit('error', { action: 'para-route', path: fullPath, error: err.message });
+        }
+    }
+
     /**
      * Execute a matched rule
      */
@@ -400,13 +471,20 @@ class FileWatcher extends EventEmitter {
                     break;
 
                 case 'delete':
-                    fs.unlinkSync(event.path);
-                    this._stats.filesActioned++;
-                    this.emit('action', {
-                        action: 'delete',
-                        source: event.path,
-                        rule
-                    });
+                    // Trash-based (v4.0.9): journaled and reversible with undo.
+                    this._getFmfs().delete(event.path)
+                        .then(() => {
+                            this._stats.filesActioned++;
+                            this.emit('action', {
+                                action: 'delete',
+                                source: event.path,
+                                rule
+                            });
+                        })
+                        .catch((err) => {
+                            this._stats.errors++;
+                            this.emit('error', { action: 'delete', path: event.path, error: err.message, rule });
+                        });
                     break;
 
                 case 'log':

package/index.js

@@ -178,10 +178,10 @@ ${banner()}
     ${c('cyan', 'filemayor')} ${c('yellow', '<command>')} ${c('dim', '[path]')} ${c('dim', '[options]')}
 
     ${c('yellow', 'explain')}    ${c('dim', '<path>')}    Diagnose folder health
-    ${c('yellow', 'cure')}       ${c('dim', '<path>')}    Plan treatment using AI
+    ${c('yellow', 'cure')}       ${c('dim', '<path>')}    Plan treatment using AI (--para for PARA buckets)
     ${c('yellow', 'apply')}                Execute the cure plan
-    ${c('yellow', 'duplicates')} ${c('dim', '<path>')}    Find duplicate files
-    ${c('yellow', 'dedupe')}     ${c('dim', '<path>')}    Remove duplicate files
+    ${c('yellow', 'duplicates')} ${c('dim', '<path>')}    Find duplicates (content-hash)
+    ${c('yellow', 'dedupe')}     ${c('dim', '<path>')}    Trash duplicates (reversible with undo)
 
   ${c('bold', 'COMMANDS')}
     ${c('yellow', 'scan')}      ${c('dim', '<path>')}    Scan directory and report contents
@@ -189,9 +189,9 @@ ${banner()}
     ${c('yellow', 'organize')}  ${c('dim', '<path>')}    Organize files into categories
     ${c('yellow', 'para')}      ${c('dim', '<path>')}    Sort by actionability — PARA method (then apply)
     ${c('yellow', 'clean')}     ${c('dim', '<path>')}    Find and remove junk files
-    ${c('yellow', 'watch')}     ${c('dim', '<path>')}    Watch directory for changes
+    ${c('yellow', 'watch')}     ${c('dim', '<path>')}    Watch directory (--para: auto-route new files)
     ${c('yellow', 'init')}     ${c('dim', '[--para]')}   Create .filemayor.yml (--para scaffolds PARA folders)
-    ${c('yellow', 'undo')}      ${c('dim', '<path>')}    Undo last organization
+    ${c('yellow', 'undo')}                Undo last session (--list · --session <id> · --all)
     ${c('yellow', 'info')}                System info and version
     ${c('yellow', 'license')}  ${c('dim', '<action>')}  Manage license (activate|status|deactivate)
 
@@ -382,7 +382,7 @@ async function cmdClean(target, flags, config) {
     if (format === 'table' && !flags.quiet) spinner.start();
 
     try {
-        const result = clean(targetPath, {
+        const result = await clean(targetPath, {
             dryRun,
             categories: flags.category || config.clean.categories,
             maxDepth: flags.depth || config.clean.maxDepth,
@@ -424,8 +424,14 @@ async function cmdWatch(target, flags, config) {
             naming: config.organize.naming,
             duplicateStrategy: config.organize.duplicates,
         },
+        paraMode: !!flags.para,
+        paraConfig: config.para || {},
     });
 
+    if (flags.para) {
+        console.log(info('PARA mode: new files route to Projects / Areas / Resources / Archives (journaled — undo works).'));
+    }
+
     watcher.on('watching', (data) => {
         console.log(success(`Watching: ${data.directory}`));
     });
@@ -540,23 +546,50 @@ async function cmdPara(target, flags, config) {
 }
 
 async function cmdUndo(target, flags) {
-    const { JOURNAL_PATH, rollback: fsRollback } = require('./core/fs-abstraction');
+    const { JOURNAL_PATH, rollback: fsRollback, listSessions } = require('./core/fs-abstraction');
 
     if (!fs.existsSync(JOURNAL_PATH)) {
         console.log(info('No operations to undo (journal is empty)'));
         return;
     }
 
-    const spinner = new Spinner('Undoing operations...');
+    // undo --list: show the undoable session history, newest first.
+    if (flags.list) {
+        const sessions = listSessions(JOURNAL_PATH);
+        if (sessions.length === 0) {
+            console.log(info('No undoable sessions — the journal has nothing left to reverse.'));
+            return;
+        }
+        console.log(c('bold', '\n  UNDO HISTORY') + c('dim', ` — ${sessions.length} session${sessions.length === 1 ? '' : 's'}\n`));
+        for (const s of sessions) {
+            const when = s.end.replace('T', ' ').slice(0, 19);
+            const parts = [];
+            if (s.moves) parts.push(`${s.moves} move${s.moves === 1 ? '' : 's'}`);
+            if (s.deletes) parts.push(`${s.deletes} delete${s.deletes === 1 ? '' : 's'}`);
+            console.log(`  ${c('cyan', s.sessionId.padEnd(10))} ${c('dim', when)}  ${parts.join(', ')}`);
+        }
+        console.log(c('dim', "\n  Reverse one:  filemayor undo --session <id>"));
+        console.log(c('dim', '  Reverse all:  filemayor undo --all\n'));
+        return;
+    }
+
+    const scope = flags.session
+        ? `session ${flags.session}`
+        : flags.all ? 'all sessions' : 'the most recent session';
+    const spinner = new Spinner(`Undoing ${scope}...`);
     spinner.start();
 
     try {
-        const result = await fsRollback(JOURNAL_PATH);
+        const result = await fsRollback(JOURNAL_PATH, {
+            all: !!flags.all,
+            sessionId: typeof flags.session === 'string' ? flags.session : undefined,
+        });
         spinner.stop();
         if (result.count === 0) {
             console.log(info('Nothing to undo — no completed operations found in the journal'));
         } else {
-            console.log(success(`Undone ${result.count} operation${result.count === 1 ? '' : 's'}`));
+            const which = result.sessionId && !flags.all ? c('dim', ` (session ${result.sessionId})`) : '';
+            console.log(success(`Undone ${result.count} operation${result.count === 1 ? '' : 's'}`) + which);
         }
     } catch (err) {
         spinner.fail(err.message);
@@ -586,18 +619,33 @@ async function cmdExplain(target, flags) {
 
 async function cmdCure(target, flags) {
     const targetPath = path.resolve(target || '.');
-    const prompt = flags.prompt || 'Clean up this folder and group similar files.';
-    
-    if (!process.env.GEMINI_API_KEY) {
-        console.log(error('GEMINI_API_KEY environment variable is required for AI curative features.'));
-        process.exit(1);
+    const prompt = flags.prompt || (flags.para
+        ? 'Sort this folder by actionability using the PARA method (Projects, Areas, Resources, Archives).'
+        : 'Clean up this folder and group similar files.');
+
+    // Multi-provider (v4.0.9): first key present wins — Anthropic, Gemini,
+    // then OpenAI. With no key at all, the core planner falls back to the
+    // free FileMayor proxy, so there is nothing to hard-fail on here.
+    const providers = [
+        ['ANTHROPIC_API_KEY', 'anthropic'],
+        ['GEMINI_API_KEY', 'gemini'],
+        ['OPENAI_API_KEY', 'openai'],
+    ];
+    let apiKey = '';
+    for (const [envVar, provider] of providers) {
+        if (process.env[envVar]) {
+            process.env.FM_AI_PROVIDER = provider;
+            process.env.FM_AI_API_KEY = process.env[envVar];
+            apiKey = process.env[envVar];
+            break;
+        }
     }
 
     const spinner = new Spinner(`Consulting AI for ${c('cyan', targetPath)}...`);
     spinner.start();
 
     try {
-        const engine = new CureEngine(targetPath, process.env.GEMINI_API_KEY);
+        const engine = new CureEngine(targetPath, apiKey);
         activePlanState = await engine.generatePlan(prompt);
         spinner.stop();
         
@@ -679,7 +727,7 @@ async function cmdDuplicates(target, flags) {
 
     try {
         const engine = new DedupeEngine();
-        const result = engine.find(targetPath);
+        const result = await engine.find(targetPath);
         spinner.stop();
         console.log(reporter.formatDedupeReport(result));
     } catch (err) {
@@ -695,14 +743,15 @@ async function cmdDedupe(target, flags) {
 
     try {
         const engine = new DedupeEngine();
-        const report = engine.find(targetPath);
+        const report = await engine.find(targetPath);
         if (report.sets === 0) {
             spinner.succeed('Total order restored: No duplicates found.');
             return;
         }
 
         const result = await engine.clean(report);
-        spinner.succeed(`Purged ${result.deleted} duplicates. Reclaimed ${result.freedHuman}.`);
+        spinner.succeed(`Trashed ${result.deleted} duplicates. Reclaimed ${result.freedHuman}.`);
+        console.log(c('dim', `  Recoverable: files moved to FileMayor trash — 'filemayor undo' restores them.`));
     } catch (err) {
         spinner.fail(err.message);
         process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "filemayor",
-    "version": "4.0.8",
+    "version": "4.0.9",
     "description": "FileMayor — Your intelligent filesystem clerk. CLI + Desktop + PWA.",
     "main": "index.js",
     "bin": {