proton-drive-mcp 1.3.2 → 1.4.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 1.4.0 — 2026-10-01
+
+### Added
+- **Persistent search index (opt-in).** Every new server process used to walk the whole drive again on its first `drive_search`, `drive_tree`, `drive_usage` or `drive_find_duplicates` (about 30 s for 1,200 files, minutes on big drives). With `PROTON_DRIVE_INDEX=1` (or the **Persistent search index** switch in the MCPB bundle) the last complete walk is saved to disk and a new process answers in about 1.5 s with `stale: true` while a background walk refreshes it. Verified on a real 1,222-file drive: cold 31–34 s, next process 1.3–2.1 s.
+  - **Privacy:** the index is a plaintext copy of file and folder names, paths, sizes, dates and claimed sha1 hashes of your end-to-end-encrypted drive, so it is off by default. It lives in a private directory (`~/Library/Caches/proton-drive-mcp` on macOS, `~/.cache/proton-drive-mcp` on Linux, or `PROTON_DRIVE_INDEX_DIR`), file mode 0600, written atomically; symlinks, foreign owners and loose permissions are refused, and a pre-existing directory is never taken over. `proton-drive-cli index status` and `index clear` inspect and remove it.
+  - **Safety:** before saved data is served, one `list /my-files` confirms it belongs to the logged-in account (a failed check serves nothing; a mismatch deletes the file); data older than `PROTON_DRIVE_INDEX_MAX_AGE_H` (default 24) is ignored; the server's own writes (upload, move, trash, ...) remove the affected entries from memory and disk, and an index that cannot be kept current (read-only directory) is not served. `drive_sync_plan`, `drive_find_duplicates` and `drive_sharing_audit` never use saved data.
+  - Results served from the index carry `stale: true` (and `refreshing: true` while a refresh runs); `refresh: true` always walks.
+
+### Known limitations
+- `drive_tree` with a depth limit is not answered from the saved full walk, and changes made by other clients or processes are not seen until the saved data is refreshed. The refresh cooldown after a failed background walk is per server process.
+
+## 1.3.3 — 2026-10-01
+
+### Fixed
+- `drive_find_duplicates` with `verify`: on a real 1,125-file drive about half of the verification downloads failed with `database is locked` (the CLI's SQLite cache, hit by 4 parallel downloads) and left groups unverified. Verification now retries that error in a fresh temp dir (max 4 attempts), runs 2 downloads at a time by default, and failure notes are a single line instead of a SQLite dump. Re-run on the same drive: 30 of 30 groups verified, no lock errors.
+
 ## 1.3.2 — 2026-10-01
 
 ### Changed

package/README.md

@@ -108,7 +108,7 @@ Restart Claude Desktop. Check **`+` → Connectors → proton-drive-mcp** to con
 
 ### One-click install (MCPB bundle)
 
-Instead of editing JSON, download `proton-drive-mcp-<version>.mcpb` from the [latest GitHub release](https://github.com/googlarz/proton-drive-mcp/releases/latest) and open it (or drag it into **Settings → Extensions** in Claude Desktop). In the extension settings, set **proton-drive CLI path** to the output of `which proton-drive` (usually `~/.local/bin/proton-drive`); optionally set the **Proton Drive sync folder** to enable `drive_read_file` / `drive_write_file`. You still need the official `proton-drive` CLI installed and `proton-drive auth login` done once.
+Instead of editing JSON, download `proton-drive-mcp-<version>.mcpb` from the [latest GitHub release](https://github.com/googlarz/proton-drive-mcp/releases/latest) and open it (or drag it into **Settings → Extensions** in Claude Desktop). In the extension settings, set **proton-drive CLI path** to the output of `which proton-drive` (usually `~/.local/bin/proton-drive`); optionally set the **Proton Drive sync folder** to enable `drive_read_file` / `drive_write_file`, and the **Persistent search index** switch (off by default; it stores file names in plain text on this computer, see [Persistent index](#persistent-index-opt-in)). You still need the official `proton-drive` CLI installed and `proton-drive auth login` done once.
 
 ### If installed globally
 
@@ -241,16 +241,33 @@ proton-drive-cli share audit /my-files
 proton-drive-cli sync-plan ./local /my-files/backup --direction up
 proton-drive-cli bulk-move /my-files/Archive /my-files/a.pdf /my-files/b.pdf          # plan only
 proton-drive-cli bulk-trash /my-files/old1.txt /my-files/old2.txt --confirm           # apply
+proton-drive-cli index status                                                         # persistent index: enabled?, path, size, age, entries
+proton-drive-cli index clear                                                          # delete the saved index file
 ```
 
-- The first walk of a large drive can take minutes (measured ~25 s per 1,200 files at concurrency 8). Later calls reuse a 5-minute cache; `refresh` bypasses it.
+- The first walk of a large drive can take minutes (measured ~25 s per 1,200 files at concurrency 8). Later calls reuse a 5-minute in-memory cache; `refresh` bypasses it. With the opt-in persistent index, a saved copy up to 24 h old can answer first (marked `stale: true`).
 - Walks skip `.git` and `node_modules` by default.
+- With `PROTON_DRIVE_INDEX=1`, results may come from a saved index (`stale: true` = served from the saved index, not a walk made now) while a refresh runs; repeat the call or pass `refresh: true` for a fresh read. Off by default, see [Persistent index](#persistent-index-opt-in).
 - Read-only tools (`drive_search`, `drive_tree`, `drive_usage`, `drive_find_duplicates`, `drive_sharing_audit`, `drive_sync_plan`) change nothing. `drive_bulk_move` and `drive_bulk_trash` are two-step: call without `confirmed` for the plan, then with `confirmed: true` to apply. Bulk trash is reversible with `drive_restore`.
 - Duplicate detection uses the sha1 the uploader claimed, which is unverified. `verify: true` downloads the candidates and hashes them.
 - The sharing audit flags an invitee as external when the address is outside Proton domains, so Proton users on a custom domain are over-flagged.
 - Sizes are sums of file sizes, not your account quota.
 - `drive_usage` trash stats always make one uncached `/trash` listing (~2.5 s), even when the walk is cached.
 
+### Persistent index (opt-in)
+
+By default every new server process (each Claude Desktop session) walks the drive again on the first `drive_search`, `drive_tree`, `drive_usage` or `drive_find_duplicates`: about 25 s per 1,200 files, minutes on big drives. Set `PROTON_DRIVE_INDEX=1` to keep completed walks on disk and answer instantly after a restart.
+
+**Privacy: this is off by default.** Your Drive is end-to-end encrypted, but the index is a **plaintext** copy of file and folder names, paths, sizes, dates and claimed sha1 hashes on your local disk. Anyone who can read your user account's files (or your backups) can read it. Enable it only on a machine you trust.
+
+- **What is stored:** the node list of up to 8 recent complete walks under `/my-files` (partial or failed walks are never saved, so a `drive_tree` that stops at its depth limit is not stored), plus a fingerprint of your account's Drive root. No file contents, no credentials, no tokens.
+- **Where:** `PROTON_DRIVE_INDEX_DIR` if set; otherwise `~/Library/Caches/proton-drive-mcp` (macOS) or `$XDG_CACHE_HOME/proton-drive-mcp` / `~/.cache/proton-drive-mcp` (Linux). One file, `walk-index.json`, mode `0600` in a `0700` directory, written atomically. Use a dedicated directory: a pre-existing directory with group/other access (or owned by someone else) is refused with one warning and never chmodded; a missing one is created `0700`. A symlinked directory or file is refused. A saved file with loose permissions, another owner, a future timestamp, or above 200 MB is ignored. Not written above 200 MB.
+- **Account check:** before any saved data is served, one `list /my-files` (~2 s) confirms it belongs to the account that is logged in now; if the check fails (network, rate limit) nothing is served from disk for that call and the file is kept; a proven account mismatch deletes it. Either way the drive is walked fresh.
+- **Freshness:** data up to `PROTON_DRIVE_INDEX_MAX_AGE_H` hours old (default 24; `0` = never use saved data) is returned immediately with `stale: true` (and `refreshing: true` while one background walk replaces it); a repeated call then returns the fresh walk. A failed or incomplete background walk is not retried for 5 minutes within the same server process (`PROTON_DRIVE_INDEX_REFRESH_COOLDOWN_MS`); a new process tries once again. Saved data is first checked against the live account with one `list /my-files`; if that check fails (network, rate limit) nothing is served from disk for that call and the file is kept, and only a proven account mismatch deletes it. `drive_sync_plan`, `drive_find_duplicates` and the sharing audit never use saved data. `refresh: true` always does a blocking fresh walk. Writes made through this server drop the affected entries from memory and disk.
+- **Read-only directory:** an index in a directory (or file) you cannot write to is ignored, because it could not be kept current after the server's own writes.
+- **Limits:** `drive_tree` with a depth limit is not answered from the saved full walk (it walks live); changes made by other clients or processes are not seen until the data is refreshed.
+- **Check or remove it:** `proton-drive-cli index status` and `proton-drive-cli index clear` (or just delete the file). In the MCPB bundle, the **Persistent search index** setting is the opt-in.
+
 ### Photos
 
 ```bash
@@ -396,14 +413,14 @@ The server offers four MCP prompts (also declared in the MCPB manifest): `organi
 - `drive_move` accepts a full destination path (parent + new name) for a familiar interface, but the underlying CLI only has separate `move` (change parent) and `rename` (change name) commands — this MCP translates automatically, issuing one or both as needed.
 - `drive_delete` only works on items already in `/trash` or `/photos-trash` — the CLI rejects live paths. Trash an item first with `drive_trash`, or use `drive_empty_trash` to clear everything at once.
 - If the client declares MCP elicitation (form mode), a refused `confirmed` gate is put to the human instead, and `drive_bulk_move` / `drive_bulk_trash` ask before applying a `confirmed: true` call. Only an explicit approval runs the call; decline, cancel, timeout or error keep the refusal, and after 5 declined prompts in a minute the server stops prompting. This only upgrades refusals and bulk applies: a compromised model that supplies `confirmed: true` on any other tool is **not** stopped by it. Clients without elicitation behave as before. Confirmation prompts need a client that supports elicitation (Claude Code CLI today; Claude Desktop is unverified).
-- Walk-based tools (`drive_tree`, `drive_search`, `drive_usage`, `drive_find_duplicates`) read from a cache up to 5 minutes old; changes made by other clients or processes are not seen until it expires or you pass `refresh: true`. The first walk of a large drive can take minutes (measured about 25 s per 1200 files at concurrency 8).
+- Walk-based tools (`drive_tree`, `drive_search`, `drive_usage`, `drive_find_duplicates`) read from a cache up to 5 minutes old (with the opt-in persistent index, up to 24 h old and marked `stale: true`; `drive_sharing_audit`, `drive_sync_plan` and `drive_find_duplicates` never use the saved index); changes made by other clients or processes are not seen until it expires or you pass `refresh: true`. The first walk of a large drive can take minutes (measured about 25 s per 1200 files at concurrency 8).
 - `drive_auth_status` has no native CLI equivalent — it probes by resolving `/my-files` and reports authenticated based on whether that succeeds.
 - Paths are always Drive-absolute: `/my-files/folder/file.pdf`. Relative paths are not supported.
 - All calls include `--json` automatically, except `drive_version`, whose underlying CLI command ignores `--json` and always prints plain text — this MCP parses it directly.
 
 ### Token cost
 
-`tools/list` is sent to the model in every session. Measured payload (JSON bytes): `full` 39.0 KB (46 tools), `core` 16.8 KB (18 tools). Set `PROTON_DRIVE_TOOL_TIER=core` to load only:
+`tools/list` is sent to the model in every session. Measured payload (JSON bytes): `full` 39.2 KB (46 tools), `core` 17.0 KB (18 tools). Set `PROTON_DRIVE_TOOL_TIER=core` to load only:
 
 `drive_auth_status`, `drive_version`, `drive_list`, `drive_info`, `drive_list_trash`, `drive_search`, `drive_tree`, `drive_mkdir`, `drive_upload`, `drive_download`, `drive_rename`, `drive_move`, `drive_copy`, `drive_trash`, `drive_restore`, `drive_share_status`, `photos_list_timeline`, `photos_download`.
 
@@ -446,6 +463,9 @@ Every tool group was live-tested on 2026-09-28 against a real Proton account, **
 | `CLAUDE_DESKTOP_CONFIG` | Optional | Path of the Claude Desktop config that `doctor` and `setup-claude-desktop` read/write instead of the per-OS default. |
 | `PROTON_DRIVE_RETRY_BASE_MS` | Optional | Test hook: base backoff in ms for retrying read-only calls (default 250). |
 | `PROTON_DRIVE_WALK_TTL_MS` | Optional | How long `drive_tree`/`drive_search` reuse a cached folder walk, in ms (default 300000; 0 disables the cache). Results can be up to this old, and changes made by other clients or processes are not seen until it expires or `refresh: true`. The first walk of a large drive can take minutes. The cache is dropped for any path this server writes to. |
+| `PROTON_DRIVE_INDEX` | Optional | Set to `1` (or `true`) to keep completed folder walks in a **plaintext** on-disk index so searches are fast after a restart. Off by default. See [Persistent index](#persistent-index-opt-in). |
+| `PROTON_DRIVE_INDEX_DIR` | Optional | Directory for the index file (default: `~/Library/Caches/proton-drive-mcp` on macOS, `$XDG_CACHE_HOME` or `~/.cache/proton-drive-mcp` elsewhere). Use a dedicated directory: if it exists it must be yours with mode `0700` (group/other access is refused); a missing one is created `0700`. The file is `0600`. |
+| `PROTON_DRIVE_INDEX_MAX_AGE_H` | Optional | Oldest saved index data that may be served, in hours (default 24; 0 = never serve saved data). Served data is marked `stale: true` and refreshed in the background (`drive_sync_plan`, `drive_find_duplicates` and the sharing audit never use it). |
 | `PROTON_DRIVE_TOOL_TIER` | Optional | `full` (default, all 46 tools) or `core` (18 everyday tools; see [Token cost](#token-cost)). Tools outside the active tier are hidden from `tools/list` and refused at call time. Read once at startup; an unknown value falls back to `full` with a warning on stderr. |
 
 ---

package/dist/cli.js

@@ -13,6 +13,7 @@ import { runDoctor, formatDoctor } from "./utils/doctor.js";
 import { buildEntry, defaultConfigPath, isDirectory, resolveDriveCli, writeEntry, SERVER_KEY } from "./utils/claudeConfig.js";
 import { syncPlan, planBulkMove, planBulkTrash, loadListing, foldersToList } from "./services/plan.js";
 import { invalidatePath } from "./services/walk.js";
+import { indexStatus, deleteIndex } from "./services/walkIndex.js";
 import { resolve } from "node:path";
 import { driveSearch, driveTree } from "./services/find.js";
 import { driveUsage, driveFindDuplicates, driveSharingAudit } from "./services/analytics.js";
@@ -81,6 +82,9 @@ Commands:
   photo download <photo>... <local> [--conflict X] [--confirm]  Download photos (skip/rename/remove; 'remove' needs --confirm)
   photo upload <local>... [--conflict X]   Upload photos to your library (skip/rename)
 
+  index status                             Persistent walk index (PROTON_DRIVE_INDEX=1): enabled?, path, size, age, entries
+  index clear                              Delete the saved index file (it holds plaintext names/paths of your drive)
+
   doctor [--config <path>]                 Read-only diagnostics: Node, proton-drive CLI, auth, sync path, Claude Desktop config
                                            (exit 1 if any check fails)
   setup-claude-desktop [--config <path>] [--sync-path <dir>] [--write]
@@ -201,6 +205,18 @@ async function run() {
         setupClaudeDesktop();
         return;
     }
+    // Local file only: no account, no CLI binary needed.
+    if (cmd === "index") {
+        if (sub === "status")
+            print(indexStatus());
+        else if (sub === "clear")
+            print(deleteIndex());
+        else {
+            console.error("Usage: index status|clear");
+            process.exit(1);
+        }
+        return;
+    }
     const cliCheck = await checkCliAvailable();
     if (!cliCheck.available) {
         const msg = cliCheck.reason === "not_executable"

package/dist/index.js

@@ -12,7 +12,7 @@ import { validateRemotePath, validateRemotePathList, validateLocalPath, validate
 import { logger } from "./utils/logger.js";
 import { driveSearch, driveTree } from "./services/find.js";
 import { syncPlan, planBulkMove, planBulkTrash, loadListing, foldersToList } from "./services/plan.js";
-import { invalidatePath } from "./services/walk.js";
+import { invalidatePath, abortBackgroundRefreshes } from "./services/walk.js";
 import { getSyncRoot, readSyncFile, writeSyncFile, syncFileExists } from "./utils/syncfs.js";
 import { driveUsage, driveFindDuplicates, driveSharingAudit } from "./services/analytics.js";
 const require = createRequire(import.meta.url);
@@ -195,7 +195,7 @@ const TOOLS = [
     },
     {
         name: "drive_search",
-        description: "Find files/folders under a path by name, type, extension, size or date in one walk. Filters are ANDed. Returns {total, hasMore, items [{path, type, size?, mtime?, sha1?}], walk {complete, fromCache, skipped?}}; walk.complete=false means matches may be missing. Cached 5 min; refresh=true re-reads; skips .git/node_modules.",
+        description: "Find files/folders under a path by name, type, extension, size or date in one walk. Filters are ANDed. Returns {total, hasMore, items [{path, type, size?, mtime?, sha1?}], walk {complete, fromCache, skipped?}}; walk.complete=false means matches may be missing. Cached 5 min; refresh=true re-reads; skips .git/node_modules. With PROTON_DRIVE_INDEX=1 a saved index may answer first (stale:true); repeat the call or pass refresh:true.",
         annotations: { readOnlyHint: true, idempotentHint: true },
         inputSchema: {
             type: "object",
@@ -1558,10 +1558,11 @@ export async function main() {
         }
     });
     const shutdown = (code) => {
+        abortBackgroundRefreshes();
         killAllChildren();
         process.exit(code);
     };
-    server.onclose = () => killAllChildren();
+    server.onclose = () => { abortBackgroundRefreshes(); killAllChildren(); };
     process.once("SIGTERM", () => shutdown(0));
     process.once("SIGINT", () => shutdown(0));
     process.stdout.on("error", (e) => { if (e.code === "EPIPE")

package/dist/services/analytics.js

@@ -3,7 +3,7 @@ import { createReadStream } from "node:fs";
 import { mkdtemp, readdir, rm, stat } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { walkTree } from "./walk.js";
+import { walkTree, staleFields } from "./walk.js";
 import { validateLocalPath } from "../utils/validation.js";
 import { callContext } from "../utils/subprocess.js";
 const DAY_MS = 86_400_000;
@@ -35,7 +35,7 @@ function breakdown(nodes, key, top) {
     return topBy([...m].map(([k, v]) => ({ key: k, ...v })), top, (r) => r.key);
 }
 function walkMeta(w) {
-    return { complete: w.complete, skippedCount: w.skipped.length, skipped: w.skipped.slice(0, 10), fromCache: w.fromCache };
+    return { complete: w.complete, skippedCount: w.skipped.length, skipped: w.skipped.slice(0, 10), fromCache: w.fromCache, ...staleFields(w) };
 }
 // ---- drive_usage ----------------------------------------------------------
 export function summarizeTrash(items) {
@@ -163,14 +163,14 @@ export async function verifyGroups(groups, hash, o) {
         totalMembers += g.members.length;
         const digests = new Map();
         const failed = [];
-        await pool(g.members, o.concurrency ?? 4, async (m) => {
+        await pool(g.members, o.concurrency ?? 2, async (m) => {
             if (o.signal?.aborted)
                 return;
             try {
                 digests.set(m, await hash(m));
             }
             catch (e) {
-                failed.push(`${m.path}: ${e instanceof Error ? e.message : String(e)}`);
+                failed.push(`${m.path}: ${oneLine(e instanceof Error ? e.message : String(e))}`);
             }
         });
         stop(); // the hasher's own finally already removed any temp dir
@@ -187,9 +187,16 @@ export async function verifyGroups(groups, hash, o) {
     }
     return out.filter((g) => g.members.length > 1).sort((a, b) => wasted(b) - wasted(a) || (a.members[0].path < b.members[0].path ? -1 : 1));
 }
-/** Downloads one file into its own private temp dir, sha256s it, and always removes the dir. */
+const LOCKED_RE = /database is locked|SQLITE_BUSY/i;
+const oneLine = (m) => (m.split("\n")[0] ?? m).slice(0, 160);
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * Downloads one file into its own private temp dir, sha256s it, and always removes the dir.
+ * The CLI's SQLite cache can report "database is locked" at startup when several downloads run
+ * at once; nothing has been transferred then, so a fresh attempt is safe (max 4 tries).
+ */
 export function makeDriveHasher(drive) {
-    return async (node) => {
+    const once = async (node) => {
         const dir = await mkdtemp(join(tmpdir(), "pdmcp-dup-"));
         try {
             validateLocalPath(dir); // same local-path rules as drive_download
@@ -208,6 +215,20 @@ export function makeDriveHasher(drive) {
             await rm(dir, { recursive: true, force: true });
         }
     };
+    return async (node) => {
+        const base = Number(process.env["PROTON_DRIVE_RETRY_BASE_MS"] ?? 250);
+        for (let attempt = 1;; attempt++) {
+            try {
+                return await once(node);
+            }
+            catch (e) {
+                const msg = e instanceof Error ? e.message : String(e);
+                if (attempt >= 4 || !LOCKED_RE.test(msg))
+                    throw e;
+                await sleep(base * attempt + Math.random() * base);
+            }
+        }
+    };
 }
 function reportGroup(g) {
     const keeper = keeperOf(g.members);
@@ -224,7 +245,7 @@ export async function driveFindDuplicates(drive, o, deps = {}) {
     if (o.maxVerifyTotalBytes !== undefined && (!Number.isInteger(o.maxVerifyTotalBytes) || o.maxVerifyTotalBytes < 1 || o.maxVerifyTotalBytes > MAX_VERIFY_TOTAL_BYTES)) {
         throw new Error(`maxVerifyTotalBytes must be an integer between 1 and ${MAX_VERIFY_TOTAL_BYTES}`);
     }
-    const walk = await (deps.walk ?? walkTree)(drive, o.path, { refresh: o.refresh });
+    const walk = await (deps.walk ?? walkTree)(drive, o.path, { refresh: o.refresh, noDisk: true }); // deletion suggestions must come from a current walk
     const limit = o.limit ?? 20;
     let groups = findDuplicateCandidates(walk.nodes, o.minSize ?? 1024);
     let verified = false;
@@ -271,7 +292,7 @@ export function auditShareStatus(path, s) {
     return { path, publicLink, invitees, pending, flags };
 }
 export async function driveSharingAudit(drive, o, deps = {}) {
-    const walk = await (deps.walk ?? walkTree)(drive, o.path, { refresh: o.refresh });
+    const walk = await (deps.walk ?? walkTree)(drive, o.path, { refresh: o.refresh, noDisk: true }); // a security audit must not read a saved index
     const status = deps.status ?? ((p) => drive.shareStatus(p));
     const shared = walk.nodes.filter((n) => (n.isShared || n.isSharedByUrl) && parentOf(n.path) !== "");
     const targets = shared.slice(0, SHARE_AUDIT_CAP);

package/dist/services/find.js

@@ -1,4 +1,4 @@
-import { baseName, depthOf, parentPath, DEFAULT_EXCLUDE, walkTree } from "./walk.js";
+import { baseName, depthOf, parentPath, DEFAULT_EXCLUDE, walkTree, staleFields } from "./walk.js";
 import { validateRemotePath } from "../utils/validation.js";
 import { globMatch } from "../utils/glob.js";
 // Argument handling shared by the drive_tree / drive_search tools and the CLI.
@@ -56,7 +56,7 @@ function root(a) {
 }
 function walkInfo(w, scanned, scanCapped) {
     return {
-        complete: w.complete, fromCache: w.fromCache, ageMs: w.ageMs, callsMade: w.callsMade, scanned,
+        complete: w.complete, fromCache: w.fromCache, ...staleFields(w), ageMs: w.ageMs, callsMade: w.callsMade, scanned,
         ...(scanCapped ? { scanCapped: true } : {}),
         ...(w.skipped.length ? { skippedCount: w.skipped.length, skipped: w.skipped.slice(0, SKIPPED_SHOWN) } : {}),
     };
@@ -201,7 +201,7 @@ export async function driveTree(svc, a) {
         complete: w.skipped.length === 0,
         ...(unexpandedCount ? { unexpanded: unexpandedCount } : {}),
         ...(w.skipped.length ? { skippedCount: w.skipped.length, skipped: w.skipped.slice(0, SKIPPED_SHOWN) } : {}),
-        fromCache: w.fromCache, ageMs: w.ageMs, callsMade: w.callsMade,
+        fromCache: w.fromCache, ...staleFields(w), ageMs: w.ageMs, callsMade: w.callsMade,
         tree: top.children ?? [], ...(top.more ? { more: top.more } : {}),
     };
 }

package/dist/services/plan.js

@@ -2,7 +2,7 @@ import { createHash } from "node:crypto";
 import { createReadStream, lstatSync, readdirSync, statSync } from "node:fs";
 import { join, relative, sep } from "node:path";
 import { ROOT_PATHS, splitRemotePath, joinRemote } from "./drive.js";
-import { walkTree } from "./walk.js";
+import { walkTree, staleFields } from "./walk.js";
 import { globMatch } from "../utils/glob.js";
 import { validateLocalPath, validateRemotePath } from "../utils/validation.js";
 import { isProtectedEntry } from "../utils/localguard.js";
@@ -135,7 +135,7 @@ export async function syncPlan(svc, a, walk = walkTree) {
     const limit = Math.max(1, Math.min(a.limit ?? 200, 1000));
     const patterns = a.ignore ?? DEFAULT_IGNORE;
     const ignore = makeIgnore(patterns);
-    const w = await walk(svc, driveRoot, { exclude: patterns.filter((p) => !/[*?/]/.test(p)) });
+    const w = await walk(svc, driveRoot, { exclude: patterns.filter((p) => !/[*?/]/.test(p)), noDisk: true }); // a plan must come from a current walk
     const scan = scanLocal(localRoot, ignore);
     const diff = await diffTrees(scan.files, w, { compare, ignore, hashLocal: (rel) => sha1File(join(localRoot, ...rel.split("/"))) });
     const cap = (xs) => xs.slice(0, limit);
@@ -151,6 +151,7 @@ export async function syncPlan(svc, a, walk = walkTree) {
         listsTruncated: [diff.onlyLocal, diff.onlyDrive, diff.changed].some((l) => l.length > limit),
         complete: w.complete && !scan.truncated,
         driveWalkComplete: w.complete,
+        ...staleFields(w),
         skipped: cap(w.skipped),
         local: { scanned: scan.scanned, symlinksSkipped: scan.symlinksSkipped, unreadable: scan.unreadable, protectedSkipped: scan.protectedSkipped, truncated: scan.truncated, maxEntries: MAX_LOCAL_ENTRIES },
         note: "Plan only. onlyLocal = not on Drive, onlyDrive = not local; 'maybe changed' compares mtime (Drive claimed time) and can be a false positive." +

package/dist/services/walk.js

@@ -1,5 +1,9 @@
 import { DriveNotAuthenticatedError } from "../utils/errors.js";
 import { callContext } from "../utils/subprocess.js";
+import { logger } from "../utils/logger.js";
+import { indexEnabled, indexMaxAgeMs, readIndex, writeIndex, deleteIndex, INDEX_VERSION, MAX_ENTRIES } from "./walkIndex.js";
+/** Output fields for results served from the persistent index while a refresh runs (empty otherwise). */
+export const staleFields = (w) => w.stale ? { stale: true, ...(w.refreshing ? { refreshing: true } : {}) } : {};
 export const DEFAULT_EXCLUDE = [".git", "node_modules"];
 const DEFAULT_MAX_CALLS = 300;
 const MAX_CONCURRENCY = 12; // the CLI's SQLite cache starts failing above this
@@ -58,16 +62,11 @@ function fromCache(entry, root, maxDepth, exclude, exact) {
         callsMade: 0, fromCache: true, ageMs: Date.now() - entry.createdAt,
     };
 }
-function lookup(root, maxDepth, key, excludeKey, exclude) {
-    const now = Date.now(), ttl = ttlMs();
+function pick(entries, root, maxDepth, key, excludeKey, exclude) {
     let best;
-    for (const [k, e] of cache) {
-        if (now - e.createdAt >= ttl) {
-            cache.delete(k);
-            continue;
-        }
+    for (const e of entries) {
         if (e.key === key)
-            return fromCache(e, root, maxDepth, exclude, true); // same request, even if it was partial
+            return { e, exact: true }; // same request, even if it was partial
         // An ancestor's walk can answer a subfolder request if it saw everything and went deep enough.
         if (e.excludeKey !== excludeKey || e.skipped.length > 0 || !isUnder(root, e.root))
             continue;
@@ -83,32 +82,19 @@ function lookup(root, maxDepth, key, excludeKey, exclude) {
         if (!best || e.root.length > best.root.length)
             best = e;
     }
-    return best && fromCache(best, root, maxDepth, exclude, false);
+    return best && { e: best, exact: false };
 }
-/**
- * Breadth-first walk of a Drive folder with bounded parallelism. A folder that
- * still fails after one retry goes to `skipped` (its subtree is never dropped
- * silently); maxCalls/maxDepth cuts set `complete: false`. Results are cached
- * for PROTON_DRIVE_WALK_TTL_MS (default 5 min); a walk of a subfolder can be
- * served from a cached walk of an ancestor.
- */
-export async function walkTree(svc, rootPath, opts = {}) {
-    const root = normalizeRoot(rootPath);
-    const maxDepth = opts.maxDepth === undefined ? undefined : Math.max(1, Math.floor(opts.maxDepth));
-    const maxCalls = Math.max(1, Math.floor(opts.maxCalls ?? DEFAULT_MAX_CALLS));
-    const concurrency = Math.min(MAX_CONCURRENCY, Math.max(1, Math.floor(opts.concurrency ?? 8)));
-    const excludeList = [...new Set(opts.exclude ?? DEFAULT_EXCLUDE)].sort();
-    const exclude = new Set(excludeList);
-    const signal = opts.signal ?? callContext.getStore()?.signal;
-    if (signal?.aborted)
-        throw abortError(signal);
-    const excludeKey = excludeList.join("\0");
-    const key = [root, maxDepth ?? "", maxCalls, excludeKey].join("\0");
-    if (!opts.refresh) {
-        const hit = lookup(root, maxDepth, key, excludeKey, exclude);
-        if (hit)
-            return hit;
-    }
+function lookup(root, maxDepth, key, excludeKey, exclude) {
+    const now = Date.now(), ttl = ttlMs();
+    for (const [k, e] of cache)
+        if (now - e.createdAt >= ttl)
+            cache.delete(k);
+    const hit = pick(cache.values(), root, maxDepth, key, excludeKey, exclude);
+    return hit && fromCache(hit.e, root, maxDepth, exclude, hit.exact);
+}
+/** The actual breadth-first walk (no caching). */
+async function runWalk(svc, p, signal) {
+    const { root, maxDepth, maxCalls, concurrency, exclude } = p;
     const nodes = [];
     const skipped = [];
     const queue = [{ path: root, depth: 0 }];
@@ -193,17 +179,287 @@ export async function walkTree(svc, rootPath, opts = {}) {
     });
     nodes.sort(byPath);
     skipped.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
-    const complete = skipped.length === 0 && !isDepthCut(nodes, depthOf(root), maxDepth, exclude);
-    cache.delete(key);
-    cache.set(key, { root, key, excludeKey, maxDepth, createdAt: Date.now(), nodes, skipped, complete });
+    return { nodes, skipped, callsMade, complete: skipped.length === 0 && !isDepthCut(nodes, depthOf(root), maxDepth, exclude) };
+}
+function remember(p, w) {
+    cache.delete(p.key);
+    cache.set(p.key, { root: p.root, key: p.key, excludeKey: p.excludeKey, maxDepth: p.maxDepth, createdAt: Date.now(), nodes: w.nodes, skipped: w.skipped, complete: w.complete });
     while (cache.size > CACHE_ENTRIES)
         cache.delete(cache.keys().next().value);
-    return { root, nodes: nodes.slice(), complete, callsMade, skipped: skipped.slice(), fromCache: false, ageMs: 0 };
+}
+// ---- persistent index (opt-in, PROTON_DRIVE_INDEX=1) ------------------------
+// Disk data is only served after one `list /my-files` proves it belongs to the
+// current account, and is served stale-while-revalidate.
+const ACCOUNT_ROOT = "/my-files";
+/** undefined = not loaded yet, null = nothing usable on disk. */
+let disk;
+let diskVerified;
+const VERIFY_TTL_MS = 10 * 60_000;
+let shuttingDown = false;
+const refreshFailedAt = new Map();
+const cooldownMs = () => {
+    const v = Number(process.env.PROTON_DRIVE_INDEX_REFRESH_COOLDOWN_MS ?? 300_000);
+    return Number.isFinite(v) && v >= 0 ? v : 300_000;
+};
+let knownAccountKey;
+let persistChain = Promise.resolve();
+let invalidationSeq = 0;
+const refreshes = new Map();
+let exitHooked = false;
+/** The parentUid shared by the first-level children of /my-files identifies the account's Drive root. */
+function fingerprint(items) {
+    const ids = new Set(items.map((i) => i.parentUid));
+    const [only] = ids;
+    return ids.size === 1 && typeof only === "string" ? only : undefined;
+}
+function loadDisk() {
+    if (disk === undefined) {
+        const f = readIndex({ requireWritable: true });
+        disk = f ? { accountKey: f.accountKey, entries: f.entries } : null;
+    }
+    return disk;
+}
+function discardDisk() {
+    disk = null;
+    try {
+        deleteIndex();
+    }
+    catch { /* best effort */ }
+}
+/** Rejects with the caller's own abort reason without touching the shared promise. */
+function raceAbort(p, signal) {
+    if (!signal)
+        return p;
+    if (signal.aborted)
+        return Promise.reject(abortError(signal));
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(abortError(signal));
+        signal.addEventListener("abort", onAbort, { once: true });
+        p.then(resolve, reject).finally(() => signal.removeEventListener("abort", onAbort));
+    });
+}
+/**
+ * One `list /my-files` proves the saved data belongs to the live account. Only a
+ * successful comparison that differs deletes the file; any failure (network, rate
+ * limit, empty or unreadable listing) just serves nothing from disk this time and is
+ * not remembered. The check is shared by concurrent callers on its own signal, so one
+ * caller's abort cannot fail the others, and it is repeated after 10 minutes.
+ */
+async function verifyDisk(svc, signal) {
+    if (diskVerified && Date.now() - diskVerified.at > VERIFY_TTL_MS)
+        diskVerified = undefined;
+    if (!diskVerified) {
+        const ctl = new AbortController();
+        const promise = callContext.run({ signal: ctl.signal }, async () => {
+            try {
+                const current = fingerprint((await svc.listEntries(ACCOUNT_ROOT)).map((e) => e.item));
+                if (!current)
+                    return "unknown";
+                knownAccountKey = current;
+                if (disk && disk.accountKey === current)
+                    return "match";
+                discardDisk();
+                return "mismatch";
+            }
+            catch {
+                return "unknown";
+            }
+        });
+        const rec = { at: Date.now(), ctl, promise };
+        diskVerified = rec;
+        void promise.then((v) => { if (v === "unknown" && diskVerified === rec)
+            diskVerified = undefined; });
+    }
+    return (await raceAbort(diskVerified.promise, signal)) === "match";
+}
+const toCacheEntry = (e) => ({
+    root: e.root, key: e.key, excludeKey: e.opts.exclude.join("\0"), maxDepth: e.opts.maxDepth,
+    createdAt: e.completedAt, nodes: e.nodes, skipped: [], complete: true,
+});
+function diskCandidates() {
+    const st = loadDisk();
+    const now = Date.now(), maxAge = indexMaxAgeMs();
+    return st ? st.entries.filter((e) => { const age = now - e.completedAt; return Number.isFinite(age) && age >= 0 && age <= maxAge; }).map(toCacheEntry) : [];
+}
+function persist(svc, p, w, startSeq) {
+    if (!indexEnabled() || !w.complete || !isUnder(p.root, ACCOUNT_ROOT))
+        return;
+    persistChain = persistChain.then(async () => {
+        try {
+            if (shuttingDown || invalidationSeq !== startSeq)
+                return; // a write happened mid-walk: do not save a possibly outdated tree
+            let acct = knownAccountKey ?? (p.root === ACCOUNT_ROOT ? fingerprint(w.nodes.filter((n) => depthOf(n.path) === 2)) : undefined);
+            if (!acct)
+                acct = fingerprint((await svc.listEntries(ACCOUNT_ROOT)).map((e) => e.item));
+            if (!acct || shuttingDown || invalidationSeq !== startSeq)
+                return;
+            knownAccountKey = acct;
+            const cur = loadDisk();
+            const base = cur && cur.accountKey === acct ? cur.entries : [];
+            const entry = { key: p.key, root: p.root, opts: { maxDepth: p.maxDepth, maxCalls: p.maxCalls, exclude: p.excludeList }, completedAt: Date.now(), nodes: w.nodes };
+            const entries = [entry, ...base.filter((e) => e.key !== p.key)].sort((a, b) => b.completedAt - a.completedAt).slice(0, MAX_ENTRIES);
+            const file = { version: INDEX_VERSION, accountKey: acct, savedAt: Date.now(), entries };
+            if (writeIndex(file) === "ok") {
+                disk = { accountKey: acct, entries };
+                diskVerified = { at: Date.now(), ctl: new AbortController(), promise: Promise.resolve("match") }; // saved under the live drive's own account key
+            }
+        }
+        catch (err) {
+            logger.warn("Persistent walk index not updated:", err instanceof Error ? err.message : String(err));
+        }
+    });
+}
+/** Stops background index refreshes (process shutdown). */
+export function abortBackgroundRefreshes() {
+    shuttingDown = true;
+    diskVerified?.ctl.abort(new Error("walk aborted"));
+    for (const r of refreshes.values())
+        r.controller.abort(new Error("walk aborted"));
+}
+/** True when a refresh is running (or was just started); false while a failed one cools down. */
+function startRefresh(svc, p) {
+    if (refreshes.has(p.key))
+        return true;
+    const failed = refreshFailedAt.get(p.key);
+    if (failed !== undefined && Date.now() - failed < cooldownMs())
+        return false;
+    if (!exitHooked) {
+        exitHooked = true;
+        process.once("exit", abortBackgroundRefreshes);
+    }
+    const controller = new AbortController();
+    const rec = { controller, root: p.root, superseded: false, promise: Promise.resolve() };
+    const startSeq = invalidationSeq;
+    refreshes.set(p.key, rec);
+    // Own signal, not the triggering request's: that request has already returned.
+    rec.promise = callContext.run({ signal: controller.signal }, () => runWalk(svc, p, controller.signal))
+        .then((w) => {
+        if (rec.superseded)
+            return;
+        if (!w.complete) {
+            refreshFailedAt.set(p.key, Date.now());
+            return;
+        } // keep the stale entry rather than store a partial tree
+        refreshFailedAt.delete(p.key);
+        remember(p, w);
+        persist(svc, p, w, startSeq);
+    })
+        .catch((err) => {
+        if (controller.signal.aborted)
+            return;
+        refreshFailedAt.set(p.key, Date.now());
+        logger.warn("Background walk refresh failed:", err instanceof Error ? err.message : String(err));
+    })
+        .finally(() => { if (refreshes.get(p.key) === rec)
+        refreshes.delete(p.key); });
+    return true;
+}
+async function diskLookup(svc, p, signal) {
+    if (!indexEnabled() || indexMaxAgeMs() <= 0)
+        return undefined;
+    const find = () => pick(diskCandidates(), p.root, p.maxDepth, p.key, p.excludeKey, p.exclude);
+    if (!find())
+        return undefined;
+    if (!(await verifyDisk(svc, signal)))
+        return undefined;
+    const hit = find(); // the file may have been invalidated or discarded while we checked the account
+    if (!hit)
+        return undefined;
+    const res = fromCache(hit.e, p.root, p.maxDepth, p.exclude, hit.exact);
+    if (res.ageMs < ttlMs())
+        return { ...res, stale: true };
+    return { ...res, stale: true, ...(startRefresh(svc, p) ? { refreshing: true } : {}) };
+}
+/**
+ * Breadth-first walk of a Drive folder with bounded parallelism. A folder that
+ * still fails after one retry goes to `skipped` (its subtree is never dropped
+ * silently); maxCalls/maxDepth cuts set `complete: false`. Results are cached
+ * for PROTON_DRIVE_WALK_TTL_MS (default 5 min); a walk of a subfolder can be
+ * served from a cached walk of an ancestor. With PROTON_DRIVE_INDEX=1 complete
+ * walks are also saved to disk and served stale-while-revalidate in a new process.
+ */
+export async function walkTree(svc, rootPath, opts = {}) {
+    const root = normalizeRoot(rootPath);
+    const maxDepth = opts.maxDepth === undefined ? undefined : Math.max(1, Math.floor(opts.maxDepth));
+    const maxCalls = Math.max(1, Math.floor(opts.maxCalls ?? DEFAULT_MAX_CALLS));
+    const concurrency = Math.min(MAX_CONCURRENCY, Math.max(1, Math.floor(opts.concurrency ?? 8)));
+    const excludeList = [...new Set(opts.exclude ?? DEFAULT_EXCLUDE)].sort();
+    const exclude = new Set(excludeList);
+    const signal = opts.signal ?? callContext.getStore()?.signal;
+    if (signal?.aborted)
+        throw abortError(signal);
+    const excludeKey = excludeList.join("\0");
+    const key = [root, maxDepth ?? "", maxCalls, excludeKey].join("\0");
+    const params = { root, maxDepth, maxCalls, concurrency, excludeList, exclude, key, excludeKey };
+    if (!opts.refresh) {
+        const hit = lookup(root, maxDepth, key, excludeKey, exclude);
+        if (hit)
+            return hit;
+        if (!opts.noDisk) {
+            const fromDisk = await diskLookup(svc, params, signal);
+            if (fromDisk)
+                return fromDisk;
+        }
+    }
+    const startSeq = invalidationSeq;
+    const w = await runWalk(svc, params, signal);
+    remember(params, w);
+    persist(svc, params, w, startSeq);
+    return { root, nodes: w.nodes.slice(), complete: w.complete, callsMade: w.callsMade, skipped: w.skipped.slice(), fromCache: false, ageMs: 0 };
 }
 /** Drop cached walks that contain `path` (call after the server itself writes there). */
 export function invalidatePath(path) {
     const p = normalizeRoot(path);
+    const related = (root) => isUnder(root, p) || isUnder(p, root);
+    invalidationSeq++;
     for (const [k, e] of cache)
-        if (isUnder(e.root, p) || isUnder(p, e.root))
+        if (related(e.root))
             cache.delete(k);
+    for (const r of refreshes.values())
+        if (related(r.root)) {
+            r.superseded = true;
+            r.controller.abort(new Error("walk superseded"));
+        }
+    // Memory first: nothing related may be served from the loaded state, whatever happens to the file.
+    if (disk) {
+        const keepMem = disk.entries.filter((e) => !related(e.root));
+        disk = keepMem.length ? { accountKey: disk.accountKey, entries: keepMem } : null;
+    }
+    if (!indexEnabled())
+        return;
+    try {
+        const f = readIndex(); // re-read: another process may have saved since we loaded
+        if (!f)
+            return;
+        const keep = f.entries.filter((e) => !related(e.root));
+        if (keep.length === f.entries.length)
+            return;
+        // If the rewrite does not succeed, remove the file so no deleted/moved item can outlive this call.
+        if (keep.length === 0 || writeIndex({ ...f, savedAt: Date.now(), entries: keep }) !== "ok")
+            deleteIndex();
+    }
+    catch {
+        try {
+            deleteIndex();
+        }
+        catch { /* never fail a write because of the index */ }
+    }
+}
+/** Test hook: drop all in-process state (memory cache, loaded index, background refreshes). */
+export function resetWalkCacheForTests() {
+    abortBackgroundRefreshes();
+    refreshes.clear();
+    cache.clear();
+    disk = undefined;
+    diskVerified = undefined;
+    knownAccountKey = undefined;
+    refreshFailedAt.clear();
+    shuttingDown = false;
+}
+/** Test hook: resolves when background refreshes and index writes have finished. */
+export async function flushWalkIndexForTests() {
+    do {
+        await Promise.allSettled([...refreshes.values()].map((r) => r.promise));
+        await persistChain;
+    } while (refreshes.size > 0);
 }

package/dist/services/walkIndex.js

@@ -0,0 +1,187 @@
+import { accessSync, chmodSync, closeSync, constants, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeSync } from "node:fs";
+import { homedir, platform } from "node:os";
+import { dirname, join } from "node:path";
+import { randomBytes } from "node:crypto";
+import { logger } from "../utils/logger.js";
+/**
+ * Opt-in on-disk copy of completed Drive walks (PROTON_DRIVE_INDEX=1). It holds
+ * file names, paths and hashes of an end-to-end-encrypted drive in PLAINTEXT, so
+ * it is off by default; the file is 0600 in a 0700 directory that this code created or that was already private to the user.
+ */
+export const INDEX_VERSION = 1;
+export const MAX_ENTRIES = 8;
+export const MAX_BYTES = 200 * 1024 * 1024;
+const FILE_NAME = "walk-index.json";
+export function indexEnabled() {
+    const v = (process.env.PROTON_DRIVE_INDEX ?? "").trim().toLowerCase();
+    return v === "1" || v === "true";
+}
+export function indexDir() {
+    const d = process.env.PROTON_DRIVE_INDEX_DIR;
+    if (d && d.trim())
+        return d;
+    if (platform() === "darwin")
+        return join(homedir(), "Library", "Caches", "proton-drive-mcp");
+    return join(process.env.XDG_CACHE_HOME || join(homedir(), ".cache"), "proton-drive-mcp");
+}
+export const indexPath = () => join(indexDir(), FILE_NAME);
+/** Max age of disk data we will serve, ms (PROTON_DRIVE_INDEX_MAX_AGE_H, default 24 h; 0 disables use). */
+export function indexMaxAgeMs() {
+    const h = Number(process.env.PROTON_DRIVE_INDEX_MAX_AGE_H ?? 24);
+    return (Number.isFinite(h) && h >= 0 ? h : 24) * 3_600_000;
+}
+const lstatOrNull = (p) => { try {
+    return lstatSync(p);
+}
+catch {
+    return null;
+} };
+const FUTURE_SKEW_MS = 5 * 60_000;
+const foreignOrLoose = (st) => (typeof process.getuid === "function" && st.uid !== process.getuid()) || (st.mode & 0o077) !== 0;
+/** Reads and validates the index; anything wrong (missing, symlink, loose mode, foreign owner, oversize, corrupt, other version) is "no index". */
+export function readIndex(o = {}) {
+    const p = indexPath();
+    const dst = lstatOrNull(indexDir());
+    if (!dst || !dst.isDirectory())
+        return undefined;
+    if (o.requireWritable) {
+        // Data we cannot keep current (a read-only directory can neither be rewritten nor cleared after our own
+        // writes) must not be served: a trashed or moved item would reappear in the next process.
+        try {
+            accessSync(indexDir(), constants.W_OK);
+            accessSync(p, constants.W_OK);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    let fd;
+    try {
+        fd = openSync(p, constants.O_RDONLY | constants.O_NOFOLLOW); // a symlink is never followed
+        const st = fstatSync(fd);
+        if (!st.isFile() || foreignOrLoose(st) || st.size > MAX_BYTES)
+            return undefined; // checked before reading
+        const j = JSON.parse(readFileSync(fd, "utf8"));
+        if (!j || j.version !== INDEX_VERSION || typeof j.accountKey !== "string" || !Array.isArray(j.entries))
+            return undefined;
+        const horizon = Date.now() + FUTURE_SKEW_MS;
+        const ok = j.entries.every((e) => e && typeof e.key === "string" && typeof e.root === "string" && Number.isFinite(e.completedAt) && e.completedAt <= horizon && Array.isArray(e.nodes) && e.opts && Array.isArray(e.opts.exclude));
+        return ok ? j : undefined;
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                closeSync(fd);
+            }
+            catch { /* ignore */ }
+        }
+    }
+}
+let warnedSize = false;
+const warnedDirs = new Set();
+/** Atomic write. Never throws; the result says what happened. */
+export function writeIndex(file, o = {}) {
+    if (!indexEnabled())
+        return "disabled";
+    const dir = indexDir();
+    let tmp;
+    try {
+        const trimmed = { ...file, entries: [...file.entries].sort((a, b) => b.completedAt - a.completedAt).slice(0, MAX_ENTRIES) };
+        const body = JSON.stringify(trimmed);
+        if (Buffer.byteLength(body) > (o.maxBytes ?? MAX_BYTES)) {
+            if (!warnedSize) {
+                warnedSize = true;
+                logger.warn("Persistent walk index not saved: it would exceed the size cap.");
+            }
+            return "too-large";
+        }
+        const existing = lstatOrNull(dir);
+        if (existing) {
+            // Never chmod or take over a directory this code did not create.
+            if (!existing.isDirectory() || foreignOrLoose(existing)) {
+                if (!warnedDirs.has(dir)) {
+                    warnedDirs.add(dir);
+                    logger.warn(`Persistent walk index not saved: ${dir} must be a real directory owned by you with no group/other access (mode 0700). Use a dedicated directory.`);
+                }
+                return "refused";
+            }
+        }
+        else {
+            mkdirSync(dirname(dir), { recursive: true });
+            mkdirSync(dir, { mode: 0o700 });
+            chmodSync(dir, 0o700); // umask-proof; safe because we just created it
+            const made = lstatSync(dir);
+            if (!made.isDirectory() || foreignOrLoose(made))
+                return "refused";
+        }
+        const target = join(dir, FILE_NAME);
+        const tst = lstatOrNull(target);
+        if (tst && !tst.isFile())
+            return "refused"; // symlink or directory in the way
+        tmp = join(dir, `${FILE_NAME}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`);
+        const fd = openSync(tmp, "wx", 0o600); // O_EXCL: never follows a pre-planted link
+        try {
+            writeSync(fd, body);
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+        chmodSync(tmp, 0o600);
+        renameSync(tmp, target);
+        tmp = undefined;
+        const fin = lstatSync(target);
+        if (!fin.isFile() || (fin.mode & 0o077) !== 0) {
+            try {
+                unlinkSync(target);
+            }
+            catch { /* best effort */ }
+            return "refused";
+        }
+        return "ok";
+    }
+    catch (err) {
+        logger.warn("Persistent walk index write failed:", err instanceof Error ? err.message : String(err));
+        return "error";
+    }
+    finally {
+        if (tmp) {
+            try {
+                unlinkSync(tmp);
+            }
+            catch { /* already gone */ }
+        }
+    }
+}
+/** Deletes the index file (a symlink is removed itself, never followed). */
+export function deleteIndex() {
+    const path = indexPath();
+    const st = lstatOrNull(path);
+    if (!st)
+        return { path, deleted: false, bytes: 0 };
+    try {
+        unlinkSync(path);
+        return { path, deleted: true, bytes: st.size };
+    }
+    catch {
+        return { path, deleted: false, bytes: 0 };
+    }
+}
+export function indexStatus() {
+    const path = indexPath();
+    const st = lstatOrNull(path);
+    const base = { enabled: indexEnabled(), path, maxAgeHours: indexMaxAgeMs() / 3_600_000 };
+    if (!st)
+        return { ...base, exists: false };
+    const idx = readIndex();
+    return {
+        ...base, exists: true, bytes: st.size, valid: !!idx,
+        ...(idx ? {
+            savedAt: new Date(idx.savedAt).toISOString(), ageMs: Date.now() - idx.savedAt,
+            entries: idx.entries.map((e) => ({ root: e.root, nodes: e.nodes.length, completedAt: new Date(e.completedAt).toISOString() })),
+        } : { entries: [] }),
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "proton-drive-mcp",
-  "version": "1.3.2",
+  "version": "1.4.0",
   "description": "MCP server and CLI that gives Claude full access to Proton Drive — upload, download, share, and manage your end-to-end encrypted files without leaving the conversation.",
   "type": "module",
   "main": "dist/index.js",
@@ -18,7 +18,7 @@
     "dev": "tsc --watch",
     "start": "node dist/index.js",
     "cli": "npm run build && node dist/cli.js",
-    "test": "npm run build && node --test --test-concurrency=4 test/*.test.mjs",
+    "test": "npm run build && node --import ./test/helpers/no-index.mjs --test --test-concurrency=4 test/*.test.mjs",
     "lint": "tsc --noEmit",
     "clean": "rm -rf dist",
     "ci": "npm run lint && npm test",