@git.zone/tsdisk 1.2.1 → 1.3.0

package/ts/tsdisk.cli.ts

@@ -2,6 +2,9 @@ import * as plugins from './tsdisk.plugins.js';
 import { commitinfo } from './00_commitinfo_data.js';
 import { scanWorkspace, type IWorkspaceScanOptions, type IScanIssue } from './tsdisk.scan.js';
 import { parseCliOptions, createCleanupPlan, type ICliOptions } from './tsdisk.cleanup.js';
+import { measureDiskUsage, normalizeScanRoots, type IUsageReport } from './tsdisk.usage.js';
+import { DiskProgressReporter, estimateReclaimableSpace, formatBytes, type IDiskProgress } from './tsdisk.progress.js';
+export { formatBytes } from './tsdisk.progress.js';
 export type { IWorkspaceScanOptions } from './tsdisk.scan.js';
 import {
   classifyToolCachePath,
@@ -23,6 +26,7 @@ interface IRunOptions {
 }
 
 export interface IRuntimeContext {
+  onProgress?: (progress: Partial<IDiskProgress>) => void;
   runningAsRoot: boolean;
   sudoAvailable: boolean;
   sudoChecked: boolean;
@@ -89,24 +93,6 @@ function firstLines(text: string, maxLines = 8): string {
   return text.trim().split(/\r?\n/).slice(0, maxLines).join('\n');
 }
 
-export function formatBytes(bytes: number): string {
-  if (!Number.isFinite(bytes) || bytes < 0) {
-    return 'n/a';
-  }
-
-  const units = ['B', 'KiB', 'MiB', 'GiB', 'TiB'];
-  let value = bytes;
-  let unitIndex = 0;
-
-  while (value >= 1024 && unitIndex < units.length - 1) {
-    value = value / 1024;
-    unitIndex++;
-  }
-
-  const decimals = unitIndex === 0 || value >= 100 ? 0 : value >= 10 ? 1 : 2;
-  return `${value.toFixed(decimals)} ${units[unitIndex]}`;
-}
-
 function printSizeLine(label: string, bytes: number) {
   console.log(`${formatBytes(bytes).padStart(10)}  ${label}`);
 }
@@ -523,6 +509,7 @@ async function runRootInteractive(
   args: string[],
   timeoutSeconds?: number,
 ): Promise<number> {
+  ctx.onProgress?.({ stage: `${command} ${args.slice(0, 3).join(' ')}` });
   let executable = command;
   let finalArgs = args;
 
@@ -561,6 +548,7 @@ async function runCommand(
   args: string[],
   options: IRunOptions = {},
 ): Promise<ICommandResult> {
+  ctx.onProgress?.({ stage: `${command} ${args.slice(0, 3).join(' ')}` });
   let executable = command;
   let finalArgs = [...args];
   const env: NodeJS.ProcessEnv = {};
@@ -691,17 +679,23 @@ async function getWorkspaceRoots(): Promise<string[]> {
   if (cwd && cwd !== '/') {
     roots.add(cwd);
   }
-  return [...roots];
+  return await normalizeScanRoots([...roots]);
 }
 
 export async function collectProjectToolCacheReport(ctx: IRuntimeContext, roots?: string[]) {
   const findings: IToolCacheFinding[] = [];
   const issues: IScanIssue[] = [];
-  const scanRoots = roots?.length ? roots : await getWorkspaceRoots();
+  const issueCounts: Partial<Record<IScanIssue['reason'], number>> = {};
+  const usagePriorityPaths: string[] = [];
+  const scanRoots = await normalizeScanRoots(roots?.length ? roots : await getWorkspaceRoots());
   for (const root of scanRoots) {
-    const result = await scanWorkspace(root, { maxDepth: 8, timeoutMs: 45_000, maxEntries: 50_000 });
+    const result = await scanWorkspace(root, { maxDepth: 8, timeoutMs: 45_000, maxEntries: 50_000,
+      onProgress: (partial) => ctx.onProgress?.({ stage: `discovering ${root}`, cacheCount: findings.length + partial.findings.length, reclaim: estimateReclaimableSpace([...findings, ...partial.findings]) }),
+    });
     findings.push(...result.findings);
+    usagePriorityPaths.push(...result.usagePriorityPaths);
     issues.push(...result.issues);
+    for (const [reason, count] of Object.entries(result.issueCounts)) issueCounts[reason] = (issueCounts[reason] ?? 0) + count;
   }
   const unique = [...new Map(findings.map((finding) => [plugins.path.resolve(finding.path), finding])).values()];
   const deadline = Date.now() + toolCacheSizingTimeoutMs;
@@ -716,36 +710,17 @@ export async function collectProjectToolCacheReport(ctx: IRuntimeContext, roots?
     const size = result.code === 0 ? parseDuOutput(result.stdout)[0] : undefined;
     if (size) finding.bytes = size.bytes;
     else issues.push({ path: finding.path, reason: 'size-unavailable', detail: result.stderr.trim() || 'du failed or returned no size.' });
+    ctx.onProgress?.({ cacheCount: unique.length, reclaim: estimateReclaimableSpace(unique) });
   }
-  return { roots: scanRoots, toolCaches: unique.sort((a, b) => (b.bytes ?? 0) - (a.bytes ?? 0)), issues, complete: issues.length === 0 };
+  issueCounts['size-unavailable'] = issues.filter((issue) => issue.reason === 'size-unavailable').length;
+  ctx.onProgress?.({ cacheCount: unique.length, reclaim: estimateReclaimableSpace(unique) });
+  return { roots: scanRoots, toolCaches: unique.sort((a, b) => (b.bytes ?? 0) - (a.bytes ?? 0)), usagePriorityPaths, issues, issueCounts, complete: issues.length === 0 };
 }
 
 export async function collectProjectToolCacheDiagnostics(ctx: IRuntimeContext): Promise<IToolCacheFinding[]> {
   return (await collectProjectToolCacheReport(ctx)).toolCaches;
 }
 
-async function printProjectToolCacheDiagnostics(ctx: IRuntimeContext) {
-  section('Project Tool Cache Diagnostics');
-  const roots = await getWorkspaceRoots();
-  if (roots.length === 0) {
-    console.log('No workspace roots found.');
-    return;
-  }
-  progress(`Scanning workspace roots: ${roots.join(', ')}`);
-  const report = await collectProjectToolCacheReport(ctx);
-  for (const issue of report.issues) console.log(`Incomplete scan: ${issue.reason}: ${issue.path}: ${issue.detail}`);
-  const findings = report.toolCaches;
-  if (findings.length === 0) {
-    console.log('No known project-local tool caches found.');
-    return;
-  }
-
-  for (const finding of findings) {
-    console.log(`${finding.bytes === undefined ? "unknown" : formatBytes(finding.bytes)}  ${finding.ownerGuess} ${finding.kind} [${finding.risk}] ${finding.path}`);
-    console.log(`           suggested: ${finding.suggestedCleanupCommand}`);
-  }
-}
-
 async function pathExistsForDu(ctx: IRuntimeContext, path: string, asRoot: boolean): Promise<boolean> {
   if (!asRoot) {
     return await pathExists(path);
@@ -1503,6 +1478,7 @@ function printHelp() {
   console.log('  Cleanup uses project-installed tsrust/tsdocker and pnpm store prune, without sudo or raw cache deletion.');
   console.log('  --days applies only to Rust targets. Docker uses its owner checks; pnpm uses reference tracking.');
   console.log('  scan exit codes: 0 complete, 2 incomplete, 1 invalid input/failure.');
+  console.log('  Live progress updates every 5 seconds (stderr with --json). Potential cleanup requires owner review.');
   console.log('  tsdisk --help          Show this help');
   console.log('  tsdisk --version       Show the version');
   console.log('');
@@ -1517,8 +1493,19 @@ function printHelp() {
 
 export async function main() {
   const ctx = await initContext();
+  const reporter = new DiskProgressReporter((line) => console.log(line));
+  ctx.onProgress = (update) => reporter.update(update);
+  reporter.start();
+  try { await runHumanReport(ctx); }
+  finally { reporter.stop(); }
+}
 
+async function runHumanReport(ctx: IRuntimeContext) {
   await printDiskOverview(ctx);
+  const caches = await collectProjectToolCacheReport(ctx);
+  const usage = await collectWorkspaceUsage(ctx, caches);
+  printWorkspaceUsage(usage);
+  console.log(`Potential cleanup: ${formatBytes(estimateReclaimableSpace(caches.toolCaches).candidateBytes)} of cache candidates; owner review required. Confirmed reclaimable: unknown.`);
   await ensureSudo(ctx);
   await printNcduInsights(ctx);
 
@@ -1536,7 +1523,9 @@ export async function main() {
   await printDuTree(ctx, 'Target Local Share Breakdown', `${ctx.targetHome}/.local/share`, true);
   await printDuTree(ctx, 'Target Cache Breakdown', `${ctx.targetHome}/.cache`, true);
   await printConfiguredToolPaths(ctx);
-  await printProjectToolCacheDiagnostics(ctx);
+  section('Project Tool Cache Diagnostics');
+  for (const cache of caches.toolCaches) console.log(`${cache.bytes === undefined ? 'unknown' : formatBytes(cache.bytes)}  ${JSON.stringify(cache.path)}\n  ${cache.suggestedCleanupCommand}`);
+  if (!caches.complete) console.log(`Discovery incomplete: ${JSON.stringify(caches.issueCounts)}`);
   await printKnownSizes(ctx, 'Known User Caches', [
     { label: 'rootless Docker data', path: `${ctx.targetHome}/.local/share/docker` },
     { label: 'pnpm store', path: `${ctx.targetHome}/.local/share/pnpm` },
@@ -1587,27 +1576,61 @@ export async function main() {
 
 export interface IDiagnosticSection {
   name: string;
+  kind?: 'command' | 'derived';
+  derivedFrom?: 'usage.entries';
   command: string;
   args: string[];
   result: ICommandResult;
   complete: boolean;
 }
 
+export function diagnosticCommandComplete(command: string, result: ICommandResult): boolean {
+  return !result.truncated && !result.stderr.trim() && (result.code === 0 || (command === 'lsof' && result.code === 1));
+}
+
+async function collectWorkspaceUsage(ctx: IRuntimeContext, caches: Awaited<ReturnType<typeof collectProjectToolCacheReport>>) {
+  ctx.onProgress?.({ stage: 'measuring workspace files and directories' });
+  const usage = await measureDiskUsage(caches.roots, {
+    timeoutSeconds: ctx.duTimeoutSeconds,
+    trackedPaths: caches.toolCaches.map((finding) => finding.path),
+    priorityPaths: caches.usagePriorityPaths,
+    onProgress: (partial) => ctx.onProgress?.({
+      stage: 'measuring workspace files and directories', measuredBytes: partial.measuredBytes,
+      largest: partial.snapshot().filter((entry) => !caches.roots.includes(entry.path)).slice(0, 3),
+    }),
+  });
+  return usage;
+}
+
+function printWorkspaceUsage(usage: IUsageReport) {
+  section(`Workspace Disk Usage (${usage.complete ? 'complete' : 'partial; + means a lower bound'})`);
+  for (const entry of usage.entries.slice(0, 30)) console.log(`${formatBytes(entry.bytes)}${entry.complete ? '' : '+'}  ${JSON.stringify(entry.path)}`);
+  if (usage.stderr) console.log(firstLines(usage.stderr));
+}
+
 export async function collectDiskReport(ctx: IRuntimeContext, roots?: string[]) {
   const caches = await collectProjectToolCacheReport(ctx, roots);
+  const usage = await collectWorkspaceUsage(ctx, caches);
+  const reclaim = estimateReclaimableSpace(caches.toolCaches);
   const sections: IDiagnosticSection[] = [];
   const deadline = Date.now() + 120_000;
   const inspect = async (name: string, command: string, args: string[]) => {
     const result = Date.now() >= deadline
       ? { code: 124, stdout: '', stderr: 'Diagnostic command budget exhausted.' }
       : await runCommand(ctx, command, args, { timeoutSeconds: Math.max(1, Math.min(15, Math.floor((deadline - Date.now()) / 1000))) });
-    const complete = !result.truncated && (result.code === 0 || (command === 'lsof' && result.code === 1 && !result.stderr.trim()));
-    sections.push({ name, command, args, result, complete });
+    const complete = diagnosticCommandComplete(command, result);
+    sections.push({ name, kind: 'command', command, args, result, complete });
     return result;
   };
   await inspect('filesystems', 'df', ['-hT']);
   await inspect('mounts', 'findmnt', ['--json']);
-  for (const root of caches.roots) await inspect(`workspace:${root}`, 'du', ['-x', '--max-depth=1', '--block-size=1', '--', root]);
+  for (const root of caches.roots) {
+    const entries = usage.entries.filter((entry) => entry.path === root || entry.path.startsWith(root === '/' ? '/' : `${root}/`));
+    const truncated = entries.length > 100;
+    sections.push({ name: `workspace:${root}`, kind: 'derived', derivedFrom: 'usage.entries', command: 'usage-summary', args: [], complete: usage.complete && !truncated,
+      result: { code: usage.code, stderr: usage.stderr, truncated, stdout: entries.slice(0, 100).map((entry) => `${entry.bytes}\t${entry.path}\n`).join('') },
+    });
+  }
   for (const path of ['/', ctx.targetHome, `${ctx.targetHome}/.cache`, `${ctx.targetHome}/.local/share`, '/var', '/var/lib']) {
     await inspect(`usage:${path}`, 'du', ['-x', '--max-depth=1', '--block-size=1', '--', path]);
   }
@@ -1620,7 +1643,7 @@ export async function collectDiskReport(ctx: IRuntimeContext, roots?: string[])
       await inspect(`docker:${context}`, 'docker', ['--context', context, 'system', 'df', '-v']);
     }
   }
-  return { schemaVersion: 1, generatedAt: new Date().toISOString(), ...caches, sections, complete: caches.complete && sections.every((section) => section.complete) };
+  return { schemaVersion: 1, generatedAt: new Date().toISOString(), ...caches, usage, reclaim, sections, complete: caches.complete && usage.complete && sections.every((section) => section.complete) };
 }
 
 async function runCleanup(options: ICliOptions) {
@@ -1686,10 +1709,18 @@ export async function runCli(args = process.argv.slice(2)) {
     if (options.command === 'version') { console.log(commitinfo.version); return; }
     if (options.command === 'cleanup') { await runCleanup(options); return; }
     if (options.command === 'scan') {
-      const report = await collectDiskReport(await initContext(), options.roots);
+      const reporter = new DiskProgressReporter((line) => options.json ? process.stderr.write(`${line}\n`) : console.log(line));
+      const ctx = await initContext();
+      ctx.onProgress = (update) => reporter.update(update);
+      reporter.start();
+      let report: Awaited<ReturnType<typeof collectDiskReport>>;
+      try { report = await collectDiskReport(ctx, options.roots); }
+      finally { reporter.stop(); }
       if (options.json) console.log(JSON.stringify(report, null, 2));
       else {
         console.log(`Scan ${report.complete ? 'complete' : 'incomplete'}: ${report.toolCaches.length} tool caches`);
+        printWorkspaceUsage(report.usage);
+        console.log(`Potential cleanup: ${formatBytes(report.reclaim.candidateBytes)} (${report.reclaim.unknownSizeCount} caches unsized); owner review required. Confirmed reclaimable: unknown.`);
         for (const finding of report.toolCaches) console.log(`${finding.bytes === undefined ? 'unknown' : formatBytes(finding.bytes)}  [${finding.risk}] ${finding.path}\n  ${finding.suggestedCleanupCommand}`);
         for (const issue of report.issues) console.log(`${issue.reason}: ${issue.path}: ${issue.detail}`);
         for (const section of report.sections) console.log(`\n${section.name} [${section.complete ? 'complete' : 'incomplete'}]\n${section.result.stdout}${section.result.stderr}`);

package/ts/tsdisk.progress.ts

@@ -0,0 +1,78 @@
+import { containsPath, type IUsageEntry } from './tsdisk.usage.js';
+import type { IToolCacheFinding } from './tsdisk.toolcaches.js';
+
+export interface IReclaimEstimate {
+  candidateBytes: number;
+  unknownSizeCount: number;
+  protectedCount: number;
+  confirmedReclaimableBytes: null;
+  status: 'owner-review-required';
+}
+
+/** Do not sum parents and children, or treat a protected descendant as removable. */
+export function estimateReclaimableSpace(findings: IToolCacheFinding[]): IReclaimEstimate {
+  const protectedPaths = findings.filter((finding) => finding.marker?.safeToPrune === false).map((finding) => finding.path);
+  const candidates = findings.filter((finding) => !protectedPaths.some((path) => containsPath(path, finding.path) || containsPath(finding.path, path)));
+  const selected: IToolCacheFinding[] = [];
+  for (const finding of [...candidates].sort((a, b) => a.path.length - b.path.length)) {
+    if (finding.bytes === undefined || selected.some((parent) => containsPath(parent.path, finding.path))) continue;
+    selected.push(finding);
+  }
+  return {
+    candidateBytes: selected.reduce((sum, finding) => sum + (finding.bytes ?? 0), 0),
+    unknownSizeCount: candidates.filter((finding) => finding.bytes === undefined).length,
+    protectedCount: protectedPaths.length,
+    confirmedReclaimableBytes: null,
+    status: 'owner-review-required',
+  };
+}
+
+export interface IDiskProgress {
+  stage: string;
+  cacheCount: number;
+  measuredBytes: number;
+  reclaim: IReclaimEstimate;
+  largest: IUsageEntry[];
+}
+
+export function formatBytes(bytes: number): string {
+  if (!Number.isFinite(bytes) || bytes < 0) return 'n/a';
+  const units = ['B', 'KiB', 'MiB', 'GiB', 'TiB'];
+  let value = bytes;
+  let index = 0;
+  while (value >= 1024 && index < units.length - 1) { value /= 1024; index++; }
+  return `${value.toFixed(index === 0 || value >= 100 ? 0 : value >= 10 ? 1 : 2)} ${units[index]}`;
+}
+
+/** Timer ownership is explicit; callers stop it in finally even on failure. */
+export class DiskProgressReporter {
+  private timer?: ReturnType<typeof setInterval>;
+  private startedAt = Date.now();
+  private state: IDiskProgress = { stage: 'starting', cacheCount: 0, measuredBytes: 0, reclaim: estimateReclaimableSpace([]), largest: [] };
+
+  constructor(private write: (line: string) => void) {}
+
+  public update(update: Partial<IDiskProgress>) { Object.assign(this.state, update); }
+
+  public start() {
+    if (this.timer) return;
+    this.startedAt = Date.now();
+    this.print();
+    this.timer = setInterval(() => this.print(), 5000);
+    this.timer.unref();
+  }
+
+  private print() {
+    const state = this.state;
+    const top = state.largest.slice(0, 3).map((entry) => `${formatBytes(entry.bytes)}${entry.complete ? '' : '+'} ${JSON.stringify(entry.path)}`).join('; ');
+    this.write(`[tsdisk ${Math.floor((Date.now() - this.startedAt) / 1000)}s] ${state.stage} | measured ${formatBytes(state.measuredBytes)} | ${state.cacheCount} caches | potential cleanup ${formatBytes(state.reclaim.candidateBytes)} (owner review; ${state.reclaim.unknownSizeCount} unsized) | confirmed reclaimable: unknown${top ? ` | largest: ${top}` : ''}`);
+  }
+
+  public stop(stage = 'finished') {
+    if (!this.timer) return;
+    clearInterval(this.timer);
+    this.timer = undefined;
+    this.state.stage = stage;
+    this.print();
+  }
+}

package/ts/tsdisk.scan.ts

@@ -5,6 +5,7 @@ export interface IWorkspaceScanOptions {
   maxDepth: number;
   timeoutMs: number;
   maxEntries: number;
+  onProgress?: (result: IWorkspaceScanResult) => void;
 }
 
 export interface IScanIssue {
@@ -19,6 +20,8 @@ export interface IWorkspaceScanResult {
   issues: IScanIssue[];
   complete: boolean;
   visitedEntries: number;
+  issueCounts: Partial<Record<IScanIssue['reason'], number>>;
+  usagePriorityPaths: string[];
 }
 
 const excludedDirectories = new Set(['.git', 'node_modules', 'dist_ts', 'dist_ts_web', 'coverage', '.pnpm-store']);
@@ -30,12 +33,13 @@ export async function scanWorkspace(root: string, options: IWorkspaceScanOptions
       throw new Error(`Invalid scan option ${name}: ${value}`);
     }
   }
-  const result: IWorkspaceScanResult = { root: plugins.path.resolve(root), findings: [], issues: [], complete: true, visitedEntries: 0 };
+  const result: IWorkspaceScanResult = { root: plugins.path.resolve(root), findings: [], issues: [], issueCounts: {}, usagePriorityPaths: [], complete: true, visitedEntries: 0 };
   const deadline = Date.now() + options.timeoutMs;
   let stopped = false;
   const issue = (path: string, reason: IScanIssue['reason'], detail: string) => {
     result.complete = false;
-    result.issues.push({ path, reason, detail });
+    result.issueCounts[reason] = (result.issueCounts[reason] ?? 0) + 1;
+    if (result.issues.length < 200) result.issues.push({ path, reason, detail });
   };
   const limited = (path: string) => {
     if (stopped) return true;
@@ -58,6 +62,8 @@ export async function scanWorkspace(root: string, options: IWorkspaceScanOptions
     issue(result.root, 'read-error', error instanceof Error ? error.message : String(error));
     return result;
   }
+  const queue: Array<{ directory: string; depth: number }> = [{ directory: result.root, depth: 0 }];
+  let queueLimited = false;
   const visit = async (directory: string, depth: number): Promise<void> => {
     if (limited(directory)) return;
     result.visitedEntries++;
@@ -71,11 +77,14 @@ export async function scanWorkspace(root: string, options: IWorkspaceScanOptions
         issue(directory, 'mount-boundary', 'Different filesystem skipped.');
         return;
       }
-      const entries = await plugins.fs.readdir(directory, { withFileTypes: true });
+      if (plugins.path.basename(directory) === '.nogit') result.usagePriorityPaths.push(directory);
       let marker;
-      if (entries.some((entry) => entry.name === toolCacheMarkerFile)) {
-        const markerPath = plugins.path.join(directory, toolCacheMarkerFile);
-        const markerStat = await plugins.fs.lstat(markerPath);
+      const markerPath = plugins.path.join(directory, toolCacheMarkerFile);
+      const markerStat = await plugins.fs.lstat(markerPath).catch((error: NodeJS.ErrnoException) => {
+        if (error.code === 'ENOENT') return undefined;
+        throw error;
+      });
+      if (markerStat) {
         if (!markerStat.isFile() || markerStat.size > 65536) {
           issue(markerPath, 'invalid-marker', 'Marker must be a regular file of at most 64 KiB.');
         } else {
@@ -88,18 +97,22 @@ export async function scanWorkspace(root: string, options: IWorkspaceScanOptions
       if (classification) result.findings.push({ path: directory, ...classification });
       // Cache contents are not workspaces. Registry session directories can carry their own markers.
       if (classification && heuristic?.kind !== 'docker-registry-cache') return;
-      const children = entries.filter((entry) => !excludedDirectories.has(entry.name));
-      if (depth >= options.maxDepth) {
-        if (children.some((entry) => entry.isDirectory() || entry.isSymbolicLink())) issue(directory, 'depth-limit', `Maximum scan depth ${options.maxDepth} reached.`);
-        return;
-      }
-      for (const child of children) {
+      let enumerated = 0;
+      const children = await plugins.fs.opendir(directory);
+      for await (const child of children) {
+        // A huge flat directory must not consume the budget of sibling projects.
+        if (++enumerated > 4096) {
+          issue(directory, 'entry-limit', 'Directory listing stopped at 4096 entries; sibling directories are still scanned.');
+          break;
+        }
+        if (excludedDirectories.has(child.name)) continue;
+        if (!child.isDirectory() && !child.isSymbolicLink()) continue;
+        if (depth >= options.maxDepth) {
+          issue(directory, 'depth-limit', `Maximum scan depth ${options.maxDepth} reached.`);
+          break;
+        }
         const childPath = plugins.path.join(directory, child.name);
         if (limited(childPath)) return;
-        if (!child.isDirectory() && !child.isSymbolicLink()) {
-          result.visitedEntries++;
-          continue;
-        }
         if (child.isSymbolicLink()) {
           result.visitedEntries++;
           issue(childPath, 'symlink', 'Symbolic link skipped.');
@@ -113,12 +126,26 @@ export async function scanWorkspace(root: string, options: IWorkspaceScanOptions
           });
           if (!sessionMarker) { result.visitedEntries++; continue; }
         }
-        await visit(childPath, depth + 1);
+        if (queue.length >= options.maxEntries) {
+          if (!queueLimited) issue(directory, 'entry-limit', 'Directory queue budget exhausted; already queued siblings are still scanned.');
+          queueLimited = true;
+          continue;
+        }
+        queue.push({ directory: childPath, depth: depth + 1 });
       }
     } catch (error) {
       issue(directory, 'read-error', error instanceof Error ? error.message : String(error));
     }
   };
-  await visit(result.root, 0);
+  // Breadth first: canonical projects precede deeply nested retained worktrees.
+  let lastProgress = 0;
+  for (let index = 0; index < queue.length && !stopped; index++) {
+    await visit(queue[index].directory, queue[index].depth);
+    if (Date.now() - lastProgress >= 250) {
+      options.onProgress?.(result);
+      lastProgress = Date.now();
+    }
+  }
+  options.onProgress?.(result);
   return result;
 }

package/ts/tsdisk.usage.ts

@@ -0,0 +1,199 @@
+import * as plugins from './tsdisk.plugins.js';
+
+export interface IUsageEntry {
+  path: string;
+  bytes: number;
+  complete: boolean;
+}
+
+export interface IUsageReport {
+  roots: string[];
+  measuredBytes: number;
+  entries: IUsageEntry[];
+  records: number;
+  complete: boolean;
+  code: number;
+  stderr: string;
+}
+
+export function containsPath(parent: string, child: string): boolean {
+  const relative = plugins.path.relative(parent, child);
+  return relative === '' || (!relative.startsWith(`..${plugins.path.sep}`) && relative !== '..' && !plugins.path.isAbsolute(relative));
+}
+
+/** Preserve explicitly selected nested mounts; subsume overlapping roots on the same device. */
+export async function normalizeScanRoots(roots: string[]): Promise<string[]> {
+  const unique = [...new Set(roots.map((root) => plugins.path.resolve(root)))].sort((a, b) => a.length - b.length || a.localeCompare(b));
+  const accepted: Array<{ path: string; dev?: number }> = [];
+  for (const path of unique) {
+    const stat = await plugins.fs.lstat(path).catch(() => undefined);
+    const real = await plugins.fs.realpath(path).catch(() => undefined);
+    const dev = stat?.isDirectory() && real === path ? stat.dev : undefined;
+    if (dev !== undefined && accepted.some((parent) => parent.dev === dev && containsPath(parent.path, path))) continue;
+    accepted.push({ path, dev });
+  }
+  return accepted.map((root) => root.path);
+}
+
+/** GNU du emits files immediately and inclusive directory totals on completion.
+ * Reconcile each completed directory with its observed children, rather than
+ * adding inclusive totals twice. The active ancestor chain survives a timeout.
+ */
+export class UsageAccumulator {
+  private pending = '';
+  private active = new Map<string, number>();
+  private largest = new Map<string, IUsageEntry>();
+  private tracked = new Map<string, IUsageEntry>();
+  private minimumLargestBytes = 0;
+  private operandBytes = new Map<string, number>();
+  private accountingRoots: string[];
+  private currentRoot?: string;
+  public measuredBytes = 0;
+  public records = 0;
+  public currentPath = '';
+
+  constructor(private roots: string[], private trackedPaths: Set<string> = new Set(), private priorityPaths: string[] = []) {
+    this.roots = [...roots].sort((a, b) => b.length - a.length);
+    if (roots.some((root) => plugins.path.resolve(root) !== root) || priorityPaths.some((path) => !roots.some((root) => root !== path && containsPath(root, path)))) {
+      throw new Error('Usage accounting requires normalized roots and strict descendant priority paths.');
+    }
+    this.accountingRoots = [...priorityPaths, ...roots].sort((a, b) => b.length - a.length);
+    this.trackedPaths = new Set([...trackedPaths, ...roots, ...priorityPaths]);
+  }
+
+  public consume(chunk: string) {
+    this.pending += chunk;
+    let start = 0;
+    for (;;) {
+      const end = this.pending.indexOf('\0', start);
+      if (end < 0) break;
+      this.record(this.pending.slice(start, end));
+      start = end + 1;
+    }
+    this.pending = this.pending.slice(start);
+    if (this.pending.length > 1024 * 1024) throw new Error('Invalid du record exceeds 1 MiB.');
+  }
+
+  private record(record: string) {
+    const separator = record.indexOf('\t');
+    const bytes = Number(record.slice(0, separator));
+    const path = record.slice(separator + 1);
+    const matches = (candidate: string) => path === candidate || path.startsWith(candidate === '/' ? '/' : `${candidate}/`);
+    const root = this.currentRoot && matches(this.currentRoot) ? this.currentRoot : this.accountingRoots.find(matches);
+    if (separator < 1 || !Number.isSafeInteger(bytes) || bytes < 0 || !plugins.path.isAbsolute(path) || !root) throw new Error('Invalid du output.');
+    this.records++;
+    this.currentPath = path;
+    this.currentRoot = path === root ? undefined : root;
+    const delta = bytes - (this.active.get(path) ?? 0);
+    this.active.delete(path);
+    this.measuredBytes += delta;
+    this.operandBytes.set(root, (this.operandBytes.get(root) ?? 0) + delta);
+    if (path !== root) {
+      for (let parent = plugins.path.dirname(path); ; parent = plugins.path.dirname(parent)) {
+        this.active.set(parent, (this.active.get(parent) ?? 0) + delta);
+        if (parent === root) break;
+      }
+    }
+    const entry = { path, bytes, complete: true };
+    if (this.trackedPaths.has(path)) this.tracked.set(path, entry);
+    // Retain only the largest completed paths, not millions of file records.
+    if (this.largest.size < 100 || bytes > this.minimumLargestBytes) {
+      this.largest.set(path, entry);
+      if (this.largest.size > 100) {
+        const sorted = [...this.largest.values()].sort((a, b) => b.bytes - a.bytes);
+        this.largest = new Map(sorted.slice(0, 100).map((item) => [item.path, item]));
+      }
+      this.minimumLargestBytes = Math.min(...[...this.largest.values()].map((item) => item.bytes));
+    }
+  }
+
+  public snapshot(): IUsageEntry[] {
+    const entries = new Map([...this.largest, ...this.tracked].map(([path, entry]) => [path, { ...entry }]));
+    for (const [path, bytes] of this.active) entries.set(path, { path, bytes, complete: false });
+    // du charges an overlapping subtree to its first operand and omits it from
+    // later ancestor totals. Restore those inclusive totals for display only;
+    // measuredBytes remains the native, deduplicated sum of operand contributions.
+    for (const priority of this.priorityPaths) {
+      const bytes = this.operandBytes.get(priority);
+      const root = this.roots.find((candidate) => containsPath(candidate, priority));
+      if (bytes === undefined || !root) continue;
+      for (let parent = plugins.path.dirname(priority); ; parent = plugins.path.dirname(parent)) {
+        const entry = entries.get(parent) ?? { path: parent, bytes: 0, complete: false };
+        entry.bytes += bytes;
+        entries.set(parent, entry);
+        if (parent === root) break;
+      }
+    }
+    return [...entries.values()].sort((a, b) => b.bytes - a.bytes);
+  }
+
+  public get endedOnRecordBoundary() { return this.pending.length === 0; }
+}
+
+export interface IUsageOptions {
+  timeoutSeconds: number;
+  trackedPaths?: string[];
+  priorityPaths?: string[];
+  onProgress?: (usage: UsageAccumulator) => void;
+}
+
+/** One streaming native pass; no output export, no symlink traversal, no raw file content reads. */
+export async function measureDiskUsage(roots: string[], options: IUsageOptions): Promise<IUsageReport> {
+  if (!Number.isFinite(options.timeoutSeconds) || options.timeoutSeconds <= 0) throw new Error('Invalid usage timeout.');
+  const valid: string[] = [];
+  const devices = new Map<string, number>();
+  const errors: string[] = [];
+  for (const root of await normalizeScanRoots(roots)) {
+    try {
+      const stat = await plugins.fs.lstat(root);
+      if (!stat.isDirectory() || await plugins.fs.realpath(root) !== root) throw new Error('Usage roots must be real directories without symlink ancestors.');
+      valid.push(root);
+      devices.set(root, stat.dev);
+    } catch (error) { errors.push(`${root}: ${error instanceof Error ? error.message : String(error)}`); }
+  }
+  const priorities: string[] = [];
+  for (const path of await normalizeScanRoots(options.priorityPaths ?? [])) {
+    const root = [...valid].reverse().find((root) => root !== path && containsPath(root, path));
+    if (!root) continue;
+    const real = await plugins.fs.realpath(path).catch(() => undefined);
+    const stat = await plugins.fs.lstat(path).catch(() => undefined);
+    if (real === path && stat?.isDirectory() && stat.dev === devices.get(root)) priorities.push(path);
+  }
+  // Measure retained project artifacts before broad dependency/source trees.
+  // This changes order only: remaining paths are visited by the final roots.
+  priorities.sort((a, b) => b.split(plugins.path.sep).length - a.split(plugins.path.sep).length || a.localeCompare(b));
+  let argumentBytes = valid.reduce((sum, path) => sum + Buffer.byteLength(path) + 1, 0);
+  const argumentLimit = priorities.findIndex((path) => (argumentBytes += Buffer.byteLength(path) + 1) > 128 * 1024);
+  if (argumentLimit >= 0) priorities.splice(argumentLimit);
+  const usage = new UsageAccumulator(valid, new Set(options.trackedPaths), priorities);
+  let stderr = errors.join('\n');
+  let malformed = false;
+  const code = valid.length ? await new Promise<number>((resolve) => {
+    const child = plugins.spawn('timeout', ['--kill-after=5s', `${options.timeoutSeconds}s`, 'du', '-a', '-0', '-x', '-B1', '--', ...priorities, ...valid], { stdio: ['ignore', 'pipe', 'pipe'], env: { ...process.env, LC_ALL: 'C' } });
+    child.stdout.setEncoding('utf8');
+    let lastNotification = 0;
+    child.stdout.on('data', (chunk: string) => {
+      if (malformed) return;
+      try {
+        usage.consume(chunk);
+        if (Date.now() - lastNotification >= 250) {
+          options.onProgress?.(usage);
+          lastNotification = Date.now();
+        }
+      } catch (error) {
+        malformed = true;
+        stderr += `\n${error instanceof Error ? error.message : String(error)}`;
+        // Signal timeout, which forwards termination to its managed process group.
+        child.kill('SIGTERM');
+      }
+    });
+    child.stderr.setEncoding('utf8');
+    child.stderr.on('data', (chunk: string) => { if (stderr.length < 65536) stderr += chunk.slice(0, 65536 - stderr.length); });
+    child.on('error', (error) => { stderr += `\n${error.message}`; });
+    child.on('close', (exitCode) => resolve(exitCode ?? 1));
+  }) : 1;
+  options.onProgress?.(usage);
+  const complete = code === 0 && !stderr.trim() && !malformed && usage.endedOnRecordBoundary;
+  const entries = usage.snapshot().map((entry) => ({ ...entry, complete: entry.complete && complete }));
+  return { roots: valid, measuredBytes: usage.measuredBytes, entries, records: usage.records, complete, code, stderr };
+}