@git.zone/tsdisk 1.2.1 → 1.4.0

package/ts/index.ts

@@ -3,6 +3,7 @@ export {
   formatBytes,
   collectDiskReport,
   collectProjectToolCacheReport,
+  diagnosticCommandComplete,
   main,
   parseDuOutput,
   runCli,
@@ -10,4 +11,7 @@ export {
 export * from './tsdisk.toolcaches.js';
 export * from './tsdisk.scan.js';
 export * from './tsdisk.cleanup.js';
+export * from './tsdisk.usage.js';
+export { DiskProgressReporter, estimateReclaimableSpace } from './tsdisk.progress.js';
+export type { IDiskProgress, IReclaimEstimate } from './tsdisk.progress.js';
 export type { IRuntimeContext, IDiagnosticSection } from './tsdisk.cli.js';

package/ts/tsdisk.cleanup.ts

@@ -10,6 +10,8 @@ export interface ICleanupAction {
   applyArgs: string[];
   scope: string;
   blocked?: string;
+  sudoArgs?: string[];
+  requiresSudo?: boolean;
 }
 
 export interface ICleanupPlan {
@@ -25,10 +27,11 @@ export interface ICliOptions {
   apply: boolean;
   yes: boolean;
   days: number;
+  sudo?: 'auto' | 'allow' | 'never';
 }
 
 export function parseCliOptions(args: string[]): ICliOptions {
-  const options: ICliOptions = { command: 'diagnose', roots: [], categories: ['rust', 'docker'], json: false, apply: false, yes: false, days: 14 };
+  const options: ICliOptions = { command: 'diagnose', roots: [], categories: ['rust', 'docker'], json: false, apply: false, yes: false, days: 14, sudo: 'auto' };
   let commandSeen = false;
   let dryRun = false;
   let cleanupOption = false;
@@ -44,6 +47,12 @@ export function parseCliOptions(args: string[]): ICliOptions {
     else if (arg === '--apply') { options.apply = true; cleanupOption = true; }
     else if (arg === '--yes' || arg === '-y') { options.yes = true; cleanupOption = true; }
     else if (arg === '--dry-run' || arg === '-n') { dryRun = true; cleanupOption = true; }
+    else if (arg === '--sudo' || arg === '--no-sudo') {
+      const value = arg === '--sudo' ? 'allow' : 'never';
+      if (options.sudo !== 'auto' && options.sudo !== value) throw new Error('--sudo and --no-sudo cannot be combined.');
+      options.sudo = value;
+      cleanupOption = true;
+    }
     else if (['--root', '--only', '--days'].some((flag) => arg === flag || arg.startsWith(`${flag}=`))) {
       const separator = arg.indexOf('=');
       const name = separator < 0 ? arg : arg.slice(0, separator);
@@ -110,6 +119,12 @@ export async function createCleanupPlan(options: ICliOptions): Promise<ICleanupP
         if (!version || (different !== undefined && different !== -1 && version[different] < minimum[different])) {
           action.blocked = `@git.zone/${binary} ${minimum.join('.')} or later is required for the documented prune contract.`;
         }
+        if (category === 'docker' && version && (version[0] > 3 || (version[0] === 3 && version[1] >= 7))) {
+          action.previewArgs = ['prune', '--json'];
+          action.sudoArgs = [...action.applyArgs, '--sudo'];
+        } else if (category === 'docker' && options.sudo === 'allow') {
+          action.blocked = '@git.zone/tsdocker 3.7.0 or later is required for sudo cleanup. Upgrade the project tool first.';
+        }
       } catch {
         action.blocked = `Install a current @git.zone/${binary} in this project before cleanup. No tool is downloaded automatically.`;
       }
@@ -118,3 +133,13 @@ export async function createCleanupPlan(options: ICliOptions): Promise<ICleanupP
   }
   return plan;
 }
+
+/** A versioned owner preview determines whether authentication is needed. */
+export function dockerPreviewRequiresSudo(stdout: string): boolean {
+  const plan = JSON.parse(stdout) as { schemaVersion?: unknown; kind?: unknown; cacheDirs?: Array<{ removal?: { requiresSudo?: unknown } }> };
+  if (plan.schemaVersion !== 1 || plan.kind !== 'tsdocker-prune-plan' || !Array.isArray(plan.cacheDirs)
+    || plan.cacheDirs.some((cache) => typeof cache?.removal?.requiresSudo !== 'boolean')) {
+    throw new Error('Invalid Docker permission preview; refusing cleanup.');
+  }
+  return plan.cacheDirs.some((cache) => cache.removal!.requiresSudo === true);
+}

package/ts/tsdisk.cli.ts

@@ -1,7 +1,10 @@
 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 { parseCliOptions, createCleanupPlan, dockerPreviewRequiresSudo, 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);
@@ -1500,9 +1475,13 @@ function printHelp() {
   console.log('                         Preview owning-tool cleanup; defaults to rust,docker in the current project');
   console.log('  tsdisk cleanup --apply [--yes]     Execute after review; JSON/noninteractive execution requires --yes');
   console.log('  --dry-run              Explicit cleanup preview; cannot be combined with --apply');
-  console.log('  Cleanup uses project-installed tsrust/tsdocker and pnpm store prune, without sudo or raw cache deletion.');
+  console.log('  Cleanup uses project-installed tsrust/tsdocker and pnpm store prune.');
+  console.log('  Docker cleanup asks for sudo when needed (tsdocker >=3.7.0); only approved cache removal is elevated.');
+  console.log('  --sudo                 Allow an existing sudo authorization without a terminal; never accepts a password argument');
+  console.log('  --no-sudo              Refuse cleanup requiring elevated filesystem access');
   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 +1496,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 +1526,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 +1579,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 +1646,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) {
@@ -1637,6 +1663,7 @@ async function runCleanup(options: ICliOptions) {
         console.log(`    ${action.scope}`);
         console.log(`    command: ${JSON.stringify([action.command, ...action.applyArgs])}`);
         if (action.blocked) console.log(`    blocked: ${action.blocked}`);
+        if (action.requiresSudo) console.log('    requires sudo for cache file removal');
       });
       for (const item of [...previews, ...results]) {
         console.log(`[${item.action + 1}] exit ${item.result.code}`);
@@ -1651,6 +1678,15 @@ async function runCleanup(options: ICliOptions) {
     if (action.blocked) continue;
     const result = await runCommand(ctx, action.command, action.previewArgs ?? ['store', 'path'], { cwd: action.cwd, timeoutSeconds: 120 });
     previews.push({ action: index, result });
+    if (action.sudoArgs && result.code === 0 && !result.truncated) {
+      try { action.requiresSudo = dockerPreviewRequiresSudo(result.stdout); }
+      catch (error) { action.blocked = error instanceof Error ? error.message : String(error); }
+      if (options.apply && action.requiresSudo && (options.sudo === 'never' || (!process.stdin.isTTY && options.sudo !== 'allow'))) {
+        action.blocked = options.sudo === 'never'
+          ? 'This cache requires sudo, which --no-sudo disables.'
+          : 'This cache requires sudo. Run cleanup in a terminal for a password prompt, or use --sudo with existing sudo authorization.';
+      }
+    }
   }
   if (plan.actions.some((action) => action.blocked) || previews.some((preview) => preview.result.code !== 0 || preview.result.truncated)) {
     print();
@@ -1663,8 +1699,21 @@ async function runCleanup(options: ICliOptions) {
     if (!process.stdin.isTTY) throw new Error('Noninteractive cleanup requires --apply --yes.');
     if (!await promptYesNo('Run the listed owning-tool cleanup commands?', false)) return;
   }
+  if (plan.actions.some((action) => action.requiresSudo)) {
+    // sudo owns password input and terminal echo; credentials never enter this process.
+    console.error('Approved registry caches require elevated file removal. Authenticating with sudo.');
+    const code = process.stdin.isTTY
+      ? await runInteractive('/usr/bin/sudo', ['-v'], 60)
+      : (await runCommand(ctx, '/usr/bin/sudo', ['-n', '-v'], { timeoutSeconds: 60 })).code;
+    if (code !== 0) {
+      for (const action of plan.actions) if (action.requiresSudo) action.blocked = 'Sudo authentication failed or was cancelled; no cleanup commands were applied.';
+      print();
+      process.exitCode = 1;
+      return;
+    }
+  }
   for (const [index, action] of plan.actions.entries()) {
-    const result = await runCommand(ctx, action.command, action.applyArgs, { cwd: action.cwd, timeoutSeconds: 240 });
+    const result = await runCommand(ctx, action.command, action.requiresSudo ? action.sudoArgs! : action.applyArgs, { cwd: action.cwd, timeoutSeconds: 240 });
     results.push({ action: index, result });
     if (result.code !== 0) { process.exitCode = 1; break; }
   }
@@ -1686,10 +1735,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;
 }