@rightkit/release 0.2.165 → 0.2.173

package/disk-command.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, unlinkSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
@@ -150,7 +150,8 @@ function defaultGlobalRoots() {
 
 export function scheduleSpec({ platform = process.platform, nodePath = process.execPath, cli = path.join(path.dirname(fileURLToPath(import.meta.url)), "cli", "right-release.mjs"), home = os.homedir(), hour = 3, minute = 30 } = {}) {
   if (platform === "darwin") {
-    const logDir = "/Volumes/D/claude/tmp/swept";
+    // launchd cannot open log files on an external volume for a background job (spawn fails with EX_CONFIG);
+    // `disk run` writes its own structured log to disk-hygiene.jsonl on the heavy volume.
     const file = path.join(home, "Library", "LaunchAgents", `${LAUNCHD_LABEL}.plist`);
     const plist = `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
@@ -158,8 +159,8 @@ export function scheduleSpec({ platform = process.platform, nodePath = process.e
 <key>Label</key><string>${LAUNCHD_LABEL}</string>
 <key>ProgramArguments</key><array><string>${nodePath}</string><string>${cli}</string><string>disk</string><string>run</string></array>
 <key>StartCalendarInterval</key><dict><key>Hour</key><integer>${hour}</integer><key>Minute</key><integer>${minute}</integer></dict>
-<key>StandardOutPath</key><string>${logDir}/launchd.out.log</string>
-<key>StandardErrorPath</key><string>${logDir}/launchd.err.log</string>
+<key>StandardOutPath</key><string>/dev/null</string>
+<key>StandardErrorPath</key><string>/dev/null</string>
 <key>ProcessType</key><string>Background</string><key>LowPriorityIO</key><true/><key>Nice</key><integer>10</integer>
 </dict></plist>
 `;
@@ -242,8 +243,300 @@ function schedule(sub, { stdout, cli, platform = process.platform, env = process
   return 0;
 }
 
+// ---- agent-env and probe: keep every agent and child-tool write on the external root (Adrian, 2026-10-17) -------------------
+
+const defaultAgentFs = { existsSync, statSync, mkdirSync, writeFileSync, unlinkSync, realpathSync };
+
+const pathFor = (platform) => (platform === "win32" ? path.win32 : path.posix);
+
+/** External root used when --root is absent: D:\ on Windows, /Volumes/D on macOS. No other platform is supported. */
+export function defaultExternalRoot(platform = process.platform) {
+  if (platform === "win32") return "D:\\";
+  if (platform === "darwin") return "/Volumes/D";
+  throw new Error(`disk agent-env: unsupported platform ${platform}; pass --root`);
+}
+
+function envValue(env, name, platform) {
+  if (platform !== "win32") return env[name];
+  const key = Object.keys(env).find((k) => k.toLowerCase() === name.toLowerCase());
+  return key === undefined ? undefined : env[key];
+}
+
+/** The one table of agent-environment paths, relative to the external root, identical on Windows and macOS (these are the D:
+ * paths RustRight already applied to the user environment). RustRight's broker imports this. `agentHome` rows are emitted only
+ * with --include-agent-homes. CARGO_TARGET_DIR is deliberately absent: RustRight owns cargo targets. */
+export const AGENT_ENV_TABLE = Object.freeze([
+  { name: "TEMP", segments: ["agent-cache", "tmp"] },
+  { name: "TMP", segments: ["agent-cache", "tmp"] },
+  { name: "TMPDIR", segments: ["agent-cache", "tmp"] },
+  { name: "CLAUDE_CODE_TMPDIR", segments: ["agent-cache", "tmp"] },
+  { name: "XDG_CACHE_HOME", segments: ["agent-cache", "xdg"] },
+  { name: "XDG_DATA_HOME", segments: ["agent-cache", "xdg-data"] },
+  { name: "XDG_STATE_HOME", segments: ["agent-cache", "xdg-state"] },
+  { name: "XDG_CONFIG_HOME", segments: ["agent-cache", "xdg-config"] },
+  { name: "npm_config_cache", segments: [".dev-cache", "npm-cache"] },
+  { name: "PNPM_STORE_DIR", segments: ["agent-cache", "pnpm-store"] },
+  { name: "YARN_CACHE_FOLDER", segments: ["agent-cache", "yarn"] },
+  { name: "PIP_CACHE_DIR", segments: [".dev-cache", "pip"] },
+  { name: "UV_CACHE_DIR", segments: [".dev-cache", "uv"] },
+  { name: "HF_HOME", segments: [".dev-cache", "huggingface"] },
+  { name: "TORCH_HOME", segments: ["agent-cache", "torch"] },
+  { name: "TRANSFORMERS_CACHE", segments: ["agent-cache", "transformers"] },
+  { name: "PLAYWRIGHT_BROWSERS_PATH", segments: ["agent-cache", "playwright"] },
+  { name: "PUPPETEER_CACHE_DIR", segments: ["agent-cache", "puppeteer"] },
+  { name: "NUGET_PACKAGES", segments: ["agent-cache", "nuget"] },
+  { name: "GOCACHE", segments: ["agent-cache", "go-build"] },
+  { name: "GOMODCACHE", segments: ["agent-cache", "go-mod"] },
+  { name: "DOTNET_CLI_HOME", segments: ["agent-cache", "dotnet"] },
+  { name: "ELECTRON_CACHE", segments: ["agent-cache", "electron"] },
+  { name: "DENO_DIR", segments: ["agent-cache", "deno"] },
+  { name: "CODEX_HOME", segments: ["agent-home", "codex"], agentHome: true },
+  { name: "CLAUDE_CONFIG_DIR", segments: ["agent-home", "claude"], agentHome: true },
+]);
+
+/** Ordered variable map for one external root from AGENT_ENV_TABLE. Pure. */
+export function agentEnvMap({ root, platform = process.platform, includeAgentHomes = false } = {}) {
+  if (!root) throw new Error("agentEnvMap needs a root");
+  const p = pathFor(platform);
+  return AGENT_ENV_TABLE.filter((e) => includeAgentHomes || !e.agentHome).map((e) => ({ name: e.name, value: p.join(root, ...e.segments) }));
+}
+
+export const AGENT_ENV_NOTES = [
+  "CARGO_TARGET_DIR is intentionally NOT set: RustRight owns cargo targets.",
+  "CODEX_HOME and CLAUDE_CONFIG_DIR are only emitted with --include-agent-homes (moving them requires restarting every chat).",
+];
+
+const shQuote = (v) => `'${String(v).replace(/'/g, `'\\''`)}'`;
+const psQuote = (v) => `'${String(v).replace(/'/g, "''")}'`;
+
+/** Render the map as a shell script, a PowerShell script, a cmd batch or JSON. Pure. */
+export function renderAgentEnv(map, { format, root, notes = AGENT_ENV_NOTES } = {}) {
+  if (format === "json") return JSON.stringify({ root, env: Object.fromEntries(map.map((m) => [m.name, m.value])), notes }, null, 2);
+  if (format === "sh") return [...notes.map((n) => `# ${n}`), ...map.map((m) => `export ${m.name}=${shQuote(m.value)}`)].join("\n");
+  if (format === "ps1") return [...notes.map((n) => `# ${n}`), ...map.map((m) => `$env:${m.name} = ${psQuote(m.value)}`)].join("\n");
+  if (format === "cmd") return [...notes.map((n) => `rem ${n}`), ...map.map((m) => `set "${m.name}=${m.value}"`)].join("\r\n");
+  throw new Error(`disk agent-env: unknown --format ${format} (sh|ps1|cmd|json)`);
+}
+
+function parseAgentEnv(rest, platform) {
+  const opts = { root: undefined, format: platform === "win32" ? "ps1" : "sh", check: false, includeAgentHomes: false };
+  for (let i = 0; i < rest.length; i += 1) {
+    const a = rest[i];
+    if (a === "--check") opts.check = true;
+    else if (a === "--include-agent-homes") opts.includeAgentHomes = true;
+    else if (a === "--root" || a === "--format") {
+      const v = rest[++i];
+      if (!v) throw new Error(`disk agent-env: ${a} needs a value`);
+      if (a === "--root") opts.root = v; else opts.format = v;
+    } else throw new Error(`disk agent-env: unknown option ${a}`);
+  }
+  if (!["sh", "ps1", "cmd", "json"].includes(opts.format)) throw new Error(`disk agent-env: unknown --format ${opts.format} (sh|ps1|cmd|json)`);
+  return opts;
+}
+
+const LOCAL_UNC_HOSTS = new Set(["localhost", "127.0.0.1", "::1", "[::1]", "."]);
+
+/** Realpath of `value`, resolving its nearest existing ancestor when the path itself does not exist yet. Null when nothing resolves. */
+function realpathOfExisting(value, realpath) {
+  let current = value;
+  let rest = "";
+  for (;;) {
+    try { return rest ? path.posix.join(realpath(current), rest) : realpath(current); } catch { /* try the parent */ }
+    const up = path.posix.dirname(current);
+    if (up === current) return null;
+    rest = rest ? `${path.posix.basename(current)}/${rest}` : path.posix.basename(current);
+    current = up;
+  }
+}
+
+/** True when `value` lies on the internal drive, or cannot be proven external. Windows: a path on the system drive, including the
+ * `\\?\C:\`, `\\.\C:\` and `\\?\UNC\localhost\C$\` / `\\localhost\C$\` spellings; any other path on this machine's own host name or
+ * loopback, a relative path and any device or volume-GUID path are unprovable and count as internal. macOS: any path outside
+ * /Volumes, and a /Volumes entry that resolves outside it (`/Volumes/Macintosh HD` is a symlink to /). Pure apart from the
+ * injectable `realpath` used on macOS. */
+export function pointsAtInternalDrive(value, { platform = process.platform, env = {}, realpath = realpathSync } = {}) {
+  const v = String(value ?? "");
+  if (platform === "win32") {
+    const system = String(envValue(env, "SystemDrive", platform) ?? "C:").slice(0, 1).toUpperCase();
+    let p = v.replace(/\//g, "\\");
+    let unc = null;
+    const extended = /^\\\\[?.]\\(.*)$/.exec(p);
+    if (extended) {
+      const tail = extended[1];
+      if (/^UNC\\/i.test(tail)) unc = tail.slice(4);
+      else if (/^[A-Za-z]:/.test(tail)) p = tail;
+      else return true;
+    } else if (/^\\\\[^\\]/.test(p)) unc = p.slice(2);
+    if (unc !== null) {
+      const [host = "", share = ""] = unc.split("\\");
+      const hostName = host.toLowerCase();
+      const own = String(envValue(env, "COMPUTERNAME", platform) ?? "").toLowerCase();
+      if (!host) return true;
+      if (!LOCAL_UNC_HOSTS.has(hostName) && !(own && hostName === own)) return false;
+      const admin = /^([A-Za-z])\$$/.exec(share);
+      return admin ? admin[1].toUpperCase() === system : true;
+    }
+    const m = /^([A-Za-z]):/.exec(p);
+    if (!m) return true;
+    return m[1].toUpperCase() === system;
+  }
+  if (!v.startsWith("/Volumes/")) return true;
+  if (platform === "darwin") {
+    const real = realpathOfExisting(v, realpath);
+    if (real !== null && !real.startsWith("/Volumes/")) return true;
+  }
+  return false;
+}
+
+function isUnder(value, root, platform) {
+  const p = pathFor(platform);
+  const norm = (s) => { const n = p.resolve(s); return platform === "win32" ? n.toLowerCase() : n; };
+  const r = norm(root);
+  const v = norm(value);
+  return v === r || v.startsWith(r.endsWith(p.sep) ? r : r + p.sep);
+}
+
+function uniqueProbeName(nonce) {
+  return `.rk-disk-probe-${process.pid}-${nonce ?? `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`}`;
+}
+
+/** Create then immediately remove one 0-byte uniquely named file in `dir`. Writes nothing else. Pure with injected fs. */
+const BLOCKED_CODES = new Set(["EACCES", "EPERM", "EROFS"]);
+
+/** Outcome: `allowed` (created and removed), `blocked` (EACCES/EPERM/EROFS), or `error` (missing directory or any other
+ * failure, with its code). A failed removal is `allowed` with code `UNLINK_<code>` and `leftover` set. */
+export function probeDirectory(dir, { fs = defaultAgentFs, nonce, platform = process.platform } = {}) {
+  let file;
+  try {
+    if (!dir) return { outcome: "error", code: "ENODIR" };
+    if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) return { outcome: "error", code: "ENOENT" };
+    file = pathFor(platform).join(dir, uniqueProbeName(nonce));
+    fs.writeFileSync(file, "", { flag: "wx" });
+  } catch (error) {
+    const code = error.code ?? "EUNKNOWN";
+    return { outcome: BLOCKED_CODES.has(code) ? "blocked" : "error", code };
+  }
+  try {
+    fs.unlinkSync(file);
+  } catch (error) {
+    return { outcome: "allowed", code: `UNLINK_${error.code ?? "EUNKNOWN"}`, leftover: true, file };
+  }
+  return { outcome: "allowed", code: null };
+}
+
+/** Locations that must be blocked for agents: user profile root, local temp (AppData\Local\Temp / default OS temp), OS temp, and
+ * the external root. */
+export function probeLocations({ platform = process.platform, env = process.env, home = os.homedir(), tmpdir = os.tmpdir(), root } = {}) {
+  const p = pathFor(platform);
+  const localTemp = platform === "win32"
+    ? p.join(envValue(env, "LOCALAPPDATA", platform) ?? p.join(home, "AppData", "Local"), "Temp")
+    : (envValue(env, "TMPDIR", platform) ?? tmpdir);
+  return [
+    { location: "profile", dir: home },
+    { location: "local-temp", dir: localTemp },
+    { location: "os-temp", dir: tmpdir },
+    { location: "external-root", dir: root ?? defaultExternalRoot(platform) },
+  ];
+}
+
+export const PROBE_SCHEMA = "rightkit.disk.probe.v1";
+
+/** Probe all four locations; the report is the exact `rightkit.disk.probe.v1` shape. `internalWritable` is true when any
+ * internal location (profile, local-temp, os-temp) accepted the probe file. */
+export function runProbe({ platform = process.platform, env = process.env, home, tmpdir, root, fs = defaultAgentFs, nonce, host = os.hostname() } = {}) {
+  const locations = probeLocations({ platform, env, ...(home ? { home } : {}), ...(tmpdir ? { tmpdir } : {}), root });
+  const probed = locations.map((l) => ({ l, r: probeDirectory(l.dir, { fs, nonce, platform }) }));
+  const external = locations.find((l) => l.location === "external-root").dir;
+  // Fail closed. An internal location is sealed only when the write was refused (EACCES, EPERM, EROFS) or the directory does not
+  // exist (ENOENT); ENOSPC, EBUSY and every other error prove nothing, so they count against the probe. The external root must
+  // accept the probe file, or agent writes have nowhere to go.
+  const problems = [];
+  for (const { l, r } of probed) {
+    if (l.location === "external-root") {
+      if (r.outcome !== "allowed") problems.push(`${l.location} ${l.dir} is not writable (${r.code})`);
+    } else if (r.outcome === "allowed") problems.push(`${l.location} ${l.dir} is writable`);
+    else if (r.outcome === "error" && r.code !== "ENOENT") problems.push(`${l.location} ${l.dir} could not be proven blocked (${r.code})`);
+  }
+  return {
+    problems,
+    report: {
+      schema: PROBE_SCHEMA, host, root: external,
+      results: probed.map(({ l, r }) => ({ location: l.location, path: l.dir, outcome: r.outcome, code: r.code })),
+      internalWritable: probed.some(({ l, r }) => l.location !== "external-root" && r.outcome === "allowed"),
+    },
+    leftovers: probed.filter(({ r }) => r.leftover).map(({ r }) => r.file),
+  };
+}
+
+export function renderProbe(report) {
+  return [...report.results.map((r) => `${r.outcome.toUpperCase().padEnd(8)} ${r.location.padEnd(14)} ${r.path}${r.code ? `  (${r.code})` : ""}`), report.internalWritable ? "INTERNAL DRIVE IS WRITABLE" : "internal drive is not writable"].join("\n");
+}
+
+/** Compare the live environment with the map. Each row: ok (under root), elsewhere (external, not under root), internal (set on
+ * the internal drive), unset (tool default lands on the internal drive). */
+export function checkAgentEnv(map, { env = process.env, platform = process.platform, root } = {}) {
+  return map.map(({ name, value }) => {
+    const current = envValue(env, name, platform);
+    let status;
+    if (current === undefined || current === "") status = "unset";
+    else if (pointsAtInternalDrive(current, { platform, env })) status = "internal";
+    else if (isUnder(current, root, platform)) status = "ok";
+    else status = "elsewhere";
+    return { name, expected: value, current: current ?? null, status };
+  });
+}
+
+function agentEnvCommand(rest, { env, stdout, platform, deps }) {
+  const stderr = deps.stderr ?? console.error;
+  const fs = deps.fs ?? defaultAgentFs;
+  const opts = parseAgentEnv(rest, platform);
+  const root = opts.root ?? defaultExternalRoot(platform);
+  const fail = (message) => { stderr(`disk agent-env: ${message}; refusing (no fallback to the internal drive)`); return { exitCode: 1 }; };
+  if (pointsAtInternalDrive(root, { platform, env, realpath: (p) => fs.realpathSync(p) })) return fail(`root ${root} is on the internal drive`);
+  if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) return fail(`root ${root} is missing`);
+  if (platform === "darwin") {
+    let real = root;
+    try { real = fs.realpathSync(root); } catch { /* keep lexical */ }
+    if (!real.startsWith("/Volumes/")) return fail(`root ${root} resolves to ${real}, not an external volume`);
+  }
+  const writable = probeDirectory(root, { fs, nonce: deps.nonce, platform });
+  if (writable.outcome !== "allowed" || writable.leftover) return fail(`root ${root} is not writable (${writable.code})`);
+  const map = agentEnvMap({ root, platform, includeAgentHomes: opts.includeAgentHomes });
+  if (opts.check) {
+    const rows = checkAgentEnv(map, { env, platform, root });
+    const bad = rows.filter((r) => r.status === "internal" || r.status === "unset");
+    if (opts.format === "json") stdout(JSON.stringify({ root, ok: bad.length === 0, variables: rows }, null, 2));
+    else {
+      for (const r of rows) stdout(`${r.status.toUpperCase().padEnd(9)} ${r.name.padEnd(26)} ${r.current ?? "(unset)"}${r.status === "ok" ? "" : `  -> ${r.expected}`}`);
+      stdout(bad.length ? `${bad.length} variable(s) point at the internal drive or are unset` : "all variables point at the external root");
+    }
+    return { exitCode: bad.length ? 1 : 0, rows };
+  }
+  for (const m of map) fs.mkdirSync(m.value, { recursive: true });
+  stdout(renderAgentEnv(map, { format: opts.format, root }));
+  return { exitCode: 0, map };
+}
+
+function probeCommand(rest, { env, stdout, platform, deps }) {
+  let json = false;
+  let root;
+  for (let i = 0; i < rest.length; i += 1) {
+    if (rest[i] === "--json") json = true;
+    else if (rest[i] === "--root") { root = rest[++i]; if (!root) throw new Error("disk probe: --root needs a value"); }
+    else throw new Error(`disk probe: unknown option ${rest[i]}`);
+  }
+  const { report, leftovers, problems } = runProbe({ platform, env, root, ...(deps.probe ?? {}), ...(deps.fs ? { fs: deps.fs } : {}), nonce: deps.nonce });
+  stdout(json ? JSON.stringify(report) : renderProbe(report));
+  const stderr = deps.stderr ?? console.error;
+  for (const problem of problems) stderr(`disk probe: ${problem}`);
+  for (const file of leftovers) stderr(`disk probe: could not remove ${file}`);
+  return { exitCode: report.internalWritable || leftovers.length || problems.length ? 1 : 0, report, problems };
+}
+
 export async function runDiskCommand(args = process.argv.slice(2), { env = process.env, stdout = console.log, platform = process.platform, deps = {} } = {}) {
   const [command, ...rest] = args;
+  if (command === "agent-env") return agentEnvCommand(rest, { env, stdout, platform, deps });
+  if (command === "probe") return probeCommand(rest, { env, stdout, platform, deps });
   if (command === "schedule") {
     const at = rest.indexOf("--cli");
     const exitCode = schedule(rest[0], { stdout, cli: at === -1 ? undefined : rest[at + 1], platform, env });
@@ -303,7 +596,7 @@ export async function runDiskCommand(args = process.argv.slice(2), { env = proce
     if (warn) stdout(`WARNING: ${after.warnings.join("; ")}`);
     return { exitCode: !self.ok ? 2 : warn ? DISK_EXIT_WARNING : 0, before, after, applied, purged, selfCheck: self };
   }
-  throw new Error("disk usage: check|sweep [--dry-run|--delete] [--all]|allow-workspace-sweep [--off] [--days N]|purge [--dry-run] [--days N]|run|schedule install|uninstall|status  [--json]");
+  throw new Error("disk usage: check|sweep [--dry-run|--delete] [--all]|allow-workspace-sweep [--off] [--days N]|purge [--dry-run] [--days N]|run|schedule install|uninstall|status|agent-env [--root dir] [--format sh|ps1|cmd|json] [--check] [--include-agent-homes]|probe  [--json]");
 }
 
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {

package/disk-policy.json

@@ -7,7 +7,7 @@
   },
   "holdingDays": 3,
   "holding": {
-    "mac": [{"prefix": "/", "path": "~/.rightkit-swept"}],
+    "mac": [{"prefix": "/", "path": "/Volumes/D/.rightkit-swept", "mount": "/Volumes/D"}, {"prefix": "/", "path": "~/.rightkit-swept"}],
     "win": [{"prefix": "C:\\", "path": "${LOCALAPPDATA}\\Orthic Labs\\.rightkit-swept"}]
   },
   "heavyVolume": {
@@ -27,13 +27,15 @@
   "writers": [
     {"id": "claude-session-dirs", "platform": "mac", "path": "/private/tmp/claude-501/*/*", "capBytes": 2147483648, "action": "sweep", "unit": "self"},
     {"id": "rightkit-qa-tmp", "platform": "mac", "path": "/private/tmp/rightkit-qa", "capBytes": 2147483648, "action": "sweep", "unit": "children"},
+    {"id": "cache-coreml-e5rt-tmp", "platform": "mac", "path": "~/Library/Caches/*/com.apple.e5rt.e5bundlecache/*/*/*.tmp.*", "capBytes": 4294967296, "action": "sweep", "unit": "self", "staleDays": 1},
+    {"id": "cache-coreml-e5rt", "platform": "mac", "path": "~/Library/Caches/*/com.apple.e5rt.e5bundlecache/*/*", "capBytes": 4294967296, "action": "sweep", "unit": "children", "staleDays": 2},
     {"id": "cache-e2e", "platform": "mac", "path": "~/Library/Caches/e2e_*", "capBytes": 1073741824, "action": "sweep", "unit": "self"},
     {"id": "cache-parakeet", "platform": "mac", "path": "~/Library/Caches/parakeet_*", "capBytes": 1073741824, "action": "sweep", "unit": "self"},
     {"id": "cache-swiftright-factory", "platform": "mac", "path": "~/Library/Caches/SwiftRightFactory", "capBytes": 10737418240, "action": "sweep", "unit": "children"},
-    {"id": "cache-cutright-engine", "platform": "mac", "path": "~/Library/Caches/cutright-engine", "capBytes": 2147483648, "action": "report"},
-    {"id": "cache-heardright-engine", "platform": "mac", "path": "~/Library/Caches/heardright-engine", "capBytes": 2147483648, "action": "report"},
-    {"id": "cache-pnpm", "platform": "mac", "path": "~/Library/Caches/pnpm", "capBytes": 3221225472, "action": "report"},
-    {"id": "cache-python", "platform": "mac", "path": "~/Library/Caches/python", "capBytes": 3221225472, "action": "report"},
+    {"id": "cache-cutright-engine", "platform": "mac", "path": "~/Library/Caches/cutright-engine", "capBytes": 2147483648, "action": "report", "unit": "children", "escalate": {"factor": 2, "staleDays": 7}},
+    {"id": "cache-heardright-engine", "platform": "mac", "path": "~/Library/Caches/heardright-engine", "capBytes": 2147483648, "action": "report", "unit": "children", "escalate": {"factor": 2, "staleDays": 7}},
+    {"id": "cache-pnpm", "platform": "mac", "path": "~/Library/Caches/pnpm", "capBytes": 3221225472, "action": "report", "unit": "children", "escalate": {"factor": 2, "staleDays": 7}},
+    {"id": "cache-python", "platform": "mac", "path": "~/Library/Caches/python", "capBytes": 3221225472, "action": "report", "unit": "children", "escalate": {"factor": 2, "staleDays": 7}},
     {"id": "xcode-deriveddata", "platform": "mac", "path": "~/Library/Developer/Xcode/DerivedData", "capBytes": 10737418240, "action": "sweep", "unit": "children"},
     {"id": "coresimulator", "platform": "mac", "path": "~/Library/Developer/CoreSimulator", "capBytes": 26843545600, "action": "report"},
     {"id": "documents-scratch", "platform": "mac", "path": "~/Documents", "capBytes": 21474836480, "action": "report"},

package/disk-policy.mjs

@@ -10,6 +10,12 @@ export const DEFAULT_POLICY_FILE = path.join(path.dirname(fileURLToPath(import.m
 export function readDiskPolicy(file = DEFAULT_POLICY_FILE) {
   const policy = JSON.parse(readFileSync(file, "utf8"));
   if (policy.schema !== 1 || !Array.isArray(policy.writers)) throw new Error("disk policy: unsupported schema");
+  for (const w of policy.writers) {
+    // `escalate` lets a report-only cache sweep its idle children once it is over cap by `factor` (see planSweep).
+    if (!w.escalate) continue;
+    const e = w.escalate;
+    if (w.action !== "report" || w.unit !== "children" || !(e.factor >= 1) || !(e.staleDays >= 0)) throw new Error(`disk policy: ${w.id} escalate needs action report, unit children, factor >= 1, staleDays >= 0`);
+  }
   return policy;
 }
 
@@ -112,6 +118,20 @@ export function isInsideRoot(candidate, root) {
   } catch { return false; }
 }
 
+// True when a directory strictly between `literal` (the writer's literal root) and `target` is a symlink: a cache reached
+// through a symlinked cache dir (some Mac caches now live on /Volumes/D) is never swept.
+export function symlinkAncestor(target, literal) {
+  const rel = path.relative(literal, target);
+  if (!rel || rel.startsWith("..") || path.isAbsolute(rel)) return false;
+  const parts = rel.split(path.sep).slice(0, -1);
+  let cur = literal;
+  for (const part of parts) {
+    cur = path.join(cur, part);
+    try { if (lstatSync(cur).isSymbolicLink()) return true; } catch { return false; }
+  }
+  return false;
+}
+
 export function writerMatches(writer, ctx) {
   const pattern = expandPolicyPath(writer.path, ctx);
   return expandGlob(pattern);
@@ -305,11 +325,18 @@ export function planSweep({ policy, platform = process.platform, env = process.e
   const skipped = [];
   const seen = new Set();
   const lockCheck = inUse ?? (key === "win" ? windowsLockProbe : (p) => inUseByOpenPaths(p, openPaths));
-  for (const writer of policy.writers.filter((w) => w.platform === key && w.action === "sweep")) {
-    // `--days N` overrides every writer; otherwise a writer may carry its own window (QA evidence: 3 days).
-    const cutoff = now - (staleDays ?? writer.staleDays ?? policy.staleDays) * 86400_000;
+  // Sweep writers, plus report writers with `escalate` when they are over cap by its factor (pure caches: idle children go).
+  for (const writer of policy.writers.filter((w) => w.platform === key && (w.action === "sweep" || w.escalate))) {
     let roots; let literal;
     try { roots = writerMatches(writer, { env, home }); literal = literalRoot(expandPolicyPath(writer.path, { env, home })); } catch { continue; }
+    // `--days N` overrides every writer; otherwise a writer may carry its own window (QA evidence: 3 days, caches: 2).
+    let window = staleDays ?? writer.staleDays ?? policy.staleDays;
+    if (writer.action !== "sweep") {
+      const total = roots.reduce((sum, r) => sum + size(r), 0);
+      if (!(total > writer.capBytes * writer.escalate.factor)) continue;
+      window = staleDays ?? writer.escalate.staleDays;
+    }
+    const cutoff = now - window * 86400_000;
     const units = [];
     for (const r of roots) {
       if (writer.unit !== "children") { units.push({ unit: r, root: literal }); continue; }
@@ -328,6 +355,7 @@ export function planSweep({ policy, platform = process.platform, env = process.e
       try { st = lstatSync(unit); } catch { continue; }
       if (st.isSymbolicLink()) { skipped.push({ ...base, reason: "symlink" }); continue; }
       if (!isInsideRoot(unit, root)) { skipped.push({ ...base, reason: "outside-root" }); continue; }
+      if (symlinkAncestor(unit, literal)) { skipped.push({ ...base, reason: "symlink-ancestor" }); continue; }
       if (isProtectedPath(unit, policy)) { skipped.push({ ...base, reason: "protected" }); continue; }
       if (writer.skipTracked && tracked(unit)) { skipped.push({ ...base, reason: "tracked" }); continue; }
       if (hasFreshContent(unit, cutoff)) { skipped.push({ ...base, reason: "fresh" }); continue; }
@@ -335,6 +363,10 @@ export function planSweep({ policy, platform = process.platform, env = process.e
       candidates.push({ ...base, root, bytes: size(unit), mtime: new Date(st.mtimeMs).toISOString() });
     }
   }
+  // Overlapping writers (a whole cache dir and one of its children): the outer unit wins, the nested one is not moved twice.
+  const nested = candidates.filter((c) => candidates.some((o) => o !== c && c.path.startsWith(o.path + path.sep)));
+  for (const c of nested) skipped.push({ writer: c.writer, path: c.path, reason: "nested" });
+  if (nested.length) candidates.splice(0, candidates.length, ...candidates.filter((c) => !nested.includes(c)));
   // Allowlisted workspace roots: unknown top-level entries older than 3 days and idle.
   const scanned = scan({ policy, platform, env, home });
   skipped.push(...scanned.skipped);
@@ -403,26 +435,52 @@ const isUnder = (candidate, prefix, win) => {
   return c === p || c.startsWith(withSep);
 };
 
+// True when a volume is mounted at `mount` and is not the item's own volume (`itemDev`).
+export function defaultMounted(mount, itemDev) {
+  try {
+    const dev = deviceOf(mount);
+    return existsSync(mount) && dev !== null && dev !== itemDev;
+  } catch { return false; }
+}
+
 // Candidate holding bases for an item, best first: policy per-volume rules (longest prefix), then the item's own volume root.
+// A rule with `mount` is a cross-volume base: it applies only to items on the policy floor's volume (the Mac internal drive),
+// and only while that mount is present (checked at pick time). Entries are `{ path, mount? }`.
 export function holdingBases(candidate, { policy, platform = process.platform, env = process.env, home = os.homedir() } = {}) {
   const key = platformKey(platform);
   const out = [];
+  let floorDev;
   const rules = (policy.holding?.[key] ?? []).flatMap((r) => {
-    try { return [{ prefix: expandPolicyPath(r.prefix, { env, home }), path: expandPolicyPath(r.path, { env, home }) }]; } catch { return []; }
+    try {
+      return [{ prefix: expandPolicyPath(r.prefix, { env, home }), path: expandPolicyPath(r.path, { env, home }), mount: r.mount ? expandPolicyPath(r.mount, { env, home }) : undefined }];
+    } catch { return []; }
   }).filter((r) => isUnder(candidate, r.prefix, key === "win")).sort((a, b) => b.prefix.length - a.prefix.length);
-  for (const r of rules) out.push(r.path);
-  out.push(path.join(volumeRoot(path.dirname(candidate)), HOLDING_DIR));
+  for (const r of rules) {
+    if (r.mount) {
+      if (floorDev === undefined) {
+        const floorPath = policy.floors?.[key]?.path;
+        floorDev = floorPath ? deviceOf(expandPolicyPath(floorPath, { env, home })) : null;
+      }
+      if (floorDev === null || deviceOf(path.dirname(candidate)) !== floorDev) continue;
+    }
+    out.push({ path: r.path, ...(r.mount ? { mount: r.mount } : {}) });
+  }
+  out.push({ path: path.join(volumeRoot(path.dirname(candidate)), HOLDING_DIR) });
   return out;
 }
 
-// Create (and mark) today's holding dir on the item's own volume; null when no holding dir on that volume is possible.
-export function pickHolding(candidate, { policy, platform = process.platform, env = process.env, home = os.homedir(), date = new Date(), bases } = {}) {
+// Create (and mark) today's holding dir; null when no holding dir is possible. A same-volume base must sit on the item's
+// own volume; a mount base must sit on a mounted volume other than the item's (`isMounted`, injectable for tests).
+export function pickHolding(candidate, { policy, platform = process.platform, env = process.env, home = os.homedir(), date = new Date(), bases, isMounted = defaultMounted } = {}) {
   const dev = deviceOf(path.dirname(candidate));
-  for (const base of bases ?? holdingBases(candidate, { policy, platform, env, home })) {
+  for (const entry of bases ?? holdingBases(candidate, { policy, platform, env, home })) {
+    const base = typeof entry === "string" ? entry : entry.path;
+    const mount = typeof entry === "string" ? undefined : entry.mount;
     try {
-      if (deviceOf(base) !== dev) continue; // checked before creating anything: a base on another volume would free nothing
+      // checked before creating anything: a same-volume base on another volume would free nothing
+      if (mount ? !isMounted(mount, dev) : deviceOf(base) !== dev) continue;
       mkdirSync(base, { recursive: true });
-      if (deviceOf(base) !== dev || lstatSync(base).isSymbolicLink()) continue;
+      if (lstatSync(base).isSymbolicLink() || (!mount && deviceOf(base) !== dev)) continue;
       const marker = path.join(base, HOLDING_MARKER);
       if (!existsSync(marker)) writeFileSync(marker, "created by right-release disk; date-named children are purged after the retention window\n");
       const dir = path.join(base, date.toISOString().slice(0, 10));
@@ -433,14 +491,45 @@ export function pickHolding(candidate, { policy, platform = process.platform, en
   return null;
 }
 
+// Entries (lstat-visited, symlinks not followed) and allocated bytes under `root`.
+export function treeStats(root) {
+  let entries = 0;
+  let bytes = 0;
+  const stack = [root];
+  while (stack.length) {
+    const dir = stack.pop();
+    let st;
+    try { st = lstatSync(dir); } catch { continue; }
+    entries += 1;
+    bytes += st.blocks ? st.blocks * 512 : st.size;
+    if (!st.isDirectory()) continue;
+    let names = [];
+    try { names = readdirSync(dir); } catch { continue; }
+    for (const name of names) stack.push(path.join(dir, name));
+  }
+  return { entries, bytes };
+}
+
+const pathExists = (p) => { try { lstatSync(p); return true; } catch { return false; } };
+
 export function moveEntry(source, destination) {
   mkdirSync(path.dirname(destination), { recursive: true });
   try { renameSync(source, destination); return "rename"; } catch (error) {
     if (error.code !== "EXDEV") throw error;
   }
-  const before = walkSize(source);
-  cpSync(source, destination, { recursive: true, preserveTimestamps: true, verbatimSymlinks: true, errorOnExist: true, force: false });
-  if (walkSize(destination) < before) throw new Error(`copy verification failed for ${source}; source kept`);
+  // Cross-volume: copy, verify the copy against the source, and only then remove the source. Never overwrite.
+  if (pathExists(destination)) throw new Error(`destination exists: ${destination}; source kept`);
+  const before = treeStats(source);
+  try {
+    cpSync(source, destination, { recursive: true, preserveTimestamps: true, verbatimSymlinks: true, errorOnExist: true, force: false });
+    const after = treeStats(destination);
+    if (after.entries !== before.entries || after.bytes < before.bytes) {
+      throw new Error(`copy verification failed for ${source} (entries ${before.entries} -> ${after.entries}, bytes ${before.bytes} -> ${after.bytes}); source kept`);
+    }
+  } catch (error) {
+    rmSync(destination, { recursive: true, force: true }); // our partial copy only: the source is untouched
+    throw error;
+  }
   rmSync(source, { recursive: true, force: true }); // completes the move after verified copy
   return "copy-verify-remove";
 }
@@ -452,7 +541,7 @@ export function logEvent(logFile, event) {
   } catch { /* logging must never fail the sweep */ }
 }
 
-export function applySweep({ plan, policy, platform = process.platform, deleteMode = false, date = new Date(), env = process.env, home = os.homedir(), move = moveEntry, pick = pickHolding, remove = (p) => rmSync(p, { recursive: true, force: true }) }) {
+export function applySweep({ plan, policy, platform = process.platform, deleteMode = false, date = new Date(), env = process.env, home = os.homedir(), move = moveEntry, pick = pickHolding, isMounted, remove = (p) => rmSync(p, { recursive: true, force: true }) }) {
   const logFile = path.join(policy.heavyVolume[platformKey(platform)], "disk-hygiene.jsonl");
   const results = [];
   for (const c of plan.candidates) {
@@ -462,7 +551,7 @@ export function applySweep({ plan, policy, platform = process.platform, deleteMo
       if (c.writer === "workspace-unknown" && PROJECT_MARKERS.some((m) => existsSync(path.join(c.path, m)))) throw new Error("refused: a nested git checkout or project directory is never swept");
       if (deleteMode) { remove(c.path); results.push({ ...c, action: "delete", ok: true }); logEvent(logFile, { event: "disk.sweep.delete", ...c }); continue; }
       // An item stays on its own volume: moving it elsewhere frees nothing on the volume that is short of space.
-      const holding = pick(c.path, { policy, platform, env, home, date });
+      const holding = pick(c.path, { policy, platform, env, home, date, isMounted });
       if (!holding) {
         remove(c.path);
         results.push({ ...c, action: "delete", how: "no-holding-on-volume", ok: true });