@rightkit/release 0.2.164 → 0.2.172

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);
@@ -160,9 +180,33 @@ export function ensureScratchRoots({ policy, platform = process.platform, env =
 
 /** 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. */
+// Names that are always known at a workspace root, whatever the policy file says: agent instructions and agent state.
+export const WORKSPACE_ALWAYS_ALLOWED = ["CLAUDE.md", "AGENTS.md", "CLAUDE.local.md", ".claude", ".codex", ".agent", ".agents", ".membrane", "cockpit", "contributions"];
+const PROJECT_MARKERS = [".git", "package.json", "Cargo.toml"];
+
+/** Host-local opt-in for moving workspace-unknown entries. Without it the target is report-only on every host. */
+export function workspaceSweepFlagPath({ platform = process.platform, env = process.env, home = os.homedir() } = {}) {
+  if (platform === "win32" || platform === "win") {
+    if (!env.LOCALAPPDATA) return null;
+    return path.win32.join(env.LOCALAPPDATA, "Orthic Labs", "rightkit-release", "workspace-sweep-allowed");
+  }
+  return path.posix.join(home, "Library", "Application Support", "Orthic Labs", "rightkit-release", "workspace-sweep-allowed");
+}
+export function workspaceSweepAllowed(options = {}) {
+  const file = workspaceSweepFlagPath(options);
+  return Boolean(file) && existsSync(file);
+}
+export function setWorkspaceSweepAllowed(on, options = {}) {
+  const file = workspaceSweepFlagPath(options);
+  if (!file) throw new Error("disk: cannot place the host-local flag (LOCALAPPDATA is not set)");
+  if (on) { mkdirSync(path.dirname(file), { recursive: true }); writeFileSync(file, `workspace-unknown sweep allowed on this host ${new Date().toISOString()}\n`); }
+  else renameSync(file, `${file}.revoked`);
+  return file;
+}
+
 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 allow = new Set([...WORKSPACE_ALWAYS_ALLOWED, ...(policy.workspaceAllowlist ?? [])].map((n) => fold(n, key)));
   const unknown = [];
   const skipped = [];
   for (const entry of policy.workspaceRoots?.[key] ?? []) {
@@ -177,10 +221,12 @@ export function scanWorkspaceRoots({ policy, platform = process.platform, env =
     for (const name of names) {
       const folded = fold(name, key);
       if (allow.has(folded) || extra.has(folded) || trackedNames.has(folded)) continue;
+      if (/\.md$/i.test(name)) continue; // any markdown file at the root is documentation
       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
+      // a nested git checkout or any project directory (own package.json / Cargo.toml) is known
+      if (!st.isSymbolicLink() && st.isDirectory() && PROJECT_MARKERS.some((m) => existsSync(path.join(full, m)))) continue;
       unknown.push({ root, name, path: full, symlink: st.isSymbolicLink(), mtimeMs: st.mtimeMs });
     }
   }
@@ -206,7 +252,7 @@ export function checkDisk({ policy, platform = process.platform, env = process.e
   for (const w of writers) if (w.over) warnings.push(`${w.id} holds ${formatBytes(w.bytes)} over its ${formatBytes(w.capBytes)} cap`);
   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 u of unknown) warnings.push(`unknown top-level entry ${u.path} (${u.symlink ? "symlink" : formatBytes(u.bytes)}, ${u.ageDays}d old): track it or add it to workspaceAllowlist (sweep only moves it on a host that ran \`disk allow-workspace-sweep\`)`);
   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 };
 }
@@ -272,18 +318,25 @@ 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 }), scan = scanWorkspaceRoots } = {}) {
+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, workspaceSweep = workspaceSweepAllowed({ platform, env, home }) } = {}) {
   const key = platformKey(platform);
   const effectiveDays = staleDays ?? policy.staleDays;
   const candidates = [];
   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; }
@@ -302,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; }
@@ -309,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);
@@ -326,7 +384,11 @@ export function planSweep({ policy, platform = process.platform, env = process.e
     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);
+  // Report-only unless this host opted in (`disk allow-workspace-sweep`): unknown entries are warned about, never moved.
+  for (const u of scanned.unknown) {
+    if (!workspaceSweep) { skipped.push({ writer: "workspace-unknown", path: u.path, reason: "report-only" }); continue; }
+    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;
@@ -373,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));
@@ -403,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";
 }
@@ -422,17 +541,17 @@ 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) {
     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 (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 });

package/disk-stable-root.mjs

@@ -1,7 +1,8 @@
-import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { spawnSync } from "./background-process.mjs";
+import { previousPathOf, stagingPathOf, swapInPlace } from "./in-place-install.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.
@@ -64,8 +65,8 @@ export function collectDependencies(pkgRoot) {
 }
 
 /** 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 }`. */
+ * built in the fixed `current.staging`, swapped in by rename (the old copy stays as `current.previous`), then smoke-tested at
+ * `current`; a failed swap or smoke run renames `current.previous` back. 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);
@@ -81,10 +82,13 @@ export function installStableRoot({ cli, platform = process.platform, env = proc
 
   const parent = path.dirname(stable);
   mkdirSync(parent, { recursive: true });
+  // Legacy per-pid names from earlier versions; the fixed names are `current.staging` and `current.previous`.
   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 staging = stagingPathOf(stable);
+  const previous = previousPathOf(stable);
+  rmSync(staging, { recursive: true, force: true });
   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");
@@ -98,30 +102,29 @@ export function installStableRoot({ cli, platform = process.platform, env = proc
     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;
   }
+  // Swap first, then smoke-run at the fixed `current` path (never from the staging path). A failed run renames
+  // `current.previous` back. Exactly one `.previous` is kept.
   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);
+    const result = swapInPlace({
+      staging, destination: stable, previous,
+      verify: () => {
+        if (!smoke) return;
+        const r = spawnSync(nodePath, [stableCli, "--version"], { encoding: "utf8" });
+        if (r.status !== 0) throw new Error(`the installed copy does not run: ${r.stderr || r.stdout || r.error?.message}`);
+      },
+    });
+    replaced = result.previous !== null;
   } 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") {

package/engine-locator.mjs

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+// right-release engine-locate: the verified route to the CutRight and GenRight engines (Orthic-Labs/rightkit#316).
+// Callers such as PostRight get the engine path ONLY from here. The route is fixed per platform (the installed app's stable
+// `current` folder, see in-place-install.mjs) and every candidate is verified before its path is returned: a regular file (no
+// symlink or junction), signed by the Orthic Labs release identity (macOS: Developer ID, hardened runtime, pinned Team ID and
+// Identifier, not ad hoc; Windows: valid Authenticode, pinned signer organisation), and, when the caller pins one, an exact sha256.
+// There is no environment override, no path argument and no PATH search: a path the user or a build supplies is never trusted.
+import { createHash } from "node:crypto";
+import { existsSync, lstatSync, readFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { spawnSync } from "./background-process.mjs";
+import { assertPackagedIdentity, parseCodesignDisplay } from "./packaged-app-identity.mjs";
+
+export const ENGINE_TEAM_IDENTIFIER = "6KLGD3LLKF";
+export const ENGINE_SIGNER_ORGANIZATION = "Orthic Labs";
+
+/** engine id -> installed app folder, executable name (no extension) and macOS codesign Identifier. */
+export const ENGINES = Object.freeze({
+  cutright: Object.freeze({ app: "CutRight", exe: "cutright", identifier: "com.orthiclabs.cutright.engine" }),
+  genright: Object.freeze({ app: "GenRight", exe: "genright", identifier: "com.orthiclabs.genright.engine" }),
+});
+
+export class EngineLocateError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = "EngineLocateError";
+    this.code = code;
+  }
+}
+
+const fail = (code, message) => { throw new EngineLocateError(code, message); };
+
+/** The single fixed path for an engine on a platform. Reads no override variable: `localAppData` / `home` only name the user's profile roots. */
+export function engineRoute(engine, { platform = process.platform, home = os.homedir(), localAppData = process.env.LOCALAPPDATA } = {}) {
+  const spec = ENGINES[engine];
+  if (!spec) fail("ENGINE_UNKNOWN", `unknown engine ${JSON.stringify(engine)} (cutright or genright)`);
+  if (platform === "win32") {
+    if (!localAppData) fail("ENGINE_ROUTE_UNAVAILABLE", "LOCALAPPDATA is not set, so the Windows engine route cannot be formed");
+    return path.win32.join(localAppData, "Orthic Labs", spec.app, "current", "bin", `${spec.exe}.exe`);
+  }
+  if (platform === "darwin") return path.posix.join(home, "Library", "Application Support", "Orthic Labs", spec.app, "current", "bin", spec.exe);
+  return fail("ENGINE_PLATFORM_UNSUPPORTED", `no engine route for platform ${platform}`);
+}
+
+const capture = (command, args, run = spawnSync) => {
+  const result = run(command, args, { encoding: "utf8", windowsHide: true, shell: false });
+  return { status: result.status ?? 1, output: `${result.stdout ?? ""}\n${result.stderr ?? ""}` };
+};
+
+const defaultVerifyMac = (file, spec, run) => {
+  const strict = capture("codesign", ["--verify", "--strict", file], run);
+  if (strict.status !== 0) fail("ENGINE_SIGNATURE_INVALID", `codesign --verify --strict failed for ${file}: ${strict.output.trim()}`);
+  const display = capture("codesign", ["-dv", "--verbose=4", file], run);
+  if (display.status !== 0) fail("ENGINE_SIGNATURE_INVALID", `codesign could not read ${file}: ${display.output.trim()}`);
+  const failures = assertPackagedIdentity(parseCodesignDisplay(display.output), [], { identifier: spec.identifier, team: ENGINE_TEAM_IDENTIFIER });
+  if (failures.length) fail("ENGINE_IDENTITY_MISMATCH", `${file}: ${failures.join("; ")}`);
+};
+
+const defaultVerifyWindows = (file, _spec, run) => {
+  const script = "$s = Get-AuthenticodeSignature -LiteralPath $args[0]; [pscustomobject]@{ status = [string]$s.Status; subject = if ($s.SignerCertificate) { $s.SignerCertificate.Subject } else { '' } } | ConvertTo-Json -Compress";
+  const result = capture("powershell", ["-NoProfile", "-NonInteractive", "-Command", script, file], run);
+  let parsed;
+  try { parsed = JSON.parse(result.output.trim().split(/\r?\n/).filter(Boolean).at(-1)); } catch { fail("ENGINE_SIGNATURE_INVALID", `Authenticode could not be read for ${file}: ${result.output.trim()}`); }
+  if (parsed.status !== "Valid") fail("ENGINE_SIGNATURE_INVALID", `${file}: Authenticode status is ${parsed.status}, not Valid`);
+  if (!new RegExp(`(^|,\\s*)O=${ENGINE_SIGNER_ORGANIZATION}(,|$)`).test(parsed.subject)) fail("ENGINE_IDENTITY_MISMATCH", `${file}: signer ${JSON.stringify(parsed.subject)} is not ${ENGINE_SIGNER_ORGANIZATION}`);
+};
+
+/**
+ * Locate and verify an engine. Returns { engine, path, sha256, platform }. Throws EngineLocateError (ENGINE_NOT_INSTALLED,
+ * ENGINE_NOT_REGULAR_FILE, ENGINE_SIGNATURE_INVALID, ENGINE_IDENTITY_MISMATCH, ENGINE_HASH_MISMATCH, ...). Injectable for tests:
+ * `route`, `verifySignature`, `lstat`, `readBytes`. `expectedSha256` is an optional exact pin from the caller's own release record.
+ */
+export function locateEngine(engine, {
+  platform = process.platform, home, localAppData, expectedSha256, run = spawnSync,
+  route = engineRoute(engine, { platform, ...(home ? { home } : {}), ...(localAppData ? { localAppData } : {}) }),
+  verifySignature, lstat = lstatSync, readBytes = readFileSync, exists = existsSync,
+} = {}) {
+  const spec = ENGINES[engine];
+  if (!spec) fail("ENGINE_UNKNOWN", `unknown engine ${JSON.stringify(engine)} (cutright or genright)`);
+  if (!exists(route)) fail("ENGINE_NOT_INSTALLED", `${spec.app} engine is not installed at ${route}; install ${spec.app} from RightApps (there is no path override)`);
+  const info = lstat(route);
+  if (info.isSymbolicLink() || !info.isFile()) fail("ENGINE_NOT_REGULAR_FILE", `${route} must be a regular file, not a symlink, junction or directory`);
+  const verify = verifySignature ?? (platform === "win32" ? defaultVerifyWindows : platform === "darwin" ? defaultVerifyMac : () => fail("ENGINE_PLATFORM_UNSUPPORTED", `no engine verification for platform ${platform}`));
+  verify(route, spec, run);
+  const sha256 = createHash("sha256").update(readBytes(route)).digest("hex");
+  if (expectedSha256 !== undefined) {
+    if (!/^[0-9a-f]{64}$/.test(expectedSha256)) fail("ENGINE_HASH_MISMATCH", `expectedSha256 must be a lowercase SHA-256: ${JSON.stringify(expectedSha256)}`);
+    if (sha256 !== expectedSha256) fail("ENGINE_HASH_MISMATCH", `${route}: sha256 ${sha256} is not the pinned ${expectedSha256}`);
+  }
+  return { engine, path: route, sha256, platform };
+}
+
+export function main(args = process.argv.slice(2), options = {}) {
+  try {
+    const known = new Set(["--engine", "--sha256", "--json"]);
+    for (const arg of args) if (arg.startsWith("--") && !known.has(arg)) fail("ENGINE_USAGE", `unknown option ${arg} (there is deliberately no path option)`);
+    const take = (flag) => {
+      const index = args.indexOf(flag);
+      if (index < 0) return undefined;
+      const value = args[index + 1];
+      if (!value || value.startsWith("--")) fail("ENGINE_USAGE", `${flag} requires a value`);
+      return value;
+    };
+    const engine = take("--engine");
+    if (!engine) fail("ENGINE_USAGE", "usage: right-release engine-locate --engine cutright|genright [--sha256 <hex>] [--json]");
+    const result = locateEngine(engine, { expectedSha256: take("--sha256"), ...options });
+    console.log(args.includes("--json") ? JSON.stringify(result) : result.path);
+  } catch (error) {
+    console.error(`right-release engine-locate: ${error.code ? `[${error.code}] ` : ""}${error.message}`);
+    process.exitCode = 1;
+  }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) main();

package/external-bin.mjs

@@ -0,0 +1,133 @@
+// Stage, sign and receipt any number of Tauri externalBin sidecars (Orthic-Labs/rightkit#270).
+//
+//   targets.mac.externalBin = {
+//     names: ["mailright-engine", "mailright-core"],  // bare names, as in tauri.conf externalBin "binaries/<name>"
+//     arch: "aarch64",                                // default: build host; one arch per build
+//     stageDir: "src-tauri/binaries",                 // default; files are <name>-<target triple>[.exe]
+//     bundleDir: "Contents/MacOS",                    // mac only (or "Contents/Resources")
+//     stage: { cmd: "node", args: ["scripts/build-engine.mjs"] },   // optional: the app's own build of the files
+//   }
+//
+// This is the generic form of the ffmpeg sidecar from #246 and reuses its naming, hashing, staged-file checks and signing
+// evidence checks (media-sidecar.mjs); it adds no catalog, notices or release-manifest seal. It never signs: release.mjs
+// signs the staged files with the app (Windows raw-EXE step, macOS nested code) and writes external-bin.json.
+import path from "node:path";
+import {
+  bundledFileName, hostCatalogArch, sidecarTargetTriple, stagedFileName, verifyStagedSidecars,
+} from "./media-sidecar.mjs";
+
+export const EXTERNAL_BIN_CONTRACT = "rightkit-external-bin-v1";
+export const EXTERNAL_BIN_RECEIPT_NAME = "external-bin.json";
+
+const PLATFORM_OS = Object.freeze({ mac: "macos", win: "windows", linux: "linux" });
+const ARCHES = new Set(["aarch64", "x86_64"]);
+const CONFIG_KEYS = new Set(["names", "arch", "stageDir", "bundleDir", "stage"]);
+const BUNDLE_DIRS = new Set(["Contents/MacOS", "Contents/Resources"]);
+const SHA256 = /^[0-9a-f]{64}$/;
+
+const invalid = (code, message) => Object.assign(new Error(message), { code });
+const isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+
+/** Validate and normalise `targets.<platform>.externalBin`. Every problem is reported at once. */
+export function validateExternalBinConfig(raw, { platform, hostArch = hostCatalogArch(), reservedNames = [] } = {}) {
+  const errors = [];
+  const os = PLATFORM_OS[platform];
+  if (!os) throw invalid("EXTERNAL_BIN_CONFIG_INVALID", `externalBin is not supported on platform ${JSON.stringify(platform)} (mac, win or linux)`);
+  if (!isObject(raw)) throw invalid("EXTERNAL_BIN_CONFIG_INVALID", "externalBin must be an object");
+  for (const key of Object.keys(raw)) if (!CONFIG_KEYS.has(key)) errors.push(`unknown key ${JSON.stringify(key)} (allowed: ${[...CONFIG_KEYS].join(", ")})`);
+  const names = raw.names;
+  if (!Array.isArray(names) || !names.length || new Set(names).size !== names.length
+    || names.some((name) => typeof name !== "string" || !/^[A-Za-z0-9][A-Za-z0-9_.-]*$/.test(name) || name !== path.basename(name) || /\.exe$/i.test(name))) {
+    errors.push("names must be a non-empty list of unique bare sidecar names (no path, no .exe, no target triple)");
+  } else {
+    for (const name of names) if (reservedNames.includes(name)) errors.push(`${name} is already staged by mediaSidecar`);
+  }
+  const arch = raw.arch ?? hostArch;
+  if (!ARCHES.has(arch)) errors.push(`arch must be one of ${[...ARCHES].join(", ")} (one architecture per build): ${JSON.stringify(arch)}`);
+  else {
+    try { sidecarTargetTriple(os, arch); } catch (error) { errors.push(error.message); }
+  }
+  const stageDirRaw = raw.stageDir ?? "src-tauri/binaries";
+  let stageDir;
+  if (typeof stageDirRaw !== "string" || !stageDirRaw.trim()) errors.push("stageDir must be a non-empty relative path");
+  else {
+    const normalized = stageDirRaw.replaceAll("\\", "/");
+    if (path.isAbsolute(stageDirRaw) || /^[A-Za-z]:/.test(stageDirRaw) || normalized.split("/").includes("..")) errors.push(`stageDir must be relative and stay inside the app: ${stageDirRaw}`);
+    else stageDir = normalized.replace(/\/+$/, "");
+  }
+  let bundleDir;
+  if (os === "macos") {
+    bundleDir = raw.bundleDir ?? "Contents/MacOS";
+    if (!BUNDLE_DIRS.has(bundleDir)) errors.push(`bundleDir must be ${[...BUNDLE_DIRS].join(" or ")}`);
+  } else if (raw.bundleDir !== undefined) errors.push("bundleDir applies to macOS only");
+  let stage;
+  if (raw.stage !== undefined) {
+    if (!isObject(raw.stage) || typeof raw.stage.cmd !== "string" || !raw.stage.cmd || (raw.stage.args !== undefined && !Array.isArray(raw.stage.args))) errors.push("stage must be { cmd, args? }");
+    else stage = raw.stage;
+  }
+  if (errors.length) throw invalid("EXTERNAL_BIN_CONFIG_INVALID", `invalid externalBin configuration:\n${errors.map((line) => `- ${line}`).join("\n")}`);
+  return { os, arch, names: [...names], stageDir, ...(bundleDir ? { bundleDir } : {}), ...(stage ? { stage } : {}) };
+}
+
+/** The staged file (and, on macOS, bundle path) for every configured sidecar. Same shape `verifyStagedSidecars` reads. */
+export function planExternalBin({ config, root }) {
+  return {
+    config,
+    files: config.names.map((name) => ({
+      tool: name,
+      stagedPath: path.resolve(root, config.stageDir, stagedFileName(name, config.os, config.arch)),
+      bundledName: bundledFileName(name, config.os),
+      ...(config.bundleDir ? { bundlePath: `${config.bundleDir}/${bundledFileName(name, config.os)}` } : {}),
+    })),
+  };
+}
+
+/** `sign.nestedCode` entries for the macOS bundle: the sidecar executables, hardened runtime, no entitlements. */
+export function externalBinNestedCode(config) {
+  if (config.os !== "macos") return {};
+  return Object.fromEntries(config.names.map((name) => [`${config.bundleDir}/${bundledFileName(name, "macos")}`, { hardenedRuntime: true }]));
+}
+
+/** Before signing: every staged file exists, is non-empty, and its hash is recorded (reuses the ffmpeg check). */
+export function verifyStagedExternalBins(plan, deps) {
+  return verifyStagedSidecars(plan, deps).map((file) => ({ ...file }));
+}
+
+/** After signing: `signed` maps name to { sha256, sizeBytes }. */
+export function buildExternalBinReceipt(plan, preSign, signed) {
+  const { config } = plan;
+  return {
+    schema: 1,
+    contract: EXTERNAL_BIN_CONTRACT,
+    os: config.os,
+    arch: config.arch,
+    signing: config.os === "macos" ? "developer-id-hardened-runtime" : config.os === "windows" ? "authenticode" : "none",
+    files: preSign.map((file) => {
+      const after = signed[file.tool];
+      if (!after || !SHA256.test(after.sha256 ?? "")) throw invalid("EXTERNAL_BIN_RECEIPT_INVALID", `no signed digest for ${file.tool}`);
+      return {
+        name: file.tool,
+        preSignSha256: file.preSignSha256,
+        signedSha256: after.sha256,
+        sizeBytes: after.sizeBytes,
+        ...(file.bundlePath ? { bundlePath: file.bundlePath } : { bundledName: file.bundledName }),
+      };
+    }),
+  };
+}
+
+export function validateExternalBinReceipt(receipt, expected = {}) {
+  const fail = (message) => { throw invalid("EXTERNAL_BIN_RECEIPT_INVALID", `external bin receipt: ${message}`); };
+  if (!isObject(receipt) || receipt.schema !== 1 || receipt.contract !== EXTERNAL_BIN_CONTRACT) fail("unrecognized contract");
+  if (!Array.isArray(receipt.files) || !receipt.files.length) fail("no files");
+  for (const file of receipt.files) {
+    if (typeof file.name !== "string" || !file.name) fail("file without a name");
+    for (const key of ["preSignSha256", "signedSha256"]) if (!SHA256.test(file[key] ?? "")) fail(`${file.name}.${key} must be a SHA-256`);
+    if (!Number.isSafeInteger(file.sizeBytes) || file.sizeBytes <= 0) fail(`${file.name}.sizeBytes must be positive`);
+    if (file.preSignSha256 === file.signedSha256) fail(`${file.name} was not changed by signing`);
+  }
+  if (new Set(receipt.files.map((file) => file.name)).size !== receipt.files.length) fail("duplicate name");
+  if (expected.os && receipt.os !== expected.os) fail(`os ${receipt.os} is not ${expected.os}`);
+  if (expected.names && JSON.stringify([...expected.names].sort()) !== JSON.stringify(receipt.files.map((file) => file.name).sort())) fail("names differ from the configuration");
+  return receipt;
+}

package/github-release.mjs

@@ -329,7 +329,7 @@ function verifyRemoteAsset(tag, repo, asset, run, evidence) {
   if (inspectRemoteAsset(tag, repo, asset, run, evidence) !== "match") throw new Error(`GitHub release asset missing; inspect remote asset ${repo}/${tag}/${path.basename(asset)}`);
 }
 
-function inspectRemoteAsset(tag, repo, asset, run, evidence) {
+export function inspectRemoteAsset(tag, repo, asset, run, evidence) {
   const verifyDir = `${path.dirname(asset)}/verify-${path.basename(asset)}`;
   rmSync(verifyDir, { recursive: true, force: true });
   mkdirSync(verifyDir, { recursive: true });
@@ -350,7 +350,7 @@ function sha256(file) {
   return createHash("sha256").update(readFileSync(file)).digest("hex");
 }
 
-function runCommand(command, args, { allowFailure = false, cwd } = {}) {
+export function runCommand(command, args, { allowFailure = false, cwd } = {}) {
   const result = spawnSync(command, args, { cwd, encoding: "utf8", windowsHide: true });
   const output = result.stdout?.trim() ?? "";
   if (result.status !== 0) {