fix(memory): isolate test workspace cleanup

scripts/dev/cleanup-workspaces.ts

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+/**
+ * Safely inspect or quarantine stale test/temp workspace memory stores.
+ *
+ * Default mode is dry-run. Quarantine moves only definite temp/test residues.
+ * Unknown missing roots are reported but skipped unless --include-orphans is set.
+ */
+
+import { cleanupWorkspaceResidues } from "../../src/workspace-cleanup.ts";
+
+type CliOptions = {
+  mode: "dry-run" | "quarantine";
+  dataHome?: string;
+  olderThanDays?: number;
+  includeOrphans: boolean;
+};
+
+function usage(): string {
+  return `Usage:
+  npm run cleanup:workspaces -- --dry-run
+  npm run cleanup:workspaces -- --quarantine
+  npm run cleanup:workspaces -- --quarantine --older-than-days 1
+
+Options:
+  --dry-run             List candidates without moving anything (default)
+  --quarantine          Move definite temp/test residues to quarantine
+  --data-home <path>    Override XDG data home for testing/admin work
+  --older-than-days <n> Only consider workspace dirs older than n days
+  --include-orphans     Also quarantine missing non-temp roots (off by default)
+  --help                Show this help
+`;
+}
+
+function parseArgs(argv: string[]): CliOptions {
+  const options: CliOptions = { mode: "dry-run", includeOrphans: false };
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    switch (arg) {
+      case "--dry-run":
+        options.mode = "dry-run";
+        break;
+      case "--quarantine":
+        options.mode = "quarantine";
+        break;
+      case "--data-home":
+        options.dataHome = argv[++i];
+        if (!options.dataHome) throw new Error("--data-home requires a path");
+        break;
+      case "--older-than-days": {
+        const value = Number(argv[++i]);
+        if (!Number.isFinite(value) || value < 0) throw new Error("--older-than-days requires a non-negative number");
+        options.olderThanDays = value;
+        break;
+      }
+      case "--include-orphans":
+        options.includeOrphans = true;
+        break;
+      case "--help":
+      case "-h":
+        console.log(usage());
+        process.exit(0);
+      default:
+        throw new Error(`Unknown option: ${arg}\n${usage()}`);
+    }
+  }
+
+  return options;
+}
+
+const options = parseArgs(process.argv.slice(2));
+const result = await cleanupWorkspaceResidues({
+  dataHome: options.dataHome,
+  mode: options.mode,
+  includeOrphans: options.includeOrphans,
+  minAgeMs: options.olderThanDays === undefined ? undefined : options.olderThanDays * 24 * 60 * 60 * 1_000,
+});
+
+console.log(`Mode: ${result.mode}`);
+console.log(`Scanned: ${result.results.length}`);
+console.log(`Candidates: ${result.candidates.length}`);
+
+if (result.candidates.length > 0) {
+  console.log("\nCandidates:");
+  for (const candidate of result.candidates) {
+    console.log(`- ${candidate.workspaceKey} ${candidate.classification} root=${candidate.root ?? "<missing>"}`);
+    console.log(`  reasons=${candidate.reasons.join(",")}`);
+  }
+}
+
+if (result.quarantined.length > 0) {
+  console.log(`\nQuarantined: ${result.quarantined.length}`);
+  console.log(`Quarantine dir: ${result.quarantineDir}`);
+}
+
+const unknownOrphans = result.results.filter(item => item.classification === "orphan_unknown");
+if (unknownOrphans.length > 0 && !options.includeOrphans) {
+  console.log(`\nUnknown missing-root workspaces skipped: ${unknownOrphans.length}`);
+  console.log("Use --include-orphans only after manually confirming they are safe to quarantine.");
+}

scripts/dev/run-migration.ts

@@ -2,12 +2,12 @@
  * Local helper to trigger migration on workspace roots.
  *
  * Usage:
- *   MIGRATION_DRY_RUN_ROOTS=/path/a:/path/b bun run scripts/dev/dry-run-migration.ts
+ *   MIGRATION_RUN_ROOTS=/path/a:/path/b bun run scripts/dev/run-migration.ts
  *
  * Or create a local file (gitignored):
- *   echo "/path/to/workspace1" > scripts/dev/dry-run-roots.local.txt
- *   echo "/path/to/workspace2" >> scripts/dev/dry-run-roots.local.txt
- *   bun run scripts/dev/dry-run-migration.ts
+ *   echo "/path/to/workspace1" > scripts/dev/run-migration-roots.local.txt
+ *   echo "/path/to/workspace2" >> scripts/dev/run-migration-roots.local.txt
+ *   bun run scripts/dev/run-migration.ts
  */
 
 import { existsSync } from "node:fs";
@@ -17,13 +17,13 @@ import { loadWorkspaceMemory } from "../../src/workspace-memory.ts";
 
 async function getRoots(): Promise<string[]> {
   // Priority 1: environment variable
-  const envRoots = process.env.MIGRATION_DRY_RUN_ROOTS;
+  const envRoots = process.env.MIGRATION_RUN_ROOTS;
   if (envRoots) {
     return envRoots.split(":").filter(root => root.length > 0);
   }
 
   // Priority 2: local file
-  const localFile = join(import.meta.dirname, "dry-run-roots.local.txt");
+  const localFile = join(import.meta.dirname, "run-migration-roots.local.txt");
   if (existsSync(localFile)) {
     const content = await readFile(localFile, "utf8");
     return content.trim().split("\n").filter(root => root.length > 0);
@@ -31,7 +31,7 @@ async function getRoots(): Promise<string[]> {
 
   // No roots configured
   console.log("No workspace roots configured.");
-  console.log("Set MIGRATION_DRY_RUN_ROOTS=/path/a:/path/b or create dry-run-roots.local.txt");
+  console.log("Set MIGRATION_RUN_ROOTS=/path/a:/path/b or create run-migration-roots.local.txt");
   return [];
 }