@git.zone/tsdisk 1.1.0 → 1.2.1

package/ts/tsdisk.cli.ts

@@ -1,23 +1,25 @@
 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';
+export type { IWorkspaceScanOptions } from './tsdisk.scan.js';
 import {
   classifyToolCachePath,
-  parseToolCacheMarker,
-  toolCacheMarkerFile,
   type IToolCacheFinding,
-  type IToolCacheMarker,
 } from './tsdisk.toolcaches.js';
 
 interface ICommandResult {
   code: number;
   stdout: string;
   stderr: string;
+  truncated?: boolean;
 }
 
 interface IRunOptions {
   asRoot?: boolean;
   asTargetUser?: boolean;
   timeoutSeconds?: number;
+  cwd?: string;
 }
 
 export interface IRuntimeContext {
@@ -51,11 +53,6 @@ interface INcduParseResult {
   insights: INcduInsight[];
 }
 
-export interface IWorkspaceScanOptions {
-  maxDepth: number;
-  timeoutMs: number;
-  maxEntries: number;
-}
 
 const decoder = new TextDecoder();
 const maxCapturedOutputBytes = 64 * 1024 * 1024;
@@ -209,6 +206,7 @@ function commandResultFromCapture(code: number, stdout: ICaptureState, stderr: I
     truncationMessages.push(`stderr truncated after ${formatBytes(maxCapturedOutputBytes)}`);
   }
   if (truncationMessages.length) {
+    result.truncated = true;
     result.stderr = [result.stderr.trimEnd(), `[tsdisk] ${truncationMessages.join('; ')}.`]
       .filter(Boolean)
       .join('\n');
@@ -591,12 +589,13 @@ async function runCommand(
   }
 
   if (options.timeoutSeconds && options.timeoutSeconds > 0) {
-    finalArgs = [`${options.timeoutSeconds}s`, executable, ...finalArgs];
+    finalArgs = ['--kill-after=5s', `${options.timeoutSeconds}s`, executable, ...finalArgs];
     executable = 'timeout';
   }
 
   return await new Promise<ICommandResult>((resolve) => {
     const child = plugins.spawn(executable, finalArgs, {
+      cwd: options.cwd,
       env: {
         ...process.env,
         ...env,
@@ -679,119 +678,8 @@ async function pathExists(path: string): Promise<boolean> {
   }
 }
 
-async function readMarkerInDirectory(pathArg: string): Promise<IToolCacheMarker | undefined> {
-  try {
-    const markerRaw = await plugins.fs.readFile(plugins.path.join(pathArg, toolCacheMarkerFile), 'utf8');
-    return parseToolCacheMarker(markerRaw);
-  } catch {
-    return undefined;
-  }
-}
-
-function shouldSkipWorkspaceDir(nameArg: string): boolean {
-  return nameArg === '.git'
-    || nameArg === 'node_modules'
-    || nameArg === 'dist_ts'
-    || nameArg === 'dist_ts_web'
-    || nameArg === 'coverage'
-    || nameArg === '.pnpm-store';
-}
-
-export async function collectToolCachePathsFromRoot(
-  rootArg: string,
-  optionsArg: IWorkspaceScanOptions,
-): Promise<IToolCacheFinding[]> {
-  const findings = new Map<string, IToolCacheFinding>();
-  const startedAt = Date.now();
-  let visitedEntries = 0;
-  let rootDev: number | undefined;
-
-  try {
-    rootDev = (await plugins.fs.stat(rootArg)).dev;
-  } catch {
-    return [];
-  }
-
-  const visit = async (dirArg: string, depthArg: number): Promise<void> => {
-    if (Date.now() - startedAt > optionsArg.timeoutMs || visitedEntries > optionsArg.maxEntries) {
-      return;
-    }
-
-    let entries;
-    try {
-      entries = await plugins.fs.readdir(dirArg, { withFileTypes: true });
-    } catch {
-      return;
-    }
-
-    const marker = await readMarkerInDirectory(dirArg);
-    const markerClassification = classifyToolCachePath(dirArg, marker);
-    if (markerClassification) {
-      findings.set(plugins.path.resolve(dirArg), {
-        path: dirArg,
-        ...markerClassification,
-      });
-    }
-
-    const heuristicClassification = classifyToolCachePath(dirArg);
-    if (heuristicClassification) {
-      if (!markerClassification) {
-        findings.set(plugins.path.resolve(dirArg), {
-          path: dirArg,
-          ...heuristicClassification,
-        });
-      }
-      if (heuristicClassification.kind === 'docker-registry-cache') {
-        for (const entry of entries) {
-          if (Date.now() - startedAt > optionsArg.timeoutMs || visitedEntries > optionsArg.maxEntries) {
-            return;
-          }
-          visitedEntries++;
-          if (!entry.isDirectory()) {
-            continue;
-          }
-          const entryPath = plugins.path.join(dirArg, entry.name);
-          const entryMarker = await readMarkerInDirectory(entryPath);
-          const entryMarkerClassification = classifyToolCachePath(entryPath, entryMarker);
-          if (entryMarkerClassification) {
-            findings.set(plugins.path.resolve(entryPath), {
-              path: entryPath,
-              ...entryMarkerClassification,
-            });
-          }
-        }
-      }
-      return;
-    }
-
-    if (depthArg >= optionsArg.maxDepth) {
-      return;
-    }
-
-    for (const entry of entries) {
-      if (Date.now() - startedAt > optionsArg.timeoutMs || visitedEntries > optionsArg.maxEntries) {
-        return;
-      }
-      visitedEntries++;
-      if (!entry.isDirectory() || shouldSkipWorkspaceDir(entry.name)) {
-        continue;
-      }
-      const entryPath = plugins.path.join(dirArg, entry.name);
-      let stat;
-      try {
-        stat = await plugins.fs.stat(entryPath);
-      } catch {
-        continue;
-      }
-      if (rootDev !== undefined && stat.dev !== rootDev) {
-        continue;
-      }
-      await visit(entryPath, depthArg + 1);
-    }
-  };
-
-  await visit(rootArg, 0);
-  return [...findings.values()];
+export async function collectToolCachePathsFromRoot(root: string, options: IWorkspaceScanOptions): Promise<IToolCacheFinding[]> {
+  return (await scanWorkspace(root, options)).findings;
 }
 
 async function getWorkspaceRoots(): Promise<string[]> {
@@ -806,34 +694,34 @@ async function getWorkspaceRoots(): Promise<string[]> {
   return [...roots];
 }
 
-export async function collectProjectToolCacheDiagnostics(ctx: IRuntimeContext): Promise<IToolCacheFinding[]> {
-  const roots = await getWorkspaceRoots();
+export async function collectProjectToolCacheReport(ctx: IRuntimeContext, roots?: string[]) {
   const findings: IToolCacheFinding[] = [];
-  for (const root of roots) {
-    const rootFindings = await collectToolCachePathsFromRoot(root, {
-      maxDepth: 8,
-      timeoutMs: 45_000,
-      maxEntries: 50_000,
-    });
-    findings.push(...rootFindings);
-  }
-
-  const uniqueFindings = [...new Map(findings.map((finding) => [plugins.path.resolve(finding.path), finding])).values()];
-  const sizedFindings: IToolCacheFinding[] = [];
-  const sizingStartedAt = Date.now();
-  for (const [index, finding] of uniqueFindings.entries()) {
-    if (index >= toolCacheSizingLimit || Date.now() - sizingStartedAt > toolCacheSizingTimeoutMs) {
-      sizedFindings.push(finding);
+  const issues: IScanIssue[] = [];
+  const scanRoots = roots?.length ? roots : await getWorkspaceRoots();
+  for (const root of scanRoots) {
+    const result = await scanWorkspace(root, { maxDepth: 8, timeoutMs: 45_000, maxEntries: 50_000 });
+    findings.push(...result.findings);
+    issues.push(...result.issues);
+  }
+  const unique = [...new Map(findings.map((finding) => [plugins.path.resolve(finding.path), finding])).values()];
+  const deadline = Date.now() + toolCacheSizingTimeoutMs;
+  for (const [index, finding] of unique.entries()) {
+    if (index >= toolCacheSizingLimit || Date.now() >= deadline) {
+      issues.push({ path: finding.path, reason: 'size-unavailable', detail: 'Sizing budget exhausted.' });
       continue;
     }
-    const size = await readDuTotal(ctx, finding.path, ctx.sudoAvailable);
-    sizedFindings.push({
-      ...finding,
-      bytes: size?.bytes,
+    const result = await runCommand(ctx, 'du', ['-sx', '--block-size=1', '--', finding.path], {
+      asRoot: ctx.sudoAvailable, timeoutSeconds: Math.max(1, Math.min(ctx.duTimeoutSeconds, Math.floor((deadline - Date.now()) / 1000))),
     });
+    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.' });
   }
+  return { roots: scanRoots, toolCaches: unique.sort((a, b) => (b.bytes ?? 0) - (a.bytes ?? 0)), issues, complete: issues.length === 0 };
+}
 
-  return sizedFindings.sort((a, b) => (b.bytes ?? 0) - (a.bytes ?? 0));
+export async function collectProjectToolCacheDiagnostics(ctx: IRuntimeContext): Promise<IToolCacheFinding[]> {
+  return (await collectProjectToolCacheReport(ctx)).toolCaches;
 }
 
 async function printProjectToolCacheDiagnostics(ctx: IRuntimeContext) {
@@ -844,14 +732,16 @@ async function printProjectToolCacheDiagnostics(ctx: IRuntimeContext) {
     return;
   }
   progress(`Scanning workspace roots: ${roots.join(', ')}`);
-  const findings = await collectProjectToolCacheDiagnostics(ctx);
+  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) {
-    printSizeLine(`${finding.ownerGuess} ${finding.kind} [${finding.risk}] ${finding.path}`, finding.bytes ?? 0);
+    console.log(`${finding.bytes === undefined ? "unknown" : formatBytes(finding.bytes)}  ${finding.ownerGuess} ${finding.kind} [${finding.risk}] ${finding.path}`);
     console.log(`           suggested: ${finding.suggestedCleanupCommand}`);
   }
 }
@@ -1604,7 +1494,15 @@ function printHelp() {
   console.log('');
   console.log('Usage:');
   console.log('  tsdisk                 Run the disk usage diagnostic scan');
-  console.log('  tsdisk --json          Print project tool-cache diagnostics as JSON');
+  console.log('  tsdisk scan [--root PATH] [--json]  Bounded diagnostics; repeat --root for multiple workspaces');
+  console.log('  tsdisk --json          Full diagnostic report including toolCaches, sections, and scan issues');
+  console.log('  tsdisk cleanup [--root PROJECT] [--only rust,docker,pnpm] [--days 14]');
+  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('  --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('  tsdisk --help          Show this help');
   console.log('  tsdisk --version       Show the version');
   console.log('');
@@ -1687,30 +1585,118 @@ export async function main() {
   printCleanupHints(ctx);
 }
 
-export async function runCli(args = process.argv.slice(2)) {
-  if (args.includes('--help') || args.includes('-h')) {
-    printHelp();
-    return;
+export interface IDiagnosticSection {
+  name: string;
+  command: string;
+  args: string[];
+  result: ICommandResult;
+  complete: boolean;
+}
+
+export async function collectDiskReport(ctx: IRuntimeContext, roots?: string[]) {
+  const caches = await collectProjectToolCacheReport(ctx, roots);
+  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 });
+    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 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]);
+  }
+  await inspect('pnpm-store', 'pnpm', ['store', 'path']);
+  await inspect('journal', 'journalctl', ['--disk-usage']);
+  await inspect('deleted-open-files', 'lsof', ['-nP', '+L1']);
+  const contexts = await inspect('docker-contexts', 'docker', ['context', 'ls', '--format', '{{.Name}}']);
+  if (contexts.code === 0) {
+    for (const context of contexts.stdout.trim().split(/\r?\n/).filter(Boolean)) {
+      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) };
+}
 
-  if (args.includes('--version') || args.includes('-v')) {
-    console.log(commitinfo.version);
+async function runCleanup(options: ICliOptions) {
+  const plan = await createCleanupPlan(options);
+  const ctx = await initContext();
+  const previews: Array<{ action: number; result: ICommandResult }> = [];
+  const results: Array<{ action: number; result: ICommandResult }> = [];
+  const print = () => {
+    if (options.json) console.log(JSON.stringify({ ...plan, previews, results }, null, 2));
+    else {
+      console.log(plan.dryRun ? 'Cleanup preview (no deletion)' : 'Cleanup plan');
+      plan.actions.forEach((action, index) => {
+        console.log(`[${index + 1}] ${action.category}: ${action.cwd}`);
+        console.log(`    ${action.scope}`);
+        console.log(`    command: ${JSON.stringify([action.command, ...action.applyArgs])}`);
+        if (action.blocked) console.log(`    blocked: ${action.blocked}`);
+      });
+      for (const item of [...previews, ...results]) {
+        console.log(`[${item.action + 1}] exit ${item.result.code}`);
+        if (item.result.stdout) console.log(item.result.stdout.trimEnd());
+        if (item.result.stderr) console.error(item.result.stderr.trimEnd());
+      }
+    }
+  };
+  if (options.apply && options.json && !options.yes) throw new Error('JSON cleanup requires --apply --yes to execute.');
+  // Complete all previews before any apply command. Missing tools and failed previews block the batch.
+  for (const [index, action] of plan.actions.entries()) {
+    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 (plan.actions.some((action) => action.blocked) || previews.some((preview) => preview.result.code !== 0 || preview.result.truncated)) {
+    print();
+    process.exitCode = 1;
     return;
   }
-
-  if (args.includes('--json')) {
-    try {
-      const ctx = await initContext();
-      const findings = await collectProjectToolCacheDiagnostics(ctx);
-      console.log(JSON.stringify({ toolCaches: findings }, null, 2));
-    } catch (error) {
-      console.error(error instanceof Error ? error.message : String(error));
-      process.exitCode = 1;
+  if (!options.apply) { print(); return; }
+  if (!options.json) print();
+  if (!options.yes) {
+    if (!process.stdin.isTTY) throw new Error('Noninteractive cleanup requires --apply --yes.');
+    if (!await promptYesNo('Run the listed owning-tool cleanup commands?', false)) return;
+  }
+  for (const [index, action] of plan.actions.entries()) {
+    const result = await runCommand(ctx, action.command, action.applyArgs, { cwd: action.cwd, timeoutSeconds: 240 });
+    results.push({ action: index, result });
+    if (result.code !== 0) { process.exitCode = 1; break; }
+  }
+  // JSON emits one complete document; text can show the plan before confirmation.
+  if (options.json) print();
+  else {
+    for (const item of results) {
+      console.log(`[${item.action + 1}] cleanup exit ${item.result.code}`);
+      if (item.result.stdout) console.log(item.result.stdout.trimEnd());
+      if (item.result.stderr) console.error(item.result.stderr.trimEnd());
     }
-    return;
   }
+}
 
+export async function runCli(args = process.argv.slice(2)) {
   try {
+    const options = parseCliOptions(args);
+    if (options.command === 'help') { printHelp(); return; }
+    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);
+      if (options.json) console.log(JSON.stringify(report, null, 2));
+      else {
+        console.log(`Scan ${report.complete ? 'complete' : 'incomplete'}: ${report.toolCaches.length} tool caches`);
+        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}`);
+      }
+      if (!report.complete) process.exitCode = 2;
+      return;
+    }
     await main();
   } catch (error) {
     console.error(error instanceof Error ? error.message : String(error));

package/ts/tsdisk.plugins.ts

@@ -1,11 +1,12 @@
 // node native
 import { spawn } from 'node:child_process';
-import { createReadStream, type ReadStream } from 'node:fs';
+import { constants, createReadStream, type ReadStream } from 'node:fs';
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
 import { createInterface } from 'node:readline/promises';
 
 export {
+  constants,
   createInterface,
   createReadStream,
   fs,

package/ts/tsdisk.scan.ts

@@ -0,0 +1,124 @@
+import * as plugins from './tsdisk.plugins.js';
+import { classifyToolCachePath, parseToolCacheMarker, toolCacheMarkerFile, type IToolCacheFinding } from './tsdisk.toolcaches.js';
+
+export interface IWorkspaceScanOptions {
+  maxDepth: number;
+  timeoutMs: number;
+  maxEntries: number;
+}
+
+export interface IScanIssue {
+  path: string;
+  reason: 'read-error' | 'invalid-marker' | 'depth-limit' | 'entry-limit' | 'timeout' | 'mount-boundary' | 'symlink' | 'size-unavailable';
+  detail: string;
+}
+
+export interface IWorkspaceScanResult {
+  root: string;
+  findings: IToolCacheFinding[];
+  issues: IScanIssue[];
+  complete: boolean;
+  visitedEntries: number;
+}
+
+const excludedDirectories = new Set(['.git', 'node_modules', 'dist_ts', 'dist_ts_web', 'coverage', '.pnpm-store']);
+
+export async function scanWorkspace(root: string, options: IWorkspaceScanOptions): Promise<IWorkspaceScanResult> {
+  for (const name of ['maxDepth', 'timeoutMs', 'maxEntries'] as const) {
+    const value = options[name];
+    if (!Number.isSafeInteger(value) || value < (name === 'maxDepth' ? 0 : 1)) {
+      throw new Error(`Invalid scan option ${name}: ${value}`);
+    }
+  }
+  const result: IWorkspaceScanResult = { root: plugins.path.resolve(root), findings: [], issues: [], 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 });
+  };
+  const limited = (path: string) => {
+    if (stopped) return true;
+    if (Date.now() >= deadline || result.visitedEntries >= options.maxEntries) {
+      issue(path, Date.now() >= deadline ? 'timeout' : 'entry-limit', 'Scan stopped before visiting all entries.');
+      stopped = true;
+    }
+    return stopped;
+  };
+  let rootDev: number;
+  try {
+    const stat = await plugins.fs.lstat(result.root);
+    if (stat.isSymbolicLink() || await plugins.fs.realpath(result.root) !== result.root) {
+      issue(result.root, 'symlink', 'Scan roots must not contain symbolic links.');
+      return result;
+    }
+    if (!stat.isDirectory()) throw new Error('Scan root is not a directory.');
+    rootDev = stat.dev;
+  } catch (error) {
+    issue(result.root, 'read-error', error instanceof Error ? error.message : String(error));
+    return result;
+  }
+  const visit = async (directory: string, depth: number): Promise<void> => {
+    if (limited(directory)) return;
+    result.visitedEntries++;
+    try {
+      const stat = await plugins.fs.lstat(directory);
+      if (stat.isSymbolicLink()) {
+        issue(directory, 'symlink', 'Symbolic link skipped.');
+        return;
+      }
+      if (stat.dev !== rootDev) {
+        issue(directory, 'mount-boundary', 'Different filesystem skipped.');
+        return;
+      }
+      const entries = await plugins.fs.readdir(directory, { withFileTypes: true });
+      let marker;
+      if (entries.some((entry) => entry.name === toolCacheMarkerFile)) {
+        const markerPath = plugins.path.join(directory, toolCacheMarkerFile);
+        const markerStat = await plugins.fs.lstat(markerPath);
+        if (!markerStat.isFile() || markerStat.size > 65536) {
+          issue(markerPath, 'invalid-marker', 'Marker must be a regular file of at most 64 KiB.');
+        } else {
+          marker = parseToolCacheMarker(await plugins.fs.readFile(markerPath, 'utf8'));
+          if (!marker) issue(markerPath, 'invalid-marker', 'Invalid cache ownership marker.');
+        }
+      }
+      const heuristic = classifyToolCachePath(directory);
+      const classification = classifyToolCachePath(directory, marker);
+      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) {
+        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.');
+          continue;
+        }
+        if (heuristic?.kind === 'docker-registry-cache') {
+          // Only direct sessions, never registry blob trees.
+          const sessionMarker = await plugins.fs.lstat(plugins.path.join(childPath, toolCacheMarkerFile)).catch((error: NodeJS.ErrnoException) => {
+            if (error.code === 'ENOENT') return undefined;
+            throw error;
+          });
+          if (!sessionMarker) { result.visitedEntries++; continue; }
+        }
+        await visit(childPath, depth + 1);
+      }
+    } catch (error) {
+      issue(directory, 'read-error', error instanceof Error ? error.message : String(error));
+    }
+  };
+  await visit(result.root, 0);
+  return result;
+}

package/ts/tsdisk.toolcaches.ts

@@ -1,4 +1,4 @@
-import * as path from 'node:path';
+import { path } from './tsdisk.plugins.js';
 
 export const toolCacheMarkerFile = '.gitzone-tool-cache.json';
 
@@ -29,10 +29,10 @@ export function parseToolCacheMarker(rawArg: string): IToolCacheMarker | undefin
   try {
     const marker = JSON.parse(rawArg) as Partial<IToolCacheMarker>;
     if (
-      typeof marker.owner === 'string' &&
-      typeof marker.kind === 'string' &&
-      marker.safeToPrune === true &&
-      typeof marker.createdAt === 'string' &&
+      typeof marker.owner === 'string' && marker.owner.length > 0 &&
+      typeof marker.kind === 'string' && marker.kind.length > 0 &&
+      typeof marker.safeToPrune === 'boolean' &&
+      typeof marker.createdAt === 'string' && Number.isFinite(Date.parse(marker.createdAt)) &&
       marker.schemaVersion === 1
     ) {
       return marker as IToolCacheMarker;
@@ -79,8 +79,10 @@ export function classifyToolCachePath(pathArg: string, markerArg?: IToolCacheMar
     return {
       ownerGuess: markerArg.owner,
       kind: markerArg.kind,
-      risk: markerArg.safeToPrune ? 'safe-marked' : 'review',
-      suggestedCleanupCommand: `rm -rf ${quotePath(pathArg)}`,
+      risk: 'review',
+      suggestedCleanupCommand: markerArg.safeToPrune
+        ? `report-only: ownership marker is not proof of inactivity; use the owning tool to review ${quotePath(pathArg)}`
+        : `protected: owner explicitly disallows pruning ${quotePath(pathArg)}`,
       marker: markerArg,
     };
   }
@@ -103,7 +105,7 @@ export function classifyToolCachePath(pathArg: string, markerArg?: IToolCacheMar
     };
   }
 
-  if (normalized.endsWith('/.nogit/tsbundle-temp')) {
+  if (/\/\.nogit\/tsbundle-temp(?:-[^/]+)?$/.test(normalized)) {
     return {
       ownerGuess: '@git.zone/tsbundle',
       kind: 'bundle-temp-workspace',
@@ -112,6 +114,24 @@ export function classifyToolCachePath(pathArg: string, markerArg?: IToolCacheMar
     };
   }
 
+  if (/\/\.nogit\/tsrust-matrix(?:-archive|-probes)?$/.test(normalized)) {
+    return {
+      ownerGuess: '@git.zone/tsrust',
+      kind: 'rust-matrix-artifacts',
+      risk: 'report-only',
+      suggestedCleanupCommand: `report-only: retained matrix runs may be needed for recovery; inspect ${quotePath(pathArg)}`,
+    };
+  }
+
+  if (/\/\.nogit\/(?:docker-registry\.[^/]+|docker-registry-v1-cache|dockerimagestore)$/.test(normalized)) {
+    return {
+      ownerGuess: '@git.zone/tsdocker',
+      kind: 'legacy-docker-registry-cache',
+      risk: 'report-only',
+      suggestedCleanupCommand: `report-only: verify release recovery requirements before removing ${quotePath(pathArg)}`,
+    };
+  }
+
   if (normalized.endsWith('/.nogit/docker-registry') || normalized.includes('/.nogit/docker-registry/')) {
     return {
       ownerGuess: '@git.zone/tsdocker',