@rightkit/release 0.2.162 → 0.2.163

package/cli/right-release.mjs

@@ -247,8 +247,8 @@ Commands:
   disk check [--json]                                Per-writer sizes vs caps and free-space floor (exit 3 on warning)
   disk sweep [--dry-run] [--days N] [--delete] [--json]
                                                       Move stale idle heavy data to the heavy volume (delete only with --delete)
-  disk run                                           check, dry-run sweep, move sweep, warn (the scheduled job)
-  disk schedule install|uninstall|status             Daily launchd job (Mac) / hidden Task Scheduler entry (Windows)
+  disk run                                           self-check, check, dry-run sweep, move sweep, warn (the scheduled job)
+  disk schedule install|uninstall|status             Daily launchd job (Mac) / hidden Task Scheduler entry (Windows), bound to the stable per-user copy
   deps --check|--audit|--update                      Shared dependency lane
   hardening <artifact...>                            Run the Right Suite hardening scan
   lsclean <AppName.app>                              Clear macOS LaunchServices duplicates

package/disk-command.mjs

@@ -6,8 +6,9 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 import { spawnSync } from "./background-process.mjs";
 import { compareVersions } from "./rightkit-sync.mjs";
 import {
-  DISK_EXIT_WARNING, applySweep, checkDisk, formatBytes, listOpenPaths, logEvent, planSweep, platformKey, purgeHoldings, readDiskPolicy,
+  DISK_EXIT_WARNING, applySweep, checkDisk, ensureScratchRoots, formatBytes, listOpenPaths, logEvent, planSweep, platformKey, purgeHoldings, readDiskPolicy,
 } from "./disk-policy.mjs";
+import { evaluateBinding, installStableRoot, readScheduleBinding, selfCheck } from "./disk-stable-root.mjs";
 
 export const LAUNCHD_LABEL = "dev.rightkit.disk-hygiene";
 export const WINDOWS_TASK = "RightKit Disk Hygiene";
@@ -18,6 +19,10 @@ export function renderCheck(result) {
     const size = w.error ? `error: ${w.error}` : w.matches === 0 ? "absent" : `${formatBytes(w.bytes)} / cap ${formatBytes(w.capBytes)}`;
     lines.push(`  ${w.id.padEnd(28)} ${w.action.padEnd(6)} ${size}${w.over ? "  OVER CAP" : ""}`);
   }
+  if (result.unknown?.length) {
+    lines.push(`Unknown top-level entries (${result.unknown.length}):`);
+    for (const u of result.unknown) lines.push(`  ${(u.symlink ? "symlink" : formatBytes(u.bytes)).padStart(9)}  ${String(u.ageDays).padStart(4)}d  ${u.path}`);
+  }
   for (const w of result.warnings) lines.push(`WARNING: ${w}`);
   return lines.join("\n");
 }
@@ -162,48 +167,81 @@ Register-ScheduledTask -TaskName '${WINDOWS_TASK}' -Action $a -Trigger $t -Setti
   return { platform: "win", script };
 }
 
-function schedule(sub, { stdout, cli }) {
-  const platform = process.platform;
-  const spec = scheduleSpec(platform === "darwin" || sub !== "install" ? { platform } : { platform, cli: resolveInstalledCli({ explicit: cli }) });
+const here = path.dirname(fileURLToPath(import.meta.url));
+
+/** CLI to copy into the stable root: --cli / RIGHT_RELEASE_INSTALLED_CLI, else this very package when it is not a checkout
+ * (the usual `right-release disk schedule install` from the installed package), else the discovered installed package. */
+export function sourceCli({ explicit, env = process.env, self = path.join(here, "cli", "right-release.mjs"), resolve = resolveInstalledCli } = {}) {
+  if (explicit || env.RIGHT_RELEASE_INSTALLED_CLI) return resolve({ explicit, env });
+  let real = self;
+  try { real = realpathSync(self); } catch { /* keep lexical */ }
+  if (existsSync(self) && !insideGitCheckout(real)) return self;
+  return resolve({ explicit, env });
+}
+
+function scheduleStatus({ platform, stdout, env = process.env, home = os.homedir() }) {
+  let binding = null;
+  let loaded = false;
+  try { binding = readScheduleBinding({ platform, home }); } catch (error) { stdout(`status: cannot read the schedule (${error.message})`); return 1; }
+  if (platform === "darwin") {
+    const r = spawnSync("launchctl", ["print", `gui/${process.getuid()}/${LAUNCHD_LABEL}`], { encoding: "utf8" });
+    loaded = r.status === 0;
+  } else loaded = Boolean(binding);
+  if (!binding) { stdout("not installed"); return 0; }
+  const verdict = evaluateBinding(binding, { platform, env, home });
+  stdout(`${loaded ? "installed" : "plist present but not loaded"} (${binding.source})`);
+  stdout(`  target: ${binding.cli ?? "(none)"}`);
+  if (verdict.ok) { stdout("  binding ok: stable root, target present"); return loaded ? 0 : 1; }
+  for (const p of verdict.problems) stdout(`  PROBLEM: ${p}`);
+  return 1;
+}
+
+function schedule(sub, { stdout, cli, platform = process.platform, env = process.env }) {
+  if (!["install", "uninstall", "status"].includes(sub)) throw new Error("disk schedule install|uninstall|status");
+  if (sub === "status") return scheduleStatus({ platform, stdout, env });
+  const spec = scheduleSpec({ platform });
   if (platform === "darwin") {
     const uid = String(process.getuid());
     if (sub === "install") {
-      mkdirSync(path.dirname(spec.file), { recursive: true });
+      const installed = installStableRoot({ cli: sourceCli({ explicit: cli, env }), platform, env });
+      stdout(`${installed.unchanged ? "kept" : "installed"} @rightkit/release ${installed.version ?? "?"} in ${installed.stable}`);
+      const bound = scheduleSpec({ platform, cli: installed.cli });
+      mkdirSync(path.dirname(bound.file), { recursive: true });
       mkdirSync("/Volumes/D/claude/tmp/swept", { recursive: true });
-      writeFileSync(spec.file, spec.plist);
+      ensureScratchRoots({ policy: readDiskPolicy(), platform, env });
+      writeFileSync(bound.file, bound.plist);
       spawnSync("launchctl", ["bootout", `gui/${uid}/${LAUNCHD_LABEL}`], { encoding: "utf8" });
-      const r = spawnSync("launchctl", ["bootstrap", `gui/${uid}`, spec.file], { encoding: "utf8" });
+      const r = spawnSync("launchctl", ["bootstrap", `gui/${uid}`, bound.file], { encoding: "utf8" });
       if (r.status !== 0) throw new Error(`launchctl bootstrap failed: ${r.stderr}`);
-      stdout(`installed ${spec.file} (daily 03:30)`);
-    } else if (sub === "uninstall") {
+      stdout(`installed ${bound.file} (daily 03:30), bound to ${installed.cli}`);
+    } else {
       spawnSync("launchctl", ["bootout", `gui/${uid}/${LAUNCHD_LABEL}`], { encoding: "utf8" });
       if (existsSync(spec.file)) unlinkSync(spec.file);
       stdout("uninstalled");
-    } else if (sub === "status") {
-      const r = spawnSync("launchctl", ["print", `gui/${uid}/${LAUNCHD_LABEL}`], { encoding: "utf8" });
-      stdout(r.status === 0 ? `installed (${spec.file})` : "not installed");
-    } else throw new Error("disk schedule install|uninstall|status");
-    return;
+    }
+    return 0;
   }
   if (sub === "install") {
-    const r = spawnSync("powershell.exe", ["-NoProfile", "-NonInteractive", "-WindowStyle", "Hidden", "-Command", spec.script], { encoding: "utf8" });
+    const installed = installStableRoot({ cli: sourceCli({ explicit: cli, env }), platform, env });
+    stdout(`${installed.unchanged ? "kept" : "installed"} @rightkit/release ${installed.version ?? "?"} in ${installed.stable}`);
+    ensureScratchRoots({ policy: readDiskPolicy(), platform, env });
+    const bound = scheduleSpec({ platform, cli: installed.cli });
+    const r = spawnSync("powershell.exe", ["-NoProfile", "-NonInteractive", "-WindowStyle", "Hidden", "-Command", bound.script], { encoding: "utf8" });
     if (r.status !== 0) throw new Error(`Register-ScheduledTask failed: ${r.stderr || r.stdout}`);
-    stdout(`installed scheduled task "${WINDOWS_TASK}" (daily 03:30, hidden)`);
-  } else if (sub === "uninstall") {
+    stdout(`installed scheduled task "${WINDOWS_TASK}" (daily 03:30, hidden), bound to ${installed.cli}`);
+  } else {
     spawnSync("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", `Unregister-ScheduledTask -TaskName '${WINDOWS_TASK}' -Confirm:$false`], { encoding: "utf8" });
     stdout("uninstalled");
-  } else if (sub === "status") {
-    const r = spawnSync("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", `Get-ScheduledTask -TaskName '${WINDOWS_TASK}' | Select-Object -ExpandProperty State`], { encoding: "utf8" });
-    stdout(r.status === 0 ? `installed (${String(r.stdout).trim()})` : "not installed");
-  } else throw new Error("disk schedule install|uninstall|status");
+  }
+  return 0;
 }
 
 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 === "schedule") {
     const at = rest.indexOf("--cli");
-    schedule(rest[0], { stdout, cli: at === -1 ? undefined : rest[at + 1] });
-    return { exitCode: 0 };
+    const exitCode = schedule(rest[0], { stdout, cli: at === -1 ? undefined : rest[at + 1], platform, env });
+    return { exitCode };
   }
   const opts = parse(rest);
   const policy = readDiskPolicy(opts.policy);
@@ -219,6 +257,7 @@ export async function runDiskCommand(args = process.argv.slice(2), { env = proce
     return { exitCode: result.warn ? DISK_EXIT_WARNING : 0, result };
   }
   if (command === "sweep") {
+    if (!opts.dryRun) ensureScratchRoots({ policy, platform, env });
     const p = plan();
     if (opts.dryRun) { out(p, renderSweep(p)); return { exitCode: 0, plan: p }; }
     const applied = applySweep({ plan: p, policy, platform, deleteMode: opts.deleteMode, ...deps.apply });
@@ -231,6 +270,13 @@ export async function runDiskCommand(args = process.argv.slice(2), { env = proce
     return { exitCode: purged.results.some((r) => !r.ok) ? 1 : 0, purged };
   }
   if (command === "run") {
+    // Self-check first: a broken binding (non-stable target, missing package or dependency) is logged and fails the run.
+    const self = (deps.selfCheck ?? selfCheck)({ moduleDir: path.resolve(here, "."), platform, env, ...(deps.selfCheckOptions ?? {}) });
+    if (!self.ok) {
+      for (const problem of self.problems) stdout(`ERROR: disk run self-check: ${problem}`);
+      logEvent(logFile, { event: "disk.run.selfcheck.fail", problems: self.problems, version: self.version });
+    }
+    ensureScratchRoots({ policy, platform, env });
     const before = check();
     stdout(renderCheck(before));
     const p = plan();
@@ -243,7 +289,7 @@ export async function runDiskCommand(args = process.argv.slice(2), { env = proce
     const warn = after.warn;
     logEvent(logFile, { event: warn ? "disk.floor.warn" : "disk.run.ok", warnings: after.warnings, freeBytes: after.floor.freeBytes, movedBytes: applied.movedBytes });
     if (warn) stdout(`WARNING: ${after.warnings.join("; ")}`);
-    return { exitCode: warn ? DISK_EXIT_WARNING : 0, before, after, applied, purged };
+    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] [--days N]|purge [--dry-run] [--days N]|run|schedule install|uninstall|status  [--json]");
 }

package/disk-policy.json

@@ -14,6 +14,16 @@
     "mac": "/Volumes/D/claude/tmp/swept",
     "win": "D:\\claude\\tmp\\swept"
   },
+  "unknownStaleDays": 3,
+  "workspaceRoots": {
+    "mac": [{"path": "/Volumes/D/claude"}],
+    "win": [{"path": "D:\\claude"}]
+  },
+  "workspaceAllowlist": [".DS_Store", ".git", "node_modules", "tmp", "reports", "tasks", ".cache", "bin", "repos", "packages", "tests", "schemas", "assets", "migration", "archive", "catalog.db", "catalog.db-shm", "catalog.db-wal", "apple-skill-sources", "foundation-runs", "SEO", ".audit", ".commandcode", ".fastembed_cache", ".legion", ".model-bench", ".pnpm-store", ".pytest_cache", ".research", ".right-release", ".rightkit-managed", ".tether", ".venv-tools", ".vite"],
+  "scratchRoots": {
+    "mac": ["/Volumes/D/scratch"],
+    "win": ["D:\\scratch"]
+  },
   "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"},

package/disk-policy.mjs

@@ -56,7 +56,9 @@ export function walkSize(root) {
     const dir = stack.pop();
     let st;
     try { st = lstatSync(dir); } catch { continue; }
-    total += st.blocks !== undefined ? st.blocks * 512 : st.size;
+    // Allocated bytes; where the filesystem reports none for a non-empty file (NTFS keeps small files resident
+    // in the MFT, so Windows reports 0 blocks) the logical size is the best estimate.
+    total += st.blocks ? st.blocks * 512 : st.size;
     if (!st.isDirectory()) continue;
     let handle;
     try { handle = opendirSync(dir); } catch { continue; }
@@ -115,7 +117,77 @@ export function writerMatches(writer, ctx) {
   return expandGlob(pattern);
 }
 
-export function checkDisk({ policy, platform = process.platform, env = process.env, home = os.homedir(), size = (p) => pathSize(p, { platform }), space = freeSpace } = {}) {
+
+// ---- Workspace roots (allowlist) and scratch roots ------------------------------------------------------------------
+
+const isWin = (key) => key === "win";
+const fold = (value, key) => (isWin(key) ? value.toLowerCase() : value);
+
+/** Top-level names git tracks in the repository rooted exactly at `root`; null when that cannot be proven
+ * (not a repository root, git missing or failing). Callers must then leave the root alone. */
+export function workspaceTracked(root, { platform = process.platform, git = spawnSync } = {}) {
+  const key = platformKey(platform);
+  const top = git("git", ["-C", root, "rev-parse", "--show-toplevel"], { encoding: "utf8" });
+  if (top.status !== 0) return null;
+  try {
+    // The native form resolves Windows 8.3 short names (C:\Users\RUNNER~1) to the long names git prints.
+    if (fold(realpathSync.native(String(top.stdout).trim()), key) !== fold(realpathSync.native(root), key)) return null;
+  } catch { return null; }
+  const listed = git("git", ["-C", root, "ls-files", "-z"], { encoding: "utf8", maxBuffer: 1 << 28 });
+  if (listed.status !== 0) return null;
+  const names = new Set();
+  for (const file of String(listed.stdout).split("\0")) if (file) names.add(fold(file.split("/")[0], key));
+  return names;
+}
+
+export function scratchRoots(policy, { platform = process.platform, env = process.env, home = os.homedir() } = {}) {
+  const out = [];
+  for (const p of policy.scratchRoots?.[platformKey(platform)] ?? []) { try { out.push(expandPolicyPath(p, { env, home })); } catch { /* unset variable */ } }
+  return out;
+}
+
+/** Create missing scratch roots (only when their parent volume exists). Returns the roots that exist afterwards. */
+export function ensureScratchRoots({ policy, platform = process.platform, env = process.env, home = os.homedir() } = {}) {
+  const ready = [];
+  for (const root of scratchRoots(policy, { platform, env, home })) {
+    try {
+      if (!existsSync(root) && existsSync(path.dirname(root))) mkdirSync(root);
+      if (existsSync(root)) ready.push(root);
+    } catch { /* volume not writable: the next run retries */ }
+  }
+  return ready;
+}
+
+/** Top-level entries of each workspace root that are neither tracked by the workspace repo, nested git checkouts,
+ * nor on the allowlist. Symlinks are listed (`symlink: true`) but sweep never touches them. */
+export function scanWorkspaceRoots({ policy, platform = process.platform, env = process.env, home = os.homedir(), tracked = (r) => workspaceTracked(r, { platform }) } = {}) {
+  const key = platformKey(platform);
+  const allow = new Set((policy.workspaceAllowlist ?? []).map((n) => fold(n, key)));
+  const unknown = [];
+  const skipped = [];
+  for (const entry of policy.workspaceRoots?.[key] ?? []) {
+    let root;
+    try { root = expandPolicyPath(entry.path, { env, home }); } catch { continue; }
+    if (!existsSync(root)) continue;
+    const trackedNames = tracked(root);
+    if (!trackedNames) { skipped.push({ writer: "workspace-unknown", path: root, reason: "git-unavailable" }); continue; }
+    let names = [];
+    try { names = readdirSync(root); } catch { continue; }
+    const extra = new Set((entry.allow ?? []).map((n) => fold(n, key)));
+    for (const name of names) {
+      const folded = fold(name, key);
+      if (allow.has(folded) || extra.has(folded) || trackedNames.has(folded)) continue;
+      const full = path.join(root, name);
+      let st;
+      try { st = lstatSync(full); } catch { continue; }
+      if (!st.isSymbolicLink() && existsSync(path.join(full, ".git"))) continue; // nested git checkout
+      unknown.push({ root, name, path: full, symlink: st.isSymbolicLink(), mtimeMs: st.mtimeMs });
+    }
+  }
+  return { unknown, skipped };
+}
+
+export function checkDisk({ policy, platform = process.platform, env = process.env, home = os.homedir(), size = (p) => pathSize(p, { platform }), space = freeSpace, now = Date.now(), scan = scanWorkspaceRoots } = {}) {
   const key = platformKey(platform);
   const floorPolicy = policy.floors[key];
   const floor = evaluateFloor(floorPolicy, space(floorPolicy.path));
@@ -132,7 +204,11 @@ export function checkDisk({ policy, platform = process.platform, env = process.e
   const warnings = [];
   if (floor.warn) warnings.push(`${floor.label} free ${formatBytes(floor.freeBytes)} is below the ${formatBytes(floor.thresholdBytes)} floor`);
   for (const w of writers) if (w.over) warnings.push(`${w.id} holds ${formatBytes(w.bytes)} over its ${formatBytes(w.capBytes)} cap`);
-  return { schema: 1, platform: key, floor, writers, warnings, warn: warnings.length > 0 };
+  const scanned = scan({ policy, platform, env, home });
+  const unknown = scanned.unknown.map((u) => ({ root: u.root, name: u.name, path: u.path, symlink: u.symlink, bytes: u.symlink ? 0 : size(u.path), ageDays: Math.max(0, Math.floor((now - u.mtimeMs) / 86400_000)) }));
+  for (const u of unknown) warnings.push(`unknown top-level entry ${u.path} (${u.symlink ? "symlink" : formatBytes(u.bytes)}, ${u.ageDays}d old): track it, add it to workspaceAllowlist, or let sweep move it`);
+  for (const s of scanned.skipped) warnings.push(`workspace root ${s.path}: tracked paths cannot be read from git, so unknown entries are not evaluated or swept`);
+  return { schema: 1, platform: key, floor, writers, unknown, warnings, warn: warnings.length > 0 };
 }
 
 export function formatBytes(n) {
@@ -196,7 +272,7 @@ export function gitTracksPath(target) {
   return String(listed.stdout).length > 0;
 }
 
-export function planSweep({ policy, platform = process.platform, env = process.env, home = os.homedir(), now = Date.now(), staleDays, openPaths, inUse, tracked = gitTracksPath, size = (p) => pathSize(p, { platform }) } = {}) {
+export function planSweep({ policy, platform = process.platform, env = process.env, home = os.homedir(), now = Date.now(), staleDays, openPaths, inUse, tracked = gitTracksPath, size = (p) => pathSize(p, { platform }), scan = scanWorkspaceRoots } = {}) {
   const key = platformKey(platform);
   const effectiveDays = staleDays ?? policy.staleDays;
   const candidates = [];
@@ -233,6 +309,33 @@ export function planSweep({ policy, platform = process.platform, env = process.e
       candidates.push({ ...base, root, bytes: size(unit), mtime: new Date(st.mtimeMs).toISOString() });
     }
   }
+  // Allowlisted workspace roots: unknown top-level entries older than 3 days and idle.
+  const scanned = scan({ policy, platform, env, home });
+  skipped.push(...scanned.skipped);
+  const unknownCutoff = now - (staleDays ?? policy.unknownStaleDays ?? 3) * 86400_000;
+  const consider = (writerId, unit, root, cutoff) => {
+    if (seen.has(unit)) return;
+    seen.add(unit);
+    const base = { writer: writerId, path: unit };
+    let st;
+    try { st = lstatSync(unit); } catch { return; }
+    if (st.isSymbolicLink()) { skipped.push({ ...base, reason: "symlink" }); return; }
+    if (!isInsideRoot(unit, root)) { skipped.push({ ...base, reason: "outside-root" }); return; }
+    if (isProtectedPath(unit, policy)) { skipped.push({ ...base, reason: "protected" }); return; }
+    if (hasFreshContent(unit, cutoff)) { skipped.push({ ...base, reason: "fresh" }); return; }
+    if (lockCheck(unit)) { skipped.push({ ...base, reason: "in-use" }); return; }
+    candidates.push({ ...base, root, bytes: size(unit), mtime: new Date(st.mtimeMs).toISOString() });
+  };
+  for (const u of scanned.unknown) consider("workspace-unknown", u.path, u.root, unknownCutoff);
+  // Scratch roots: every child older than 3 days and idle (the same window).
+  for (const root of scratchRoots(policy, { platform, env, home })) {
+    let rst;
+    try { rst = lstatSync(root); } catch { continue; }
+    if (rst.isSymbolicLink()) { skipped.push({ writer: "scratch-root", path: root, reason: "symlink-root" }); continue; }
+    let names = [];
+    try { names = readdirSync(root); } catch { continue; }
+    for (const n of names) consider("scratch-root", path.join(root, n), root, unknownCutoff);
+  }
   return { schema: 1, platform: key, staleDays: effectiveDays, candidates, skipped, totalBytes: candidates.reduce((s, c) => s + c.bytes, 0) };
 }
 
@@ -326,6 +429,7 @@ export function applySweep({ plan, policy, platform = process.platform, deleteMo
     try {
       // Re-verify at apply time: still the planned unit, not a symlink, still inside its root.
       if (!c.root || lstatSync(c.path).isSymbolicLink() || !isInsideRoot(c.path, c.root)) throw new Error("refused: path is not a sweepable unit inside its target root");
+      if (c.writer === "workspace-unknown" && existsSync(path.join(c.path, ".git"))) throw new Error("refused: a nested git checkout 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 });

package/disk-stable-root.mjs

@@ -0,0 +1,168 @@
+import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "./background-process.mjs";
+
+// The scheduled disk job must never bind to a pnpm store, a pnpm global hash directory or a checkout: those move or vanish
+// on upgrade. `disk schedule install` copies the installed package into this per-user root and binds the job to it.
+// See docs/architecture/development-installed-product-boundary.md (installed bindings use a stable `current` root).
+
+const pathFor = (platform) => (platform === "win32" || platform === "win" ? path.win32 : path.posix);
+
+export function stableRootPath({ platform = process.platform, env = process.env, home = os.homedir() } = {}) {
+  if (platform === "win32" || platform === "win") {
+    if (!env.LOCALAPPDATA) throw new Error("disk: LOCALAPPDATA is not set");
+    return path.win32.join(env.LOCALAPPDATA, "Orthic Labs", "rightkit-release", "current");
+  }
+  return path.posix.join(home, "Library", "Application Support", "Orthic Labs", "rightkit-release", "current");
+}
+
+export function stableCliPath(stable, platform = process.platform) {
+  return pathFor(platform).join(stable, "node_modules", "@rightkit", "release", "cli", "right-release.mjs");
+}
+
+export function isUnderStable(file, stable, platform = process.platform) {
+  const win = platform === "win32" || platform === "win";
+  const n = (v) => (win ? v.toLowerCase().replace(/\//g, "\\") : v);
+  const prefix = n(stable).replace(/[\\/]+$/, "") + (win ? "\\" : "/");
+  return n(file).startsWith(prefix);
+}
+
+const readJson = (file) => { try { return JSON.parse(readFileSync(file, "utf8")); } catch { return null; } };
+
+// Walk up from `from` looking for `node_modules/<name>` (or `<name>` directly inside a node_modules directory).
+function findDependency(name, from) {
+  let dir = from;
+  for (;;) {
+    for (const candidate of [path.join(dir, "node_modules", name), path.basename(dir) === "node_modules" ? path.join(dir, name) : null]) {
+      if (candidate && existsSync(path.join(candidate, "package.json"))) return candidate;
+    }
+    const up = path.dirname(dir);
+    if (up === dir) return null;
+    dir = up;
+  }
+}
+
+/** Runtime dependency directories of a package (transitive), as `{ name, dir }`, found beside the package (lexical path
+ * first, then its real path, so pnpm's symlinked layout works). */
+export function collectDependencies(pkgRoot) {
+  const found = new Map();
+  const visit = (root) => {
+    const deps = Object.keys(readJson(path.join(root, "package.json"))?.dependencies ?? {});
+    for (const name of deps) {
+      if (found.has(name)) continue;
+      let real = root;
+      try { real = realpathSync(root); } catch { /* keep lexical */ }
+      const dir = findDependency(name, root) ?? findDependency(name, real);
+      if (!dir) throw new Error(`disk: dependency ${name} of ${root} was not found beside the installed package`);
+      found.set(name, dir);
+      visit(dir);
+    }
+  };
+  visit(pkgRoot);
+  return [...found].map(([name, dir]) => ({ name, dir }));
+}
+
+/** Copy the installed @rightkit/release package (and its dependencies) into the stable root. The new tree is built and
+ * smoke-tested in a staging directory next to `current`, then swapped in by rename; a failed swap restores the previous
+ * `current`. Returns `{ stable, cli, version, replaced, unchanged }`. */
+export function installStableRoot({ cli, platform = process.platform, env = process.env, home = os.homedir(), now = Date.now(), nodePath = process.execPath, smoke = true } = {}) {
+  const stable = stableRootPath({ platform, env, home });
+  const stableCli = stableCliPath(stable, platform);
+  let realCli = cli;
+  try { realCli = realpathSync(cli); } catch { /* keep lexical */ }
+  if (isUnderStable(cli, stable, platform) || isUnderStable(realCli, stable, platform)) {
+    return { stable, cli: stableCli, version: readJson(path.join(stable, "node_modules", "@rightkit", "release", "package.json"))?.version, replaced: false, unchanged: true };
+  }
+  const pkgRoot = path.resolve(path.dirname(cli), "..");
+  const pkg = readJson(path.join(pkgRoot, "package.json"));
+  if (pkg?.name !== "@rightkit/release") throw new Error(`disk: ${cli} is not inside an @rightkit/release package`);
+  const deps = collectDependencies(pkgRoot);
+
+  const parent = path.dirname(stable);
+  mkdirSync(parent, { recursive: true });
+  for (const name of readdirSync(parent)) {
+    if (/^current\.(staging|prev)-/.test(name)) try { rmSync(path.join(parent, name), { recursive: true, force: true }); } catch { /* in use: leave it */ }
+  }
+  const staging = path.join(parent, `current.staging-${process.pid}-${now}`);
+  const copy = (from, to, filter) => cpSync(from, to, { recursive: true, dereference: true, force: true, filter });
+  try {
+    const target = path.join(staging, "node_modules", "@rightkit", "release");
+    mkdirSync(path.dirname(target), { recursive: true });
+    copy(pkgRoot, target, (src) => path.basename(src) !== "node_modules" && !src.endsWith(".test.mjs"));
+    for (const dep of deps) {
+      const to = path.join(staging, "node_modules", ...dep.name.split("/"));
+      mkdirSync(path.dirname(to), { recursive: true });
+      copy(dep.dir, to, (src) => path.basename(src) !== "node_modules");
+    }
+    writeFileSync(path.join(staging, "install.json"), `${JSON.stringify({ package: pkg.name, version: pkg.version, source: pkgRoot, installedAt: new Date(now).toISOString(), node: nodePath }, null, 2)}\n`);
+    const stagedCli = stableCliPath(staging, platform);
+    if (!existsSync(stagedCli)) throw new Error("disk: the copied package has no cli/right-release.mjs");
+    if (smoke) {
+      const r = spawnSync(nodePath, [stagedCli, "--version"], { encoding: "utf8" });
+      if (r.status !== 0) throw new Error(`disk: the staged copy does not run: ${r.stderr || r.stdout || r.error?.message}`);
+    }
+  } catch (error) {
+    rmSync(staging, { recursive: true, force: true });
+    throw error;
+  }
+  let replaced = false;
+  let prev;
+  try {
+    if (existsSync(stable) || isLink(stable)) { prev = path.join(parent, `current.prev-${process.pid}-${now}`); renameSync(stable, prev); replaced = true; }
+    renameSync(staging, stable);
+  } catch (error) {
+    if (prev && !existsSync(stable)) try { renameSync(prev, stable); } catch { /* reported below */ }
+    rmSync(staging, { recursive: true, force: true });
+    throw new Error(`disk: could not replace ${stable}: ${error.message}`);
+  }
+  if (prev) try { rmSync(prev, { recursive: true, force: true }); } catch { /* a later install removes it */ }
+  return { stable, cli: stableCli, version: pkg.version, replaced, unchanged: false };
+}
+
+function isLink(p) { try { return lstatSync(p).isSymbolicLink(); } catch { return false; } }
+
+/** Registered schedule target: the CLI path the launchd job or Windows task runs, or null when none is registered. */
+export function readScheduleBinding({ platform = process.platform, home = os.homedir(), file, run = spawnSync, label = "RightKit Disk Hygiene", plistFile } = {}) {
+  if (platform === "darwin") {
+    const plist = plistFile ?? file ?? path.join(home, "Library", "LaunchAgents", "dev.rightkit.disk-hygiene.plist");
+    if (!existsSync(plist)) return null;
+    const m = /<key>ProgramArguments<\/key><array>\s*<string>([^<]*)<\/string>\s*<string>([^<]*)<\/string>/.exec(readFileSync(plist, "utf8"));
+    return m ? { node: m[1], cli: m[2], source: plist } : { node: null, cli: null, source: plist };
+  }
+  const r = run("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", `$t = Get-ScheduledTask -TaskName '${label}' -ErrorAction SilentlyContinue; if (-not $t) { exit 3 }; $a = $t.Actions[0]; Write-Output $a.Execute; Write-Output $a.Arguments`], { encoding: "utf8" });
+  if (r.status !== 0) return null;
+  const [exe, ...rest] = String(r.stdout).split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
+  const args = rest.join(" ");
+  const quoted = /"([^"]+)"/.exec(args);
+  return { node: exe ?? null, cli: quoted ? quoted[1] : (args.split(/\s+/)[0] || null), source: label };
+}
+
+/** Evaluate a binding against the stable root. */
+export function evaluateBinding(binding, { platform = process.platform, env = process.env, home = os.homedir(), exists = existsSync } = {}) {
+  if (!binding) return { registered: false, ok: true, problems: [] };
+  const stable = stableRootPath({ platform, env, home });
+  const problems = [];
+  if (!binding.cli) problems.push("the schedule names no right-release CLI");
+  else {
+    if (!isUnderStable(binding.cli, stable, platform)) problems.push(`target ${binding.cli} is not under the stable root ${stable} (reinstall: right-release disk schedule install)`);
+    if (!exists(binding.cli)) problems.push(`target ${binding.cli} is MISSING`);
+  }
+  if (binding.node && !exists(binding.node)) problems.push(`node ${binding.node} is MISSING`);
+  return { registered: true, ok: problems.length === 0, problems, cli: binding.cli, node: binding.node, stable };
+}
+
+/** `disk run` self-check: this process's own package must be intact and a registered schedule must be bound to the stable root. */
+export function selfCheck({ moduleDir, platform = process.platform, env = process.env, home = os.homedir(), binding = () => readScheduleBinding({ platform, home }), exists = existsSync } = {}) {
+  const problems = [];
+  const pkg = readJson(path.join(moduleDir, "package.json"));
+  if (!pkg) problems.push(`own package.json is unreadable at ${moduleDir}`);
+  else {
+    if (!exists(path.join(moduleDir, "cli", "right-release.mjs"))) problems.push("own cli/right-release.mjs is missing");
+    for (const dep of Object.keys(pkg.dependencies ?? {})) if (!findDependency(dep, moduleDir)) problems.push(`dependency ${dep} is not resolvable from ${moduleDir}`);
+  }
+  let bound;
+  try { bound = evaluateBinding(binding(), { platform, env, home, exists }); } catch (error) { bound = { registered: false, ok: false, problems: [`cannot read the schedule binding: ${error.message}`] }; }
+  problems.push(...bound.problems);
+  return { ok: problems.length === 0, problems, registered: bound.registered, version: pkg?.version };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rightkit/release",
-  "version": "0.2.162",
+  "version": "0.2.163",
   "description": "Portable release CLI/SDK with fail-closed public GitHub Releases and private R2 + RightApps distribution.",
   "license": "MIT OR Apache-2.0",
   "type": "module",

package/rightkit-versions.json

@@ -354,7 +354,7 @@
     "rightkit-tauri": "0.1.0"
   },
   "stagedCargo": {
-    "rightkit-agent-tools": "0.1.2",
+    "rightkit-agent-tools": "0.1.3",
     "rightkit-agents": "0.1.0",
     "rightkit-app-settings": "0.2.0",
     "rightkit-asr": "0.2.1",
@@ -383,7 +383,7 @@
     "rightkit-llm": "0.2.1",
     "rightkit-logs": "0.3.0",
     "rightkit-mcp": "0.5.3",
-    "rightkit-models": "0.3.1",
+    "rightkit-models": "0.3.2",
     "rightkit-oauth": "0.5.0",
     "rightkit-ocr": "0.2.2",
     "rightkit-onnx": "0.2.3",
@@ -423,7 +423,7 @@
   },
   "registry": {
     "cargo": {
-      "rightkit-agent-tools": "0.1.2",
+      "rightkit-agent-tools": "0.1.3",
       "rightkit-agents": "0.1.0",
       "rightkit-app-settings": "0.2.0",
       "rightkit-asr": "0.2.1",
@@ -456,7 +456,7 @@
       "rightkit-logs": "0.3.0",
       "rightkit-mcp": "0.5.3",
       "rightkit-media": "0.2.6",
-      "rightkit-models": "0.3.1",
+      "rightkit-models": "0.3.2",
       "rightkit-oauth": "0.5.0",
       "rightkit-ocr": "0.2.2",
       "rightkit-onnx": "0.2.3",
@@ -513,7 +513,7 @@
       "@rightkit/qa": "0.4.8",
       "@rightkit/qa-chrome": "0.1.6",
       "@rightkit/react-shell": "0.6.4",
-      "@rightkit/release": "0.2.161",
+      "@rightkit/release": "0.2.162",
       "@rightkit/settings-ui": "0.4.4",
       "@rightkit/shell": "0.1.1",
       "@rightkit/tauri": "0.2.1",
@@ -540,7 +540,8 @@
       "0.2.5",
       "0.2.6",
       "0.2.7",
-      "0.3.0"
+      "0.3.0",
+      "0.3.1"
     ],
     "rightkit-audio": [
       "0.1.0",
@@ -756,6 +757,9 @@
     "rightkit-qa-driver": [
       "0.3.0",
       "0.3.1"
+    ],
+    "rightkit-agent-tools": [
+      "0.1.2"
     ]
   }
 }

package/runtime-budget-classes.json

@@ -21,6 +21,10 @@
       "ceilings": null,
       "requiredScale": null
     },
+    "rightkit-record": {
+      "ceilings": null,
+      "requiredScale": null
+    },
     "rightkit-sandbox": {
       "ceilings": null,
       "requiredScale": null