@bobfrankston/tsfind 0.1.1 → 0.1.2

package/README.md

@@ -1,14 +1,16 @@
 # tsfind
 
 Find files by name on an NTFS volume, fast. It reads the volume's Master File Table
-([`@bobfrankston/mftwalk`](https://github.com/BobFrankston/mftwalk)) instead of walking, and caches
-the scan, so repeated searches and analyses of the same drive take seconds. By default it prints
+([`@bobfrankston/mftwalk`](https://github.com/BobFrankston/mftwalk)) instead of walking, and saves
+the scan, kept current by the drive's change journal, so repeated searches and analyses of the
+same drive take seconds and always see it as it is now. By default it prints
 bare paths, one per line, so the list can be edited (for example, cut down to the files to
 delete). `-count` tallies the matches by name and by extension instead, and `-hogs` shows just the
 largest.
 
-A find-only companion to [tswalk](https://github.com/BobFrankston/tswalk), which walks trees
-(non-NTFS and network drives included).
+A find-only companion to [tswalk](https://github.com/BobFrankston/tswalk). When the MFT cannot be
+used (off Windows, non-NTFS or network drives, or no admin rights to be had without a UAC prompt),
+tsfind walks the tree instead and says why.
 
 ## Install
 
@@ -36,28 +38,44 @@ tsfind [dir] [pattern] [options]
 | `-sort key` | `-count` order: `size` (default), `count` or `name` |
 | `-top N` | `-count` rows per table (default 50; 0 = all) |
 | `-hogs [name\|ext] [N\|N%]` | Largest totals by name (default) or extension, with each one's share; top N (default 5), or every one taking at least N% |
-| `-age N` | Use a cached scan up to N minutes old (default 60) |
-| `-fresh` | Rescan the MFT even if a cached scan is young enough |
 | `-q` | No progress or summary |
 | `-help`, `-version` | |
 
 The list is sorted by path. Progress and the summary go to stderr, so stdout carries only the
 list. Links and junctions are never entered.
 
-## The MFT and the cache
+## The MFT and the saved scan
 
-Scanning the MFT needs Windows, NTFS and an elevated prompt (e.g. `gsudo`); tsfind does not walk.
-The whole volume is scanned whatever folder is searched. A 15 TB USB backup drive with 8.7M files
-takes about 5-8 minutes and 1.6 GB of memory.
+Reading the MFT needs Windows and NTFS. The whole volume is read whatever
+folder is searched: a 15 TB USB backup drive with 8.7M files takes about 5-8 minutes and 1.6 GB of
+memory. Each read is saved through mftwalk in `%TEMP%\tsfind\mft`, one file per volume, keyed by
+volume serial so it follows the drive to any letter. The drive's NTFS **change journal** keeps it
+current (since 2026-11-07; before that tsfind kept its own snapshot, valid for `-age` minutes):
 
-Each scan is saved, zstd-compressed, as `%TEMP%\tsfind\<volume label>-<volume serial>.idx.zst` (e.g. `20251211y-F860296A.idx.zst`): about 11 bytes
-per entry (Y: here: 1.33M entries, 14 MB), so about 110 MB for 10M files. A cache younger than
-`-age` minutes (default 60) is used instead of rescanning, for any folder on that volume, and
-reading it needs no elevation. It is a snapshot: changes since the scan are not seen until it
-expires or `-fresh` is given. When a rescan is not possible (not elevated), an older cache is used
-and the summary says how old. Each drive has its own cache, named by volume label (readable) and
-volume serial number (unique), so it follows the drive to whatever letter it is mounted under, and
-two drives with the same label are kept apart. Renaming a drive's label means one rescan.
+- **Unchanged** since the save: the saved scan is used as is. Seconds; no admin rights needed.
+- **Changed**: only the MFT records the journal names are read again (admin rights).
+- **No saved scan, or no journal**: the whole MFT is read (admin rights).
+
+### Admin rights (2026-11-09)
+
+When a read needs admin rights and tsfind is not elevated, it elevates by itself **only if Windows
+would allow it without asking**: the account is an administrator and UAC is set not to prompt
+(`ConsentPromptBehaviorAdmin` = 0). A hidden elevated copy of tsfind then brings the saved scan up
+to date, and the search runs on it in your own, unelevated process, so pipes and `-o` work as
+usual. Changes made in the seconds after that update are not included, and the summary says so.
+
+If Windows would ask, tsfind never raises the popup, because it would stall a script. It says why
+on stderr and walks the tree instead (slow on a big drive). Run it elevated for MFT speed.
+
+The walk never enters links or junctions. Entries it cannot read are listed after the summary,
+even with `-q`, since without them the results may be incomplete.
+
+A drive without a change journal is read in full on every run; tsfind prints the command that
+turns one on (`fsutil usn createjournal m=33554432 a=8388608 X:`, elevated). Measured cost of a
+journal on a USB backup drive: creating, renaming and deleting many small files is about 10-30%
+slower; large sequential writes are unaffected. The summary always says where the data came
+from: the saved scan, the MFT, or a walk and why. A saved scan takes about 150-200 bytes per MFT record (S: here,
+2.4M files: 455 MB).
 
 A file with several hard links is found under one of its names only (mftwalk keeps one name per
 MFT record); cargo's `target` directories are the common case.
@@ -65,12 +83,12 @@ MFT record); cargo's `target` directories are the common case.
 ## Examples
 
 ```bash
-gsudo tsfind U:\ -hogs ext                   # scans the MFT; the 5 extensions taking the most space
-tsfind U:\ -hogs 2%                          # from the cache: every name taking at least 2%
-tsfind U:\Aged -count -top 30                # from the cache: by name and extension
-tsfind U:\ telemetrydata.db -o tele.txt      # list for editing
+tsfind U:\ telemetrydata.db -o tele.txt      # list them to tele.txt for editing
 tsfind U:\ "*telemetry*" -l                  # with dates and sizes
-gsudo tsfind U:\ -fresh -hogs                # rescan now
+tsfind U:\ -hogs ext                         # the 5 extensions taking the most space
+tsfind U:\Aged -hogs 2%                      # every name taking at least 2% of U:\Aged
+tsfind U:\ -count -top 30                    # where the space goes, by name and extension
+tsfind "*.bak;*.tmp" -count -sort count      # in the current directory
 ```
 
 ## License

package/index.d.ts

@@ -4,6 +4,25 @@
  * count them by name and extension, or show where the space goes
  *
  * CHANGE LOG (newest first)
+ * 2026-11-11 — Claude Code (Opus 5.5), at Bob's direction: usage text and README brought into
+ *   line: the same examples in both, and both say a walk lists unreadable entries even with -q.
+ * 2026-11-09 — Claude Code (Opus 5.5), at Bob's direction: "if you can elevate without a prompt
+ *   do so, otherwise fall back", and the fallback is the walk ("bring back the walk"). When the
+ *   saved MFT scan needs an update that needs admin rights, tsfind checks whether Windows would
+ *   elevate without asking (an administrator, UAC set not to prompt: ConsentPromptBehaviorAdmin 0).
+ *   If so, a hidden elevated copy of tsfind (-refreshscan X:) brings the saved scan up to date and
+ *   the search runs on it, here, unelevated, so pipes and -o are unchanged. If Windows would ask,
+ *   tsfind does NOT raise the popup (it would stall scripts): it says why and walks the tree.
+ *   The walk also replaces the old "use tswalk" failures: off Windows, non-NTFS, network paths.
+ *   A stale saved scan is no longer used as is; Bob chose the walk over it.
+ * 2026-11-07 — Claude Code (Opus 5.5), at Bob's direction ("the default should be to use the
+ *   journal"): tsfind's own cache is gone. It now uses mftwalk's saved scans (ScanOptions.cache),
+ *   which the NTFS change journal keeps current: an unchanged volume loads the saved scan without
+ *   elevation, a changed one re-reads only the changed records, a full read happens only with no
+ *   saved scan or no journal. So results are current, not a snapshot up to an hour old, and -age
+ *   and -fresh are gone. tsfind searches the MftVolume directly; its preorder index and zstd cache
+ *   file (TSFINDX1) existed only to be cached, and are removed. If an update needs admin rights
+ *   that are not there, the saved scan is used as it is and the summary says it is not current.
  * 2026-10-27 (later) — Claude Code (Opus 5.5), at Bob's direction: MFT only, with a cache.
  *   Bob: "Walking is expensive and is already handled by tswalk... the point of tsfind is to be
  *   fast. Having a compressed cache that is valid for a limited time allows me to run multiple

package/index.js

@@ -4,6 +4,25 @@
  * count them by name and extension, or show where the space goes
  *
  * CHANGE LOG (newest first)
+ * 2026-11-11 — Claude Code (Opus 5.5), at Bob's direction: usage text and README brought into
+ *   line: the same examples in both, and both say a walk lists unreadable entries even with -q.
+ * 2026-11-09 — Claude Code (Opus 5.5), at Bob's direction: "if you can elevate without a prompt
+ *   do so, otherwise fall back", and the fallback is the walk ("bring back the walk"). When the
+ *   saved MFT scan needs an update that needs admin rights, tsfind checks whether Windows would
+ *   elevate without asking (an administrator, UAC set not to prompt: ConsentPromptBehaviorAdmin 0).
+ *   If so, a hidden elevated copy of tsfind (-refreshscan X:) brings the saved scan up to date and
+ *   the search runs on it, here, unelevated, so pipes and -o are unchanged. If Windows would ask,
+ *   tsfind does NOT raise the popup (it would stall scripts): it says why and walks the tree.
+ *   The walk also replaces the old "use tswalk" failures: off Windows, non-NTFS, network paths.
+ *   A stale saved scan is no longer used as is; Bob chose the walk over it.
+ * 2026-11-07 — Claude Code (Opus 5.5), at Bob's direction ("the default should be to use the
+ *   journal"): tsfind's own cache is gone. It now uses mftwalk's saved scans (ScanOptions.cache),
+ *   which the NTFS change journal keeps current: an unchanged volume loads the saved scan without
+ *   elevation, a changed one re-reads only the changed records, a full read happens only with no
+ *   saved scan or no journal. So results are current, not a snapshot up to an hour old, and -age
+ *   and -fresh are gone. tsfind searches the MftVolume directly; its preorder index and zstd cache
+ *   file (TSFINDX1) existed only to be cached, and are removed. If an update needs admin rights
+ *   that are not there, the saved scan is used as it is and the summary says it is not current.
  * 2026-10-27 (later) — Claude Code (Opus 5.5), at Bob's direction: MFT only, with a cache.
  *   Bob: "Walking is expensive and is already handled by tswalk... the point of tsfind is to be
  *   fast. Having a compressed cache that is valid for a limited time allows me to run multiple
@@ -26,36 +45,39 @@
  * telemetrydata.db files on the backup drives.
  */
 import * as fp from 'node:fs/promises';
-import { createReadStream, createWriteStream } from 'node:fs';
 import * as os from 'node:os';
-import { spawnSync } from 'node:child_process';
+import { getDriveInfo } from '@bobfrankston/dirutil';
 import * as path from 'node:path';
 import { styleText } from 'node:util';
-import { Readable } from 'node:stream';
-import { finished, pipeline } from 'node:stream/promises';
-import { createZstdCompress, createZstdDecompress } from 'node:zlib';
+import { finished } from 'node:stream/promises';
+import { spawn, spawnSync } from 'node:child_process';
 import packageJson from './package.json' with { type: 'json' };
 const version = packageJson.version;
-/** A cache younger than this many minutes is used instead of rescanning (-age changes it) */
-const DEFAULT_CACHE_MINUTES = 60;
 /** Default rows per -count table */
 const DEFAULT_TOP = 50;
 /** Default rows for -hogs */
 const DEFAULT_HOGS = 5;
 /** Lines handed to the output stream per write */
 const WRITE_BATCH = 10000;
-/** Names encoded or decoded per piece of the cache's name section (keeps each string well under V8's limit) */
-const NAME_BATCH = 100000;
-/** Bytes of the name section decoded at a time when loading */
-const NAME_DECODE_BYTES = 64 * 1024 * 1024;
 const CLEAR_LINE = '\x1b[2K\r';
-/** First bytes of a cache file; the digit is the format version */
-const CACHE_MAGIC = 'TSFINDX1';
-/** Bits in VolumeIndex.flags */
-const IndexFlags = {
-    Directory: 0x01, /** A directory (searched beneath) */
-    Link: 0x02, /** A junction or symbolic link (never entered) */
+/**
+ * Change journal size suggested when a drive has none (Windows' usual 32 MB, 8 MB steps); it only
+ * has to hold the changes between two runs. Same suggestion as tswalk's.
+ */
+const SUGGESTED_JOURNAL = 'm=33554432 a=8388608';
+/** Directories read at once by the walk */
+const WALK_CONCURRENCY = 16;
+/** Unreadable directories named in the walk's summary; the rest are only counted */
+const WALK_ERRORS_SHOWN = 5;
+/** Well-known SIDs in `whoami /groups` */
+const Sids = {
+    Administrators: 'S-1-5-32-544', /** BUILTIN\Administrators (deny-only in an unelevated admin token) */
+    HighIntegrity: 'S-1-16-12288', /** High Mandatory Level: the process is elevated */
 };
+/** HKLM key holding the UAC settings */
+const UAC_KEY = 'HKLM\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Policies\\System';
+/** ConsentPromptBehaviorAdmin value meaning "elevate administrators without prompting" */
+const UAC_ELEVATE_WITHOUT_PROMPT = 0;
 function usage() {
     return `tsfind v${version} - find files by name on an NTFS volume, fast, from its Master File Table
 
@@ -79,19 +101,25 @@ Options:
                 Instead of listing: where the space goes. The largest totals by name
                 (default) or by extension, with each one's share of the space matched.
                 N = how many (default ${DEFAULT_HOGS}); N% = every one taking at least N%.
-    -age N      Use a cached scan up to N minutes old (default ${DEFAULT_CACHE_MINUTES})
-    -fresh      Rescan the MFT even if a cached scan is young enough
     -q          No progress or summary
     -h, -help   This message
     -version    Version
 
-How it works: tsfind reads the volume's NTFS Master File Table (Windows, NTFS, elevated prompt),
-which takes minutes rather than the hours a walk can take on a big drive. The scan is cached,
-compressed, in ${cacheDir()}, one file per volume, so further searches of
-any folder on that volume take seconds and need no elevation. The cache is a snapshot:
-changes since the scan are not seen until it is older than -age or -fresh is given. If a
-rescan is not possible (not elevated) an older cache is used, and the summary says how old.
-For a walk of a non-NTFS or network drive, use tswalk.
+How it works: tsfind reads the volume's NTFS Master File Table (Windows, NTFS) rather than walking:
+minutes instead of the hours a walk can take on a big drive. Each read is saved, one file per
+volume, in ${cacheDir()}, and the drive's change journal keeps it current:
+  - unchanged since the save: the saved scan is used as is (seconds; no admin rights needed)
+  - changed: only the changed MFT records are read again (admin rights)
+  - no saved scan yet, or no change journal: the whole MFT is read (admin rights)
+So every search sees the drive as it is now. A drive without a change journal is read in full
+every time; tsfind prints the fsutil command that turns one on.
+
+Admin rights: when a read needs them and tsfind is not elevated, it elevates by itself only if
+Windows would allow it without asking (you are an administrator and UAC is set not to prompt).
+Otherwise it never raises a UAC popup, which would stall a script: it says why on stderr and
+walks the tree instead (slow on a big drive). It also walks off Windows, on non-NTFS drives and
+on network paths. The summary always says which it did. Entries a walk cannot read are listed
+after the summary, even with -q, since the results may then be incomplete.
 
 Progress and the summary go to stderr, so stdout carries only the list.
 
@@ -116,8 +144,8 @@ function parseArgs(args) {
     }
     const options = {
         positional: [], patterns: null, top: '.', outFile: '', long: false, dirs: false, count: false,
-        sort: 'size', rows: DEFAULT_TOP, hogs: null, hogsRows: DEFAULT_HOGS, hogsPercent: 0,
-        cacheMinutes: DEFAULT_CACHE_MINUTES, quiet: false,
+        sort: 'size', rows: DEFAULT_TOP, hogs: null, hogsRows: DEFAULT_HOGS, hogsPercent: 0, quiet: false,
+        refreshScan: '',
     };
     for (let i = 0; i < args.length; i++) {
         const arg = args[i];
@@ -183,19 +211,20 @@ function parseArgs(args) {
                 }
                 break;
             }
-            case '-age': {
-                const n = needValue();
-                if (!/^\d+(\.\d+)?$/.test(n))
-                    fail(`-age needs a number of minutes, not ${n}`);
-                options.cacheMinutes = parseFloat(n);
-                break;
-            }
+            // 2026-11-07: retired with tsfind's own cache; said explicitly rather than "Unknown option".
+            case '-age':
             case '-fresh':
-                options.cacheMinutes = 0;
-                break;
+                fail(`${arg} is gone: the drive's change journal now keeps the saved scan current, so every search is up to date.`);
             case '-q':
                 options.quiet = true;
                 break;
+            case '-refreshscan': {
+                const drive = needValue();
+                if (!/^[A-Za-z]:$/.test(drive))
+                    fail(`-refreshscan needs a drive like C:, not ${drive}`);
+                options.refreshScan = drive.toUpperCase();
+                break;
+            }
             case '-h':
             case '-help':
                 console.log(usage());
@@ -289,270 +318,272 @@ function clearProgress(options) {
     if (!options.quiet && process.stderr.isTTY)
         process.stderr.write(CLEAR_LINE);
 }
-// ── Index: scan, save, load ────────────────────────────────────────
+// ── Volume: mftwalk's saved scan, kept current by the change journal ──
 function cacheDir() {
-    return path.join(os.tmpdir(), 'tsfind');
-}
-/**
- * Read the MFT of the volume holding `top` and build tsfind's index of it. Throws MftError when
- * the MFT cannot be read (not elevated, not NTFS); the caller decides what to do about that.
- */
-async function scanToIndex(top, options) {
-    const { scanVolume } = await import('@bobfrankston/mftwalk');
-    const volume = await scanVolume(top, {
-        onProgress: (done, total) => progress(options, `MFT ${done.toLocaleString()} / ${total.toLocaleString()} records`),
-    });
-    clearProgress(options);
-    return indexFromVolume(volume);
+    return path.join(os.tmpdir(), 'tsfind', 'mft');
 }
-/** Lay the volume out in preorder from the root, through mftwalk's public accessors */
-function indexFromVolume(volume) {
-    const order = [];
-    const parentOf = [];
-    // Depth-first; children pushed in reverse so they come out in the volume's own order.
-    const stack = [{ id: volume.root, parent: -1 }];
-    while (stack.length) {
-        const { id, parent } = stack.pop();
-        const at = order.length;
-        order.push(id);
-        parentOf.push(parent);
-        const kids = volume.children(id);
-        for (let k = kids.length - 1; k >= 0; k--) {
-            // NTFS's own files ($MFT, $Extend, ...) are invisible to readdir; leave them out likewise.
-            if (!volume.isMetafile(kids[k]))
-                stack.push({ id: kids[k], parent: at });
-        }
+/** One line saying where the volume's data came from, for the summary */
+function sourceText(volume) {
+    const origin = volume.origin;
+    switch (origin.source) {
+        case 'cache':
+            return origin.changed
+                ? `saved MFT scan, NOT current: ${origin.reason}`
+                : `saved MFT scan: ${origin.reason}`;
+        case 'updated':
+            return origin.reason;
     }
-    const count = order.length;
-    const index = {
-        count,
-        parent: Int32Array.from(parentOf),
-        subtreeEnd: new Int32Array(count),
-        flags: new Uint8Array(count),
-        size: new Float64Array(count),
-        mtime: new Float64Array(count),
-        names: new Array(count),
-    };
-    for (let i = 0; i < count; i++) {
-        const id = order[i];
-        index.flags[i] = (volume.isDirectory(id) ? IndexFlags.Directory : 0) | (volume.isLink(id) ? IndexFlags.Link : 0);
-        index.size[i] = volume.size(id);
-        index.mtime[i] = volume.mtime(id).getTime();
-        index.names[i] = i === 0 ? '' : volume.name(id);
-        index.subtreeEnd[i] = i + 1;
-    }
-    // In preorder a subtree ends where its last descendant's subtree ends; children come after
-    // parents, so one backward pass carries each end up to its parent.
-    for (let i = count - 1; i > 0; i--) {
-        const p = index.parent[i];
-        if (index.subtreeEnd[i] > index.subtreeEnd[p])
-            index.subtreeEnd[p] = index.subtreeEnd[i];
-    }
-    return index;
+    return `MFT read in full: ${origin.reason}`;
 }
-/** Bytes of a typed array, as a Buffer over the same memory */
-function bytesOf(array) {
-    return Buffer.from(array.buffer, array.byteOffset, array.byteLength);
-}
-/** The cache file's pieces, in order: magic, header length, header, then the arrays and names */
-function* cachePieces(index) {
-    const header = Buffer.from(JSON.stringify({ count: index.count }));
-    const headerLength = Buffer.alloc(4);
-    headerLength.writeUInt32LE(header.length);
-    yield Buffer.from(CACHE_MAGIC);
-    yield headerLength;
-    yield header;
-    yield bytesOf(index.parent);
-    yield bytesOf(index.subtreeEnd);
-    yield bytesOf(index.flags);
-    yield bytesOf(index.size);
-    yield bytesOf(index.mtime);
-    // Names end with \0, which no NTFS name contains.
-    for (let i = 0; i < index.count; i += NAME_BATCH) {
-        yield Buffer.from(index.names.slice(i, i + NAME_BATCH).join('\0') + '\0');
-    }
+/** A walk, with the reason it is not the MFT, said now on stderr and again in the summary */
+function walkSource(top, reason, options) {
+    if (!options.quiet)
+        console.error(styleText(['red'], `Walking ${top} instead of reading the MFT: ${reason}`));
+    return { volume: null, text: `directory walk, not the MFT: ${reason}`, stale: false };
 }
 /**
- * Save the index, zstd-compressed, and date the file to the start of the scan so its age is the
- * snapshot's age. Written to a temporary name and renamed, so a reader never sees half a file.
+ * Can this process get admin rights without anyone being asked? True only for an administrator
+ * (deny-only Administrators in this unelevated token) on a machine whose UAC elevates
+ * administrators without prompting. `why` says what stands in the way when it is false.
  */
-async function saveIndex(index, cachePath, scannedAt) {
-    await fp.mkdir(path.dirname(cachePath), { recursive: true });
-    const partial = cachePath + '.partial';
-    await pipeline(Readable.from(cachePieces(index)), createZstdCompress(), createWriteStream(partial));
-    await fp.utimes(partial, scannedAt, scannedAt);
-    await fp.rename(partial, cachePath);
+function silentElevation() {
+    const groups = spawnSync('whoami', ['/groups', '/fo', 'csv', '/nh'], { encoding: 'utf8' });
+    if (groups.status !== 0) {
+        return { possible: false, why: `cannot tell whether elevation would prompt (whoami: ${groups.error?.message ?? groups.stderr.trim()})` };
+    }
+    if (groups.stdout.includes(Sids.HighIntegrity)) {
+        return { possible: false, why: 'Windows refused the MFT even though tsfind is already elevated' };
+    }
+    if (!groups.stdout.includes(Sids.Administrators)) {
+        return { possible: false, why: 'it needs admin rights, and this account is not an administrator' };
+    }
+    const uac = spawnSync('reg', ['query', UAC_KEY, '/v', 'ConsentPromptBehaviorAdmin'], { encoding: 'utf8' });
+    const value = /ConsentPromptBehaviorAdmin\s+REG_DWORD\s+0x([0-9a-f]+)/i.exec(uac.stdout ?? '');
+    if (!value) {
+        return { possible: false, why: `it needs admin rights, and the UAC setting cannot be read (${uac.error?.message ?? (uac.stderr.trim() || 'no ConsentPromptBehaviorAdmin')}), so elevating might raise a prompt` };
+    }
+    const behavior = parseInt(value[1], 16);
+    if (behavior !== UAC_ELEVATE_WITHOUT_PROMPT) {
+        return { possible: false, why: `it needs admin rights, and UAC here would ask (ConsentPromptBehaviorAdmin ${behavior}); tsfind will not raise a popup that stalls a script. Run tsfind elevated for MFT speed` };
+    }
+    return { possible: true, why: '' };
 }
-async function loadIndex(cachePath) {
-    const chunks = [];
-    await pipeline(createReadStream(cachePath), createZstdDecompress(), async function* (source) {
-        for await (const chunk of source)
-            chunks.push(chunk);
-    });
-    const data = Buffer.concat(chunks);
-    chunks.length = 0;
-    if (data.toString('latin1', 0, CACHE_MAGIC.length) !== CACHE_MAGIC)
-        throw new Error(`${cachePath} is not a tsfind cache of this version`);
-    let at = CACHE_MAGIC.length;
-    const headerLength = data.readUInt32LE(at);
-    at += 4;
-    const { count } = JSON.parse(data.toString('utf8', at, at + headerLength));
-    at += headerLength;
-    // Copied out rather than viewed in place: the arrays' offsets in the buffer are not aligned.
-    const take = (array) => {
-        bytesOf(array).set(data.subarray(at, at + array.byteLength));
-        at += array.byteLength;
-        return array;
-    };
-    const index = {
-        count,
-        parent: take(new Int32Array(count)),
-        subtreeEnd: take(new Int32Array(count)),
-        flags: take(new Uint8Array(count)),
-        size: take(new Float64Array(count)),
-        mtime: take(new Float64Array(count)),
-        names: [],
-    };
-    while (at < data.length) {
-        let end = data.indexOf(0, Math.min(at + NAME_DECODE_BYTES, data.length - 1));
-        if (end < 0)
-            end = data.length - 1;
-        const piece = data.toString('utf8', at, end).split('\0');
-        for (const name of piece)
-            index.names.push(name);
-        at = end + 1;
-    }
-    if (index.names.length !== count)
-        throw new Error(`${cachePath} is damaged: ${index.names.length} names for ${count} entries`);
-    return index;
+/** Where the hidden elevated copy leaves its result, since it has no console the caller can see */
+function refreshResultFile(driveName) {
+    return path.join(os.tmpdir(), 'tsfind', `refresh-${driveName[0]}.txt`);
 }
 /**
- * The volume label of the drive holding `top`, or '' if it has none or cannot be read.
- * Node has no call for it, Get-Volume takes seconds, and reading it needs no elevation through
- * cmd's vol, whose first line is "Volume in drive Y is <label>" (or "... has no label.").
- * That wording is English Windows; on any other the label reads as '' and the cache is named
- * "nolabel-<serial>", which still identifies the drive by its serial.
+ * Bring driveName's saved MFT scan up to date from a hidden, elevated copy of tsfind
+ * (-refreshscan). Only called when silentElevation() says Windows will not ask; the "runas" verb
+ * is Windows' own elevation request. Returns '' on success, else why it failed.
  */
-function volumeLabel(top) {
-    const result = spawnSync('cmd', ['/d', '/c', 'vol', top.slice(0, 2)], { encoding: 'utf8' });
-    // Only the first line: the second, "Volume Serial Number is ...", also contains " is ".
-    const firstLine = (result.stdout ?? '').trim().split(/\r?\n/)[0];
-    const match = /^Volume in drive \w is (.*)$/.exec(firstLine);
-    return match ? match[1].trim() : '';
+async function refreshElevated(driveName, options) {
+    const resultFile = refreshResultFile(driveName);
+    await fp.mkdir(path.dirname(resultFile), { recursive: true });
+    await fp.rm(resultFile, { force: true });
+    const psQuote = (s) => `'${s.replace(/'/g, "''")}'`;
+    const childArgs = `"${import.meta.filename}" -refreshscan ${driveName}`;
+    const command = `$p = Start-Process -FilePath ${psQuote(process.execPath)} -ArgumentList ${psQuote(childArgs)} ` +
+        `-Verb RunAs -WindowStyle Hidden -Wait -PassThru; exit $p.ExitCode`;
+    const started = Date.now();
+    const ticker = setInterval(() => progress(options, `Updating ${driveName}'s saved MFT scan, elevated: ${elapsedText(Date.now() - started)}`), 1000);
+    const { code, stderr } = await new Promise(resolve => {
+        const child = spawn('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', command], { stdio: ['ignore', 'ignore', 'pipe'] });
+        let errText = '';
+        child.stderr.on('data', chunk => errText += chunk);
+        child.on('error', error => resolve({ code: -1, stderr: error.message }));
+        child.on('close', exitCode => resolve({ code: exitCode, stderr: errText }));
+    });
+    clearInterval(ticker);
+    clearProgress(options);
+    let result = '';
+    try {
+        result = (await fp.readFile(resultFile, 'utf8')).trim();
+    }
+    catch (error) {
+        // Not lost: no result file means the elevated copy never ran or died early; the failure
+        // below then reports PowerShell's own error and the exit code instead.
+        result = '';
+    }
+    if (code === 0 && result === 'ok')
+        return '';
+    return result || stderr.trim().split('\n')[0] || `the elevated copy of tsfind exited with code ${code}`;
 }
 /**
- * The index for the volume holding `top`: the cache if it is young enough, else a new scan
- * (saved for next time), else, if the scan is not possible, an older cache with a note saying so.
+ * -refreshscan X: the hidden elevated copy. Brings X:'s saved scan up to date (mftwalk: updated
+ * from the journal, or read in full) and leaves 'ok' or the error in refreshResultFile.
  */
-async function getIndex(top, options) {
-    // 2026-10-27 — Claude Code (Opus 5.5), at Bob's direction: the cache is named by volume label
-    // and volume serial number (20251211y-F860296A.idx.zst). The label says which drive a file is
-    // for; the serial keeps two drives with the same label apart. Either follows the drive to
-    // whatever letter it is mounted under. (Briefly the drive letter was used instead of the label.)
-    // On Windows fs.stat's dev is the volume serial number, and reading it needs no elevation.
-    const serial = (await fp.stat(top)).dev.toString(16).toUpperCase().padStart(8, '0');
-    const label = volumeLabel(top);
-    const cachePath = path.join(cacheDir(), `${label.replace(/[^\w.-]/g, '_') || 'nolabel'}-${serial}.idx.zst`);
-    let cacheAgeMs = -1;
+async function refreshScanAndExit(driveName) {
+    const resultFile = refreshResultFile(driveName);
+    let result = 'ok';
     try {
-        cacheAgeMs = Date.now() - (await fp.stat(cachePath)).mtimeMs;
+        const { scanVolume } = await import('@bobfrankston/mftwalk');
+        await scanVolume(driveName + '\\', { cache: { dir: cacheDir() } });
     }
     catch (error) {
-        // Not lost: no cache file is the ordinary first-run case, and leads to a scan below.
-        if (error.code !== 'ENOENT')
-            throw error;
+        result = error.message ?? String(error);
     }
-    // 2026-10-27 — Claude Code (Opus 5.5), at Bob's direction: say at the start which source is
-    // used and how old the cache is, not only in the summary at the end.
-    const announce = (text) => {
-        if (!options.quiet)
-            console.error(styleText(['blue'], text));
-    };
-    const volumeName = `${top.slice(0, 2).toUpperCase()} ${label ? `"${label}"` : '(no label)'} (serial ${serial})`;
-    const load = async (note) => {
-        announce(`Using the cached scan of ${volumeName}, ${elapsedText(cacheAgeMs)} old${note ? `; ${note}` : ''}: ${cachePath}`);
-        const index = await loadIndex(cachePath);
-        return { index, source: { scanned: false, ageMs: cacheAgeMs, cachePath, note } };
+    await fp.mkdir(path.dirname(resultFile), { recursive: true });
+    await fp.writeFile(resultFile, result);
+    process.exit(result === 'ok' ? 0 : 1);
+}
+/**
+ * Where to search `top`: the volume from mftwalk's saved scan (see usage: unchanged -> saved scan,
+ * changed -> updated from the journal, else a full read). When that needs admin rights tsfind does
+ * not have, it elevates only if Windows will not ask; otherwise, and whenever the MFT cannot be
+ * used at all, it walks the tree and says why.
+ */
+async function getSource(top, options) {
+    if (process.platform !== 'win32')
+        return walkSource(top, 'the MFT is read on Windows only', options);
+    if (!/^[A-Za-z]:\\/.test(top))
+        return walkSource(top, 'not on a drive letter (a network path?)', options);
+    const drive = getDriveInfo(top.slice(0, 3));
+    if (drive.fileSystem !== 'NTFS')
+        return walkSource(top, `${top.slice(0, 2)} is ${drive.fileSystem || 'not a local file system'}, not NTFS`, options);
+    const driveName = top.slice(0, 2).toUpperCase();
+    const label = drive.volumeName ? `"${drive.volumeName}"` : '(no label)';
+    if (!options.quiet)
+        console.error(styleText(['blue'], `Reading ${driveName} ${label}: saved MFT scan if current, else from the MFT`));
+    const { scanVolume, MftError } = await import('@bobfrankston/mftwalk');
+    const scanOptions = {
+        onProgress: (done, total) => progress(options, `MFT ${done.toLocaleString()} / ${total.toLocaleString()} records`),
+        cache: { dir: cacheDir() },
+        log: msg => { if (!options.quiet)
+            console.error(styleText(['red'], msg)); },
     };
-    if (cacheAgeMs >= 0 && cacheAgeMs < options.cacheMinutes * 60000)
-        return load('');
-    announce(cacheAgeMs < 0
-        ? `Scanning the MFT of ${volumeName}; no cached scan yet`
-        : `Scanning the MFT of ${volumeName}; the cached scan is ${elapsedText(cacheAgeMs)} old` +
-            (options.cacheMinutes === 0 ? ' (-fresh)' : `, older than -age ${options.cacheMinutes} minutes`));
-    const { MftError } = await import('@bobfrankston/mftwalk');
-    const scannedAt = new Date();
-    let index;
     try {
-        index = await scanToIndex(top, options);
+        const volume = await scanVolume(top, scanOptions);
+        clearProgress(options);
+        return { volume, text: sourceText(volume), stale: volume.origin.changed };
     }
     catch (error) {
         clearProgress(options);
         if (!(error instanceof MftError))
             throw error;
-        // Not swallowed: with an older cache the reason goes into the summary next to its age;
-        // without one it is the failure.
-        if (cacheAgeMs >= 0)
-            return load(`could not rescan (${error.message})`);
-        fail(`Cannot read the MFT: ${error.message}.\ntsfind reads the NTFS MFT (Windows, NTFS, elevated prompt); to walk a tree instead, use tswalk.`);
+        // Not swallowed: the reason goes to stderr and into the summary, and the walk takes over.
+        if (error.code !== 'EPERM')
+            return walkSource(top, `cannot read the MFT of ${driveName}: ${error.message}`, options);
     }
-    let note = '';
+    const elevation = silentElevation();
+    if (!elevation.possible)
+        return walkSource(top, elevation.why, options);
+    if (!options.quiet)
+        console.error(styleText(['blue'], `Updating ${driveName}'s saved MFT scan elevated (UAC here elevates administrators without asking)`));
+    const refreshError = await refreshElevated(driveName, options);
+    if (refreshError)
+        return walkSource(top, `the elevated update of ${driveName}'s saved scan failed: ${refreshError}`, options);
+    const updatedAt = new Date();
     try {
-        if (!options.quiet && process.stderr.isTTY)
-            process.stderr.write('Saving the scan for later runs...');
-        await saveIndex(index, cachePath, scannedAt);
+        // trust: the saved scan was brought up to date a moment ago; changes since then (a busy
+        // C: always has some) would need admin rights again, so they are named, not read.
+        const volume = await scanVolume(top, { ...scanOptions, cache: { dir: cacheDir(), trust: true } });
         clearProgress(options);
+        const text = volume.origin.changed
+            ? `saved MFT scan, brought up to date elevated at ${updatedAt.toLocaleTimeString()} (changes after that are not included)`
+            : sourceText(volume);
+        return { volume, text, stale: false };
     }
     catch (error) {
-        // Not lost: the search goes ahead on the scan in memory, and the summary says the cache was not saved.
         clearProgress(options);
-        note = `not cached: ${error.code ?? error.message}`;
+        if (!(error instanceof MftError))
+            throw error;
+        return walkSource(top, `cannot load ${driveName}'s saved scan after updating it: ${error.message}`, options);
     }
-    return { index, source: { scanned: true, ageMs: Date.now() - scannedAt.getTime(), cachePath, note } };
 }
-/** The entry for `top` in the index, by name from the root, case-insensitively as Windows does; -1 if absent */
-function lookupEntry(index, top) {
-    const rel = top.replace(/^[A-Za-z]:/, '');
-    let at = 0;
-    for (const part of rel.split(/[\\/]+/).filter(Boolean)) {
-        const want = part.toLowerCase();
-        let found = -1;
-        // Children of `at` are the entries right after it, each followed by its own subtree.
-        for (let child = at + 1; child < index.subtreeEnd[at]; child = index.subtreeEnd[child]) {
-            if (index.names[child].toLowerCase() === want) {
-                found = child;
-                break;
-            }
+// ── Walk: the classic way, when the MFT cannot be used ────────────
+/** Run at most `max` jobs at once; the rest wait their turn */
+function makeLimiter(max) {
+    let running = 0;
+    const waiting = [];
+    return async (job) => {
+        if (running >= max)
+            await new Promise(resolve => waiting.push(resolve));
+        else
+            running++;
+        try {
+            return await job();
         }
-        if (found < 0)
-            return -1;
-        at = found;
-    }
-    return at;
+        finally {
+            // Hand the slot straight to the next waiter, or give it back.
+            const next = waiting.shift();
+            if (next)
+                next();
+            else
+                running--;
+        }
+    };
 }
-/** Full path of an entry, under the volume's current drive root */
-function entryPath(index, rootPath, entry) {
-    const parts = [];
-    for (let at = entry; at > 0; at = index.parent[at])
-        parts.push(index.names[at]);
-    return rootPath + parts.reverse().join('\\');
+/**
+ * Hand each match beneath `top` to onFound, reading WALK_CONCURRENCY directories at a time.
+ * Links and junctions are reported like directories but never entered, as in searchVolume.
+ * Returns the directories read and those that could not be (or matches that could not be stat'd).
+ */
+async function walkTree(top, regexes, options, onFound) {
+    const limit = makeLimiter(WALK_CONCURRENCY);
+    const errors = [];
+    let dirs = 0;
+    const visit = async (dir) => {
+        let entries;
+        try {
+            entries = await limit(() => fp.readdir(dir, { withFileTypes: true }));
+        }
+        catch (error) {
+            // Not lost: listed in the summary (count, and the first few by name).
+            errors.push(`${dir}: ${error.code ?? error.message}`);
+            return;
+        }
+        dirs++;
+        progress(options, `Walked ${dirs.toLocaleString()} directories`);
+        const subdirs = [];
+        const stats = [];
+        for (const entry of entries) {
+            const full = path.join(dir, entry.name);
+            const isLink = entry.isSymbolicLink();
+            const isDir = entry.isDirectory() || isLink;
+            if (isDir && !isLink)
+                subdirs.push(full);
+            if (!regexes.some(rx => rx.test(entry.name)))
+                continue;
+            if (isDir && !options.dirs)
+                continue;
+            stats.push(limit(() => fp.lstat(full)).then(st => onFound({ path: full, name: entry.name, size: isDir ? 0 : st.size, mtime: st.mtime, isDir }), 
+            // Not lost: a match that vanished or cannot be read is listed with the summary.
+            (error) => { errors.push(`${full}: ${error.code ?? error.message}`); }));
+        }
+        await Promise.all([...stats, ...subdirs.map(visit)]);
+    };
+    await visit(top);
+    clearProgress(options);
+    return { dirs, errors };
 }
-/** Hand each match beneath `start` to onFound; returns the number of directories searched */
-function searchIndex(index, start, rootPath, regexes, options, onFound) {
+/**
+ * Hand each match beneath `start` to onFound; returns the number of directories searched.
+ * Depth-first through mftwalk's accessors. Links have no children in the volume, so their
+ * contents are never searched; NTFS's own files ($MFT, $Extend ...) are skipped, as readdir does.
+ */
+function searchVolume(volume, start, regexes, options, onFound) {
     let dirs = 1;
-    const end = index.subtreeEnd[start];
-    for (let i = start + 1; i < end; i++) {
-        const flags = index.flags[i];
-        const isDir = (flags & (IndexFlags.Directory | IndexFlags.Link)) !== 0;
-        if (flags & IndexFlags.Directory && !(flags & IndexFlags.Link))
-            dirs++;
-        // Links have no entries beneath them in the index, so their contents are never searched.
-        const name = index.names[i];
-        if (!regexes.some(rx => rx.test(name)))
-            continue;
-        if (isDir && !options.dirs)
-            continue;
-        onFound({ path: entryPath(index, rootPath, i), name, size: isDir ? 0 : index.size[i], mtime: new Date(index.mtime[i]), isDir });
+    const stack = [start];
+    while (stack.length) {
+        const kids = volume.children(stack.pop());
+        for (let k = kids.length - 1; k >= 0; k--) {
+            const id = kids[k];
+            if (volume.isMetafile(id))
+                continue;
+            const isLink = volume.isLink(id);
+            const isDir = volume.isDirectory(id) || isLink;
+            if (isDir && !isLink) {
+                dirs++;
+                stack.push(id);
+            }
+            const name = volume.name(id);
+            if (!regexes.some(rx => rx.test(name)))
+                continue;
+            if (isDir && !options.dirs)
+                continue;
+            onFound({ path: volume.path(id), name, size: isDir ? 0 : volume.size(id), mtime: volume.mtime(id), isDir });
+        }
     }
     return dirs;
 }
@@ -648,8 +679,8 @@ function hogsLines(table, totalBytes, options) {
 }
 async function main() {
     const options = parseArgs(process.argv.slice(2));
-    if (process.platform !== 'win32')
-        fail('tsfind reads the NTFS MFT, so it runs on Windows only; to walk a tree, use tswalk.');
+    if (options.refreshScan)
+        await refreshScanAndExit(options.refreshScan);
     await resolvePositional(options);
     const regexes = compilePatterns(options.patterns);
     let top;
@@ -662,10 +693,6 @@ async function main() {
     catch (error) {
         fail(`Cannot search ${options.top}: ${error.code ?? error.message}`);
     }
-    const drive = /^([A-Za-z]):\\/.exec(top);
-    if (!drive)
-        fail(`${top} is not on a drive letter; tsfind reads a local NTFS volume's MFT. For a network path, use tswalk.`);
-    const rootPath = `${drive[1].toUpperCase()}:\\`;
     // Open -o's file before searching, so a bad path fails now rather than after a long scan.
     let outHandle;
     if (options.outFile) {
@@ -683,12 +710,10 @@ async function main() {
         throw error;
     });
     const start = Date.now();
-    const { index, source } = await getIndex(top, options);
-    const entry = lookupEntry(index, top);
-    if (entry < 0) {
-        fail(`${top} is not in the ${source.scanned ? 'scan' : `cached scan from ${elapsedText(source.ageMs)} ago`}` +
-            `${source.scanned ? '' : '; -fresh rescans'}`);
-    }
+    let source = await getSource(top, options);
+    const entry = source.volume ? source.volume.lookup(top) : -1;
+    if (source.volume && entry < 0)
+        source = walkSource(top, `${top} is not in the MFT data (${source.text})`, options);
     const found = [];
     const byName = new Map();
     const byExt = new Map();
@@ -705,7 +730,14 @@ async function main() {
         addTally(byName, f.name, f.size);
         addTally(byExt, f.isDir ? '(directory)' : path.extname(f.name) || '(none)', f.size);
     };
-    const dirs = searchIndex(index, entry, rootPath, regexes, options, onFound);
+    let dirs;
+    let walkErrors = [];
+    if (source.volume) {
+        dirs = searchVolume(source.volume, entry, regexes, options, onFound);
+    }
+    else {
+        ({ dirs, errors: walkErrors } = await walkTree(top, regexes, options, onFound));
+    }
     const elapsed = Date.now() - start;
     let lines;
     if (options.hogs) {
@@ -729,11 +761,28 @@ async function main() {
     }
     if (!options.quiet) {
         const what = options.dirs ? 'matches' : 'files';
-        const from = source.scanned
-            ? `MFT scanned${source.note ? `, ${source.note}` : ''}`
-            : `cached scan ${elapsedText(source.ageMs)} old${source.note ? `, ${source.note}` : ''}`;
         console.error(`${matchCount.toLocaleString()} ${what}, ${formatBytes(matchBytes)}; ${dirs.toLocaleString()} directories searched; ` +
-            `${elapsedText(elapsed)} (${from})${options.outFile ? `; written to ${path.resolve(options.outFile)}` : ''}`);
+            `${elapsedText(elapsed)}${options.outFile ? `; written to ${path.resolve(options.outFile)}` : ''}`);
+        console.error(styleText([source.stale ? 'red' : 'blue'], `From the ${source.text}.`));
+    }
+    else if (source.stale) {
+        console.error(styleText(['red'], `From the ${source.text}.`));
+    }
+    // Shown even with -q: an incomplete walk is a wrong answer unless it says so.
+    if (walkErrors.length) {
+        console.error(styleText(['red'], `${walkErrors.length.toLocaleString()} could not be read, so the results may be incomplete:`));
+        for (const line of walkErrors.slice(0, WALK_ERRORS_SHOWN))
+            console.error(styleText(['red'], `  ${line}`));
+        if (walkErrors.length > WALK_ERRORS_SHOWN)
+            console.error(styleText(['red'], `  ... and ${(walkErrors.length - WALK_ERRORS_SHOWN).toLocaleString()} more`));
+    }
+    // 2026-11-07: as in tswalk, a drive without a change journal is worth a visible warning,
+    // since every run on it pays for a full MFT read.
+    const volume = source.volume;
+    if (volume && volume.origin.source === 'disk' && !volume.origin.journal && !options.quiet) {
+        const driveName = top.slice(0, 2).toUpperCase();
+        console.error(styleText(['red'], `NOTE: ${driveName} has no change journal, so the saved scan cannot be checked and EVERY run reads the whole MFT.\n` +
+            `  Fix, once, elevated: fsutil usn createjournal ${SUGGESTED_JOURNAL} ${driveName}`));
     }
 }
 if (import.meta.main) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bobfrankston/tsfind",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Find files by name in a directory tree; list them for editing, or count them by name and extension. Optional NTFS MFT reading for big drives.",
   "main": "index.js",
   "bin": {
@@ -32,7 +32,8 @@
   },
   "homepage": "https://github.com/BobFrankston/tsfind#readme",
   "dependencies": {
-    "@bobfrankston/mftwalk": "^0.1.3"
+    "@bobfrankston/dirutil": "^1.6.5",
+    "@bobfrankston/mftwalk": "^0.1.4"
   },
   "devDependencies": {
     "@types/node": "^25.3.0"
@@ -40,12 +41,18 @@
   "publishConfig": {
     "access": "public"
   },
+  "allowScripts": {
+    "file:../../../../projects/NodeJS/dirutil": true,
+    "koffi": true
+  },
   ".dependencies": {
+    "@bobfrankston/dirutil": "file:../../projects/NodeJS/dirutil",
     "@bobfrankston/mftwalk": "file:../mftwalk"
   },
   ".transformedSnapshot": {
     "dependencies": {
-      "@bobfrankston/mftwalk": "^0.1.3"
+      "@bobfrankston/dirutil": "^1.6.5",
+      "@bobfrankston/mftwalk": "^0.1.4"
     }
   }
 }