@rightkit/release 0.2.164 → 0.2.172

package/github-updater-release.mjs

@@ -0,0 +1,154 @@
+// GitHub Releases lane of `right-release publish-update` (Orthic-Labs/rightkit#237).
+//
+// The updater artifacts and their minisign signatures are the ones the r2-rightapps lane already uses: they are
+// signed once by `sign-updater.mjs` with the suite updater key (the same TAURI_SIGNING_PRIVATE_KEY / key file as
+// every other app), sealed, and re-verified by `verifyPublicationRelease`. This module only turns the same
+// `platforms` map the r2 lane builds ({ <platform>: { signature, url } }) into a Tauri v2 static `latest.json`
+// and uploads it, with the bundles and their `.sig` files, as assets of the GitHub release `v<version>`, so
+// `https://github.com/<owner>/<repo>/releases/latest/download/latest.json` resolves. It adds no key and no trust root.
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { PublicationError, digestBytes, readVerifiedArtifact, verifyArtifactFile } from "./publication-artifacts.mjs";
+import { inspectRemoteAsset, runCommand } from "./github-release.mjs";
+
+const REPO_RE = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})\/[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/;
+const SEMVER_RE = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?$/;
+// GitHub rewrites other characters in an asset name, which would make the manifest url differ from the asset.
+const ASSET_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._+-]{0,199}$/;
+// Tauri v2 updater platform keys: <os>-<arch>, optionally <os>-<arch>-<installer>.
+const PLATFORM_RE = /^(?:windows|darwin|linux)-(?:x86_64|aarch64|i686|armv7)(?:-(?:nsis|msi|app|appimage|deb|rpm))?$/;
+const KEY_ID_RE = /^[0-9A-F]{16}$/;
+
+export const LATEST_JSON_NAME = "latest.json";
+
+export function assertGitHubRepository(repo) {
+  if (!REPO_RE.test(repo ?? "")) throw new PublicationError("PUBLICATION_GITHUB_REPOSITORY_INVALID", "release config distribution.repository must be owner/repo for github-releases");
+  return repo;
+}
+
+export function assertUpdaterPlatform(platform) {
+  if (!PLATFORM_RE.test(platform ?? "")) throw new PublicationError("PUBLICATION_UPDATER_PLATFORM_INVALID", `updater platform must be a Tauri target such as windows-x86_64 or darwin-aarch64, got: ${platform}`);
+  return platform;
+}
+
+export function assertAssetName(name) {
+  if (!ASSET_NAME_RE.test(name ?? "")) throw new PublicationError("PUBLICATION_ASSET_NAME_INVALID", `GitHub release asset names must match ${ASSET_NAME_RE}, got: ${name}`);
+  return name;
+}
+
+export function assertUpdaterVersion(version) {
+  if (!SEMVER_RE.test(version ?? "")) throw new PublicationError("PUBLICATION_VERSION_INVALID", `updater version must be SemVer, got: ${version}`);
+  return version;
+}
+
+export const githubTag = (version) => `v${assertUpdaterVersion(version)}`;
+
+export function githubAssetUrl(repo, tag, name) {
+  return `https://github.com/${assertGitHubRepository(repo)}/releases/download/${tag}/${assertAssetName(name)}`;
+}
+
+/** The stable URL an app configures as its updater endpoint (resolves to the newest non-draft, non-prerelease release). */
+export function githubLatestJsonUrl(repo) {
+  return `https://github.com/${assertGitHubRepository(repo)}/releases/latest/download/${LATEST_JSON_NAME}`;
+}
+
+/**
+ * Key id (16 upper-case hex digits, as minisign prints it) of the key that made a Tauri `.sig` file's content.
+ * The `.sig` text is base64 of a minisign signature file; its second line is base64 of
+ * [2-byte algorithm][8-byte key id, little endian][64-byte signature].
+ */
+export function updaterSignatureKeyId(signatureText) {
+  try {
+    const lines = Buffer.from(String(signatureText).trim(), "base64").toString("utf8").split(/\r?\n/);
+    const raw = Buffer.from(lines[1] ?? "", "base64");
+    if (raw.length !== 74 || raw[0] !== 0x45 || (raw[1] !== 0x64 && raw[1] !== 0x44)) return null;
+    return Buffer.from(raw.subarray(2, 10)).reverse().toString("hex").toUpperCase();
+  } catch {
+    return null;
+  }
+}
+
+/** Refuses a signature made by any key other than the configured suite key id (distribution.updaterKeyId). */
+export function assertUpdaterKeyId(signatureText, expectedKeyId, label = "updater signature") {
+  if (expectedKeyId === undefined) return;
+  if (!KEY_ID_RE.test(expectedKeyId)) throw new PublicationError("PUBLICATION_SIGNATURE_KEY_MISMATCH", "distribution.updaterKeyId must be 16 upper-case hex digits");
+  const actual = updaterSignatureKeyId(signatureText);
+  if (actual !== expectedKeyId) throw new PublicationError("PUBLICATION_SIGNATURE_KEY_MISMATCH", `${label} was not made by updater key ${expectedKeyId} (found ${actual ?? "unreadable"})`);
+}
+
+/** Tauri v2 static manifest. `platforms` is { <target>: { signature, url } }, exactly what the r2 lane builds. */
+export function buildLatestJson({ version, notes, pubDate, platforms }) {
+  assertUpdaterVersion(version);
+  const entries = Object.entries(platforms ?? {});
+  if (!entries.length) throw new PublicationError("PUBLICATION_ROUTE_INVALID", "latest.json needs at least one platform");
+  const sorted = {};
+  for (const [name, entry] of entries.sort(([a], [b]) => a.localeCompare(b))) {
+    assertUpdaterPlatform(name);
+    if (!entry?.signature || !/^https:\/\//.test(entry.url ?? "")) throw new PublicationError("PUBLICATION_SIGNATURE_MISSING", `latest.json platform ${name} needs a signature and an https url`);
+    sorted[name] = { signature: entry.signature, url: entry.url };
+  }
+  return { version, notes: notes ?? "", pub_date: pubDate, platforms: sorted };
+}
+
+/** The win and mac runs publish separately to one latest.json: keep the other platform's entries for the same version. */
+export function mergeLatestJson(existing, next) {
+  if (!existing) return next;
+  if (existing.version !== next.version) throw new PublicationError("PUBLICATION_MANIFEST_CONFLICT", `remote latest.json is for ${existing.version}, not ${next.version}; refusing to overwrite it`);
+  return buildLatestJson({ version: next.version, notes: next.notes, pubDate: next.pub_date, platforms: { ...(existing.platforms ?? {}), ...next.platforms } });
+}
+
+/**
+ * Uploads the sealed updater bundles, their signatures and latest.json to release `tag` of `repo`, creating the
+ * (public, non-draft) release when it does not exist. Every sealed asset is byte-verified after upload; latest.json
+ * is read back and compared. `assets` is [{ file, evidence }] with the sealed artifact as evidence.
+ */
+export function publishGitHubUpdaterRelease({ repo, tag, title, notes, assets, latest, stateDir, dryRun = false, run = runCommand }) {
+  assertGitHubRepository(repo);
+  const byName = new Map();
+  for (const asset of assets) {
+    const name = assertAssetName(path.basename(asset.file));
+    if (byName.has(name) && byName.get(name).file !== asset.file) throw new PublicationError("PUBLICATION_ASSET_NAME_INVALID", `duplicate updater asset name: ${name}`);
+    byName.set(name, asset);
+  }
+  // A dry run makes no network call: it only reports the assets it would publish.
+  if (dryRun) return { status: "would-publish", tag, assets: [...byName.keys(), LATEST_JSON_NAME] };
+  const existing = run("gh", ["release", "view", tag, "--repo", repo, "--json", "tagName"], { allowFailure: true });
+
+  mkdirSync(stateDir, { recursive: true });
+  if (!existing.ok) {
+    const notesFile = path.join(stateDir, "release-notes.md");
+    writeFileSync(notesFile, `${notes}\n`);
+    try { run("gh", ["release", "create", tag, "--repo", repo, "--title", title, "--notes-file", notesFile]); }
+    finally { rmSync(notesFile, { force: true }); }
+  }
+  const missing = [...byName.values()].filter((asset) => inspectRemoteAsset(tag, repo, asset.file, run, asset.evidence) === "missing");
+  if (missing.length) run("gh", ["release", "upload", tag, ...missing.map((asset) => asset.file), "--repo", repo]);
+  for (const asset of byName.values()) {
+    if (inspectRemoteAsset(tag, repo, asset.file, run, asset.evidence) !== "match") throw new PublicationError("PUBLICATION_REMOTE_VERIFY_FAILED", `GitHub release asset missing after upload: ${repo}/${tag}/${path.basename(asset.file)}`);
+  }
+
+  // Merge with the other platform's entries, then upload latest.json last so it never points at a missing asset.
+  const downloadDir = path.join(stateDir, "remote-latest");
+  rmSync(downloadDir, { recursive: true, force: true });
+  mkdirSync(downloadDir, { recursive: true });
+  let remote = null;
+  const fetched = run("gh", ["release", "download", tag, "--repo", repo, "--pattern", LATEST_JSON_NAME, "--dir", downloadDir], { allowFailure: true });
+  if (fetched.ok) remote = JSON.parse(readFileSync(path.join(downloadDir, LATEST_JSON_NAME), "utf8"));
+  else if (!/no assets match|not found/i.test(`${fetched.output ?? ""}\n${fetched.error ?? ""}`)) throw new PublicationError("PUBLICATION_REMOTE_VERIFY_FAILED", `cannot read remote latest.json: ${fetched.error || fetched.output}`);
+  rmSync(downloadDir, { recursive: true, force: true });
+  const merged = mergeLatestJson(remote, latest);
+  const bytes = Buffer.from(`${JSON.stringify(merged, null, 2)}\n`);
+  const manifestFile = path.join(stateDir, LATEST_JSON_NAME);
+  writeFileSync(manifestFile, bytes);
+  run("gh", ["release", "upload", tag, manifestFile, "--repo", repo, "--clobber"]);
+  const verifyDir = path.join(stateDir, "verify-latest");
+  rmSync(verifyDir, { recursive: true, force: true });
+  mkdirSync(verifyDir, { recursive: true });
+  try {
+    run("gh", ["release", "download", tag, "--repo", repo, "--pattern", LATEST_JSON_NAME, "--dir", verifyDir]);
+    verifyArtifactFile(path.join(verifyDir, LATEST_JSON_NAME), readVerifiedArtifact(manifestFile, { sha256: digestBytes(bytes) }));
+  } finally {
+    rmSync(verifyDir, { recursive: true, force: true });
+  }
+  return { status: existing.ok ? "updated" : "created", tag, assets: [...byName.keys(), LATEST_JSON_NAME], latestJsonUrl: githubLatestJsonUrl(repo), manifest: merged };
+}

package/hardeningscan.mjs

@@ -70,7 +70,7 @@ const contentRules = [
   ["gpl-flag", /--enable-gpl|--enable-nonfree/gi, "GPL/nonfree ffmpeg flag leaked"],
   ["stale-model", /tdt_w15_p6/gi, "stale TDT p6 string leaked"],
   // Not allowable through hardening evidence: a shipped artifact never contains the QA control server.
-  ["qa-control-marker", new RegExp(QA_CONTROL_MARKER, "g"), "QA control server shipped (rightkit-qa-driver qa-control)"],
+  ["qa-control-marker", new RegExp(QA_CONTROL_MARKER, "g"), "QA control server shipped (rightkit-qa control, or rightkit-qa-driver qa-control)"],
   ["experiment-model", /Canary-Qwen|Nemotron|dqlstm|bias-experiments/gi, "experiment/model-history marker leaked"],
 ];
 

package/in-place-install.mjs

@@ -0,0 +1,56 @@
+import nodeFs from "node:fs";
+import path from "node:path";
+
+/**
+ * The one install rule for every app, helper and dev or QA binary (Adrian, 2026-10-17: "No new id, no new folder"):
+ * macOS and Windows tie privacy grants to the path and the code identity, so an install or update replaces the
+ * copy at ONE fixed path. Rollback is a persistent `<name>.previous` beside it (rename it back). Nothing ever runs
+ * from `.previous` or from the staging copy.
+ */
+export const PREVIOUS_SUFFIX = ".previous";
+export const STAGING_SUFFIX = ".staging";
+
+export const previousPathOf = (destination) => `${destination}${PREVIOUS_SUFFIX}`;
+/** Fixed (not per-pid) staging sibling. Nothing runs from it: it is fully written and verified, then renamed. */
+export const stagingPathOf = (destination) => `${destination}${STAGING_SUFFIX}`;
+
+const exists = (fs, file) => {
+  if (typeof fs.lstatSync !== "function") return fs.existsSync(file);
+  try { fs.lstatSync(file); return true; } catch (error) { if (error?.code === "ENOENT") return false; throw error; }
+};
+
+/**
+ * Swap `staging` into `destination`: the old destination becomes `previous` (replacing any older `.previous`),
+ * then `verify(destination)` runs. Any failure removes the new copy and renames `previous` back, so the fixed
+ * path is never left empty. Renames only: no copy, no new path.
+ * @returns {{destination: string, previous: string|null}} previous is null when nothing was installed before.
+ */
+export function swapInPlace({ staging, destination, previous = previousPathOf(destination), verify = () => {}, fs = nodeFs }) {
+  if (previous === destination || staging === destination || staging === previous) throw new Error("swapInPlace needs three distinct paths");
+  let movedAside = false;
+  try {
+    if (exists(fs, destination)) {
+      if (exists(fs, previous)) fs.rmSync(previous, { recursive: true, force: true });
+      fs.renameSync(destination, previous);
+      movedAside = true;
+    }
+    fs.renameSync(staging, destination);
+    verify(destination);
+  } catch (error) {
+    try { fs.rmSync(destination, { recursive: true, force: true }); } catch { /* keep the original error */ }
+    if (movedAside && exists(fs, previous)) fs.renameSync(previous, destination);
+    try { fs.rmSync(staging, { recursive: true, force: true }); } catch { /* best effort */ }
+    throw error;
+  }
+  return { destination, previous: movedAside ? previous : null };
+}
+
+/** Copy one file to its fixed path in place: temp sibling, then rename, keeping `<file>.previous`. Returns the path. */
+export function replaceFileInPlace(from, destination, { fs = nodeFs } = {}) {
+  fs.mkdirSync(path.dirname(destination), { recursive: true });
+  const staging = stagingPathOf(destination);
+  fs.rmSync(staging, { force: true });
+  fs.copyFileSync(from, staging);
+  swapInPlace({ staging, destination });
+  return destination;
+}

package/install-app-windows.mjs

@@ -0,0 +1,63 @@
+import nodeFs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { spawnSync } from "./background-process.mjs";
+import { previousPathOf } from "./in-place-install.mjs";
+
+/**
+ * `right-release install-app --installer <Setup.exe> --dest <install folder> --exe <App.exe>` on Windows (Orthic-Labs/rightkit#258).
+ *
+ * The same rule as the macOS install: the app is installed and updated IN PLACE at one fixed folder (`--dest`, the
+ * folder the NSIS installer already owns, for example `%LOCALAPPDATA%\Programs\Pulse`). Rollback is one
+ * `<dest>.previous` beside it (a copy of the folder as it was; replaced on each install; nothing runs from it), never a
+ * versioned, digest or per-run folder. The silent installer is pinned to the fixed folder with `/D=` so it cannot choose another one.
+ *
+ * Why a copy and not a rename: a running app holds its folder open on Windows, so a rename fails; the installer closes
+ * the app and updates the same path in place instead. A failed install copies `<dest>.previous` back over `<dest>`.
+ */
+export class InstallAppWindowsError extends Error {
+  constructor(code, message) { super(message); this.name = "InstallAppWindowsError"; this.code = code; }
+}
+
+export function windowsInstallArguments(dest) {
+  // NSIS: /D must be the last argument, unquoted, and names the install folder.
+  return ["/S", `/D=${dest}`];
+}
+
+const sha256 = (fs, file) => createHash("sha256").update(fs.readFileSync(file)).digest("hex");
+
+export function installAppWindows(opts, { platform = process.platform, fs = nodeFs, run = spawnSync, event = () => {} } = {}) {
+  if (platform !== "win32") throw new InstallAppWindowsError("unsupported", `the Windows installer mode runs on win32, not ${platform}`);
+  const { installer, dest, exe } = opts;
+  if (!installer || !path.win32.isAbsolute(installer)) throw new InstallAppWindowsError("usage", "--installer must be an absolute path to the NSIS setup executable");
+  if (!dest || !path.win32.isAbsolute(dest) || path.win32.parse(dest).root === dest) throw new InstallAppWindowsError("usage", "--dest must be the fixed absolute install folder, not a drive root");
+  if (!exe || exe !== path.win32.basename(exe)) throw new InstallAppWindowsError("usage", "--exe must be the bare executable name inside --dest");
+  if (!fs.existsSync(installer)) throw new InstallAppWindowsError("installer-missing", `installer not found: ${installer}`);
+  const previous = previousPathOf(dest);
+  const installed = path.win32.join(dest, exe);
+  const hadInstall = fs.existsSync(dest);
+  event("start", { installer, dest, replacing: hadInstall });
+  if (hadInstall) {
+    // One rollback copy, replaced on every install.
+    fs.rmSync(previous, { recursive: true, force: true });
+    fs.cpSync(dest, previous, { recursive: true });
+    event("previous-kept", { previous });
+  }
+  const restore = () => {
+    if (!hadInstall || !fs.existsSync(previous)) return false;
+    fs.cpSync(previous, dest, { recursive: true, force: true });
+    return true;
+  };
+  const result = run(installer, windowsInstallArguments(dest), { stdio: "inherit", windowsHide: true, shell: false });
+  if (result.status !== 0) {
+    const restored = restore();
+    throw new InstallAppWindowsError("installer-failed", `installer exited ${result.status ?? "abnormally"}${result.error ? `: ${result.error.message}` : ""}; ${restored ? `restored ${dest} from ${previous}` : "nothing was installed before"}`);
+  }
+  // The installer must have updated the fixed folder: the executable is at the same path as before, not in a new folder.
+  if (!fs.existsSync(installed) || fs.statSync(installed).size === 0) {
+    const restored = restore();
+    throw new InstallAppWindowsError("path-changed", `the installer did not place ${exe} at the fixed path ${installed}; ${restored ? `restored from ${previous}` : "nothing was installed before"}`);
+  }
+  event("replaced", { installed, previous: hadInstall ? previous : null, sha256: sha256(fs, installed) });
+  return { ok: true, installed, previous: hadInstall ? previous : null };
+}

package/install-app.mjs

@@ -4,6 +4,9 @@
 // Never uses a shell, osascript, AppleEvents, or foreground activation.
 import { execFile as nodeExecFile, execFileSync as nodeExecFileSync } from "./background-process.mjs";
 import { detachWithRetry } from "./hdiutil-detach.mjs";
+import { previousPathOf } from "./in-place-install.mjs";
+import { assertShippedSwapHelperSigned } from "./swap-helper-bundle.mjs";
+import { installAppWindows, InstallAppWindowsError } from "./install-app-windows.mjs";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -19,11 +22,11 @@ export class InstallAppError extends Error {
   }
 }
 
-const VALUE_FLAGS = new Set(["--dmg", "--zip", "--app", "--app-name", "--bundle-id", "--dest"]);
+const VALUE_FLAGS = new Set(["--dmg", "--zip", "--app", "--app-name", "--bundle-id", "--dest", "--installer", "--exe"]);
 const BOOL_FLAGS = new Set(["--relaunch", "--no-relaunch", "--json", "--dev", "--recover"]);
 
 export function parseArgs(argv) {
-  const opts = { dmg: null, zip: null, app: null, dev: false, appName: null, bundleId: null, dest: "/Applications", relaunch: null, json: false, recover: false };
+  const opts = { dmg: null, zip: null, app: null, installer: null, exe: null, dev: false, appName: null, bundleId: null, dest: "/Applications", relaunch: null, json: false, recover: false };
   for (let i = 0; i < argv.length; i += 1) {
     const flag = argv[i];
     if (VALUE_FLAGS.has(flag)) {
@@ -35,6 +38,8 @@ export function parseArgs(argv) {
       else if (flag === "--app") opts.app = value;
       else if (flag === "--app-name") opts.appName = value;
       else if (flag === "--bundle-id") opts.bundleId = value;
+      else if (flag === "--installer") opts.installer = value;
+      else if (flag === "--exe") opts.exe = value;
       else opts.dest = value;
     } else if (BOOL_FLAGS.has(flag)) {
       if (flag === "--json") opts.json = true;
@@ -45,6 +50,12 @@ export function parseArgs(argv) {
       throw new InstallAppError("usage", `unknown argument: ${flag}`);
     }
   }
+  if (opts.installer !== null) {
+    // Windows: run the sealed NSIS installer in place at one fixed folder, keeping <dest>.previous.
+    if (opts.dmg !== null || opts.zip !== null || opts.app !== null || opts.recover || opts.dev) throw new InstallAppError("usage", "--installer cannot be combined with --dmg, --zip, --app, --dev or --recover");
+    if (!argv.includes("--dest") || opts.exe === null) throw new InstallAppError("usage", "--installer requires --dest <fixed install folder> and --exe <App.exe>");
+    return opts;
+  }
   if (argv.includes("--relaunch") && argv.includes("--no-relaunch")) throw new InstallAppError("usage", "--relaunch and --no-relaunch are mutually exclusive");
   const inputs = [opts.dmg, opts.zip, opts.app].filter((v) => v !== null).length;
   if (opts.recover) {
@@ -220,10 +231,15 @@ function coded(code, message) {
 
 // Sync on purpose: signal-handler rollback must be able to swap back. Throws an error whose `code`
 // is in SWAP_FALLBACK_CODES when no atomic swap is possible here (no helper, or exit 3 / ENOTSUP / EINVAL).
-export function createSwapPaths({ env = process.env, resolve = resolveSwapHelper, execFileSync = nodeExecFileSync } = {}) {
+// A helper that exists must be code-signed (#258): an unsigned one is a typed SWAP_HELPER_UNSIGNED error naming the fix,
+// never a silent downgrade. No helper at all keeps the documented journaled two-rename fallback, which is logged
+// (`swap-fallback`, then `replaced {swap}`).
+export function createSwapPaths({ env = process.env, resolve = resolveSwapHelper, execFileSync = nodeExecFileSync, assertSigned = assertShippedSwapHelperSigned } = {}) {
+  const checked = new Set();
   return (a, b) => {
     const helper = resolve({ env });
     if (!helper) throw coded("ENOHELPER", `${SWAP_HELPER_NAME} helper not found`);
+    if (!checked.has(helper)) { assertSigned({ file: helper, execFileSync }); checked.add(helper); }
     try { execFileSync(helper, [a, b], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }); }
     catch (error) {
       const text = `${error?.stderr || ""}`.trim();
@@ -251,12 +267,15 @@ const defaultIsAlive = (pid) => {
   try { process.kill(pid, 0); return true; } catch (e) { return e.code === "EPERM"; }
 };
 
-async function trashBundle(run, fsImpl, home, now, bundle, appName) {
-  const trashDir = path.join(home, ".Trash");
-  fsImpl.mkdirSync(trashDir, { recursive: true });
-  const trashed = path.join(trashDir, trashName(appName, now()));
-  await moveAside(run, fsImpl, bundle, trashed);
-  return trashed;
+// Keep the bundle it replaced as `<installed>.previous` beside the fixed path (replacing any older one), by rename.
+// Rollback is renaming it back; nothing ever runs from it. It is never sent to the Trash: a Trash copy is a second
+// path macOS can resolve for the same bundle id.
+async function keepPreviousBundle(run, fsImpl, bundle, installed) {
+  const previous = previousPathOf(installed);
+  if (bundle === previous) return previous;
+  fsImpl.rmSync(previous, { recursive: true, force: true });
+  await moveAside(run, fsImpl, bundle, previous);
+  return previous;
 }
 
 // Deterministic roll-forward/back of any interrupted install journal in `dest`. Idempotent.
@@ -292,8 +311,8 @@ export async function recoverInstalls({ dest, appName = null, run, fsImpl, home,
           let ok = j.phase === "verified";
           if (!ok) { try { await verifyBundle(run, j.installed, { assess: !j.dev, staple: false }); ok = true; } catch { ok = false; } }
           if (ok) {
-            try { await trashBundle(run, fsImpl, home, now, j.staged, path.basename(j.installed)); action = "rolled-forward"; }
-            catch { action = "rolled-forward-trash-pending"; keepJournal = true; keepStaged = true; }
+            try { await keepPreviousBundle(run, fsImpl, j.staged, j.installed); action = "rolled-forward"; }
+            catch { action = "rolled-forward-previous-pending"; keepJournal = true; keepStaged = true; }
           } else {
             swapBack(swapPaths, fsImpl, j.staged, j.installed); // staged now holds the bad new bundle
             action = "rolled-back";
@@ -306,8 +325,8 @@ export async function recoverInstalls({ dest, appName = null, run, fsImpl, home,
         let ok = j.phase === "verified";
         if (!ok) { try { await verifyBundle(run, j.installed, { assess: !j.dev, staple: false }); ok = true; } catch { ok = false; } }
         if (ok) {
-          try { await trashBundle(run, fsImpl, home, now, j.backup, path.basename(j.installed)); action = "rolled-forward"; }
-          catch { action = "rolled-forward-trash-pending"; keepJournal = true; }
+          try { await keepPreviousBundle(run, fsImpl, j.backup, j.installed); action = "rolled-forward"; }
+          catch { action = "rolled-forward-previous-pending"; keepJournal = true; }
         } else {
           rm(j.installed);
           fsImpl.renameSync(j.backup, j.installed);
@@ -376,7 +395,7 @@ export async function installApp(opts, deps = {}) {
       if (s.mode === "atomic") {
         // installed was never absent. Before the exchange only the staged copy needs removing; after it,
         // exchange back (installed = old again, staged = the new copy) and drop the new copy. Once final,
-        // staged holds the verified-old bundle awaiting the Trash, so it must not be touched.
+        // staged holds the verified-old bundle awaiting retirement to .previous, so it must not be touched.
         if (!s.final) {
           if (s.swapped) swapBack(swapPaths, fsImpl, s.staged, s.installed);
           removeQuiet(s.staged);
@@ -486,8 +505,9 @@ export async function installApp(opts, deps = {}) {
     // Stage a verified copy on the destination volume so the swap is rename(2) only.
     failedStage = "stage";
     const base = appName.replace(/\.app$/, "");
+    // Staging is never run from: it is verified, then renamed into place. The rollback copy is the fixed `<installed>.previous`.
     const staged = path.join(opts.dest, `.${base}.rightkit-install-${pid}.app`);
-    const backup = hadInstalled ? path.join(opts.dest, `.${base}.rightkit-backup-${pid}.app`) : null;
+    const backup = hadInstalled ? previousPathOf(installed) : null;
     const journal = journalPathFor(opts.dest, appName);
     const journalData = { schema: 1, appName, pid, phase: "staging", dev, installed, backup, staged, mount: mountPoint, mountRoot };
     removeQuiet(staged);
@@ -512,7 +532,7 @@ export async function installApp(opts, deps = {}) {
 
     // Swap. Preferred: one atomic exchange (renamex_np RENAME_SWAP), so `installed` is never absent even
     // under SIGKILL; the old bundle then sits at the staged path. Fallback (no helper, or a volume without
-    // RENAME_SWAP): old -> backup, staged -> installed, journaled. The old bundle is never trashed before
+    // RENAME_SWAP): old -> backup, staged -> installed, journaled. The old bundle is never retired before
     // the new one is verified.
     failedStage = "replace";
     let jd = journalData;
@@ -535,6 +555,7 @@ export async function installApp(opts, deps = {}) {
         swap.mode = "two-rename";
         jd = { ...journalData, swap: "two-rename" };
         writeJournal(fsImpl, journal, { ...jd, phase: "swapping" });
+        removeQuiet(backup); // an older .previous; the one kept copy is the bundle moving aside now
         fsImpl.renameSync(installed, backup); swap.backedUp = true;
         fsImpl.renameSync(staged, installed);
         swap.stagedIn = true;
@@ -555,16 +576,18 @@ export async function installApp(opts, deps = {}) {
     writeJournal(fsImpl, journal, { ...jd, phase: "verified", mount: null, mountRoot: null });
     swap.final = true;
 
-    // Only now does the old bundle go to the Trash.
-    let trashed = null;
+    // Only now is the old bundle retired, to <installed>.previous (never the Trash).
+    let kept = null;
+    let keepFailed = false;
     const oldBundle = swapMode === "atomic" ? staged : backup; // atomic: the exchange left the old bundle at the staged path
     if (hadInstalled && oldBundle) {
-      try { trashed = await trashBundle(run, fsImpl, home, now, oldBundle, appName); }
-      catch (error) { event("backup-trash-failed", { backup: oldBundle, reason: errText(error) }); trashed = oldBundle; }
+      try { kept = await keepPreviousBundle(run, fsImpl, oldBundle, installed); }
+      catch (error) { event("previous-keep-failed", { backup: oldBundle, reason: errText(error) }); kept = oldBundle; }
     }
-    if (!oldBundle || trashed !== oldBundle) removeQuiet(journal);
+    if (!oldBundle || kept !== previousPathOf(installed)) { if (!oldBundle) removeQuiet(journal); }
+    else removeQuiet(journal);
     swap = null;
-    event("replaced", { installed, previous: trashed, swap: swapMode });
+    event("replaced", { installed, previous: kept, swap: swapMode });
 
     // Relaunch hidden and in the background only.
     const relaunch = opts.relaunch === null ? wasRunning : opts.relaunch;
@@ -573,7 +596,7 @@ export async function installApp(opts, deps = {}) {
       await run("/usr/bin/open", ["-g", "-j", "-b", bundleId]);
       event("relaunched", { bundleId });
     }
-    const result = { ok: true, app: appName, installed, bundleId, teamId: newTeam, previous: trashed, swap: swapMode, relaunched: relaunch, ...(dev ? { dev: true } : {}) };
+    const result = { ok: true, app: appName, installed, bundleId, teamId: newTeam, previous: kept, swap: swapMode, relaunched: relaunch, ...(dev ? { dev: true } : {}) };
     event("done", result);
     return result;
   } catch (error) {
@@ -685,6 +708,7 @@ export async function main(argv = process.argv.slice(2), io = {}) {
     stderr(`right-release install-app: ${error.message}`);
     stderr("usage: right-release install-app (--dmg <path.dmg> | --dev (--zip <path.zip> | --app <path.app> | --dmg <path.dmg>)) [--app-name Pulse.app] [--bundle-id dev.orthic.pulse] [--dest /Applications] [--relaunch|--no-relaunch] [--json]");
     stderr("       right-release install-app --recover [--dest /Applications] [--app-name Pulse.app] [--json]");
+    stderr("       right-release install-app --installer <Setup.exe> --dest <fixed install folder> --exe <App.exe> [--json]   (Windows: in place, keeps <dest>.previous)");
     stderr("  --dev installs a Developer ID-signed, NOT notarized build (skips spctl/stapler, clears quarantine on the new bundle).");
     return 2;
   }
@@ -696,10 +720,16 @@ export async function main(argv = process.argv.slice(2), io = {}) {
     else stdout(`install-app: ${event}${Object.keys(rest).length ? ` ${JSON.stringify(rest)}` : ""}`);
   };
   try {
+    if (opts.installer !== null) {
+      installAppWindows(opts, { ...io.deps, event: (name, data = {}) => emit({ event: name, ...data }) });
+      emit({ event: "done", dest: opts.dest });
+      return 0;
+    }
     if (opts.recover) await recoverApp(opts, { ...io.deps, emit });
     else await installApp(opts, { ...io.deps, emit });
     return 0;
   } catch (error) {
+    if (error instanceof InstallAppWindowsError) { stderr(`install-app: ${error.code}: ${error.message}`); return error.code === "unsupported" ? 3 : 1; }
     return error.code === "unsupported" ? 3 : 1;
   }
 }

package/local-publish.mjs

@@ -17,7 +17,8 @@ import { GATE_SCHEMA, defaultEvidencePath, enforcePublicationGate, publishGatedT
 import { runCargoPublish } from "./publish-cargo.mjs";
 import { cargoIndexUrl } from "./cargo-registry-readback.mjs";
 import { readCargoPackage } from "./crate-graph.mjs";
-import { recordPublished } from "./rightkit-sync.mjs";
+import { recordPublished, stageSourceVersions } from "./rightkit-sync.mjs";
+import { prepareSwapHelper, SWAP_HELPER_CARGO_ARGS, SWAP_HELPER_PACKAGE } from "./swap-helper-bundle.mjs";
 
 export const LOCAL_OPERATOR = "agent (local-build grant)";
 export const LOCAL_HOST_POLICY_REASON = "Adrian 2026-10-14 local-build grant (.rightkit-local-build.json); Windows covered by the next CI run";
@@ -194,7 +195,16 @@ export async function runLocalPublish(kind, argv, deps = {}) {
   const cleanup = () => fs.rmSync(scratch, { recursive: true, force: true });
   try {
     let artifactFile; const packCommands = [];
+    if (kind === "npm" && unit === SWAP_HELPER_PACKAGE) {
+      // #258: the package ships a Developer-ID-signed bin/darwin/rightkit-swap; build, sign and verify it before packing (fails closed).
+      try { (deps.prepareSwapHelper ?? prepareSwapHelper)({ workspaceRoot, packageDir: unitPath, platform, run, env, log }); }
+      catch (error) { refuse(`${error.code ? `[${error.code}] ` : ""}${error.message}`); }
+      packCommands.push(`rightkit cargo ${SWAP_HELPER_CARGO_ARGS.join(" ")} && codesign --verify --strict bin/darwin/rightkit-swap`);
+    }
     if (kind === "npm") {
+      // The feed a tarball ships must list the version it ships with (#319): stage it before packing.
+      const feedFile = path.join(workspaceRoot, "packages", "release", "rightkit-versions.json");
+      if (fs.existsSync(feedFile)) (deps.stageSourceVersions ?? stageSourceVersions)([{ registry: "npm", name: unit, version }], { file: feedFile, root: workspaceRoot, log });
       const args = ["--dir", dir, "pack", "--pack-destination", scratch];
       packCommands.push(`pnpm ${args.join(" ")}`);
       const packed = run("pnpm", args, { cwd: workspaceRoot, env });

package/mac-signing-matrix.mjs

@@ -1,8 +1,9 @@
 // Per-file macOS signing matrix for `sign.prePackageFiles[]` object entries and `sign.nestedCode`.
 //
 //   sign: {
-//     prePackageFiles: ["dist/tool", { file: "dist/App.app", entitlements: "release/app.entitlements.plist" }],
-//     nestedCode: { "Contents/Helpers/Helper": { options: ["library"] },
+//     prePackageFiles: ["dist/tool", { file: "dist/App.app", entitlements: "release/app.entitlements.plist" },
+//                       { file: "dist/legion-hook", identifier: "com.example.legion-hook" }],
+//     nestedCode: { "Contents/Helpers/Helper": { options: ["library"], identifier: "com.example.helper" },
 //                   "Contents/PlugIns/Ext.appex": { entitlements: "release/ext.entitlements.plist" } },
 //   }
 //
@@ -16,8 +17,12 @@ const invalid = (message) => Object.assign(new Error(message), { code: "MAC_SIGN
 
 /** codesign `--options` names accepted in `options[]` (man codesign, OPTION FLAGS). `runtime` is always on. */
 export const CODESIGN_OPTION_FLAGS = Object.freeze(["expires", "hard", "host", "kill", "library", "runtime"]);
-const ENTRY_KEYS = new Set(["file", "entitlements", "hardenedRuntime", "options"]);
-const SETTING_KEYS = new Set(["entitlements", "hardenedRuntime", "options"]);
+const ENTRY_KEYS = new Set(["file", "entitlements", "hardenedRuntime", "options", "identifier"]);
+const SETTING_KEYS = new Set(["entitlements", "hardenedRuntime", "options", "identifier"]);
+// A stable per-file code identity: codesign `--identifier`. A loose tool otherwise gets an identifier derived from its file
+// name or cdhash, and macOS keys privacy grants (TCC) to the code identity, so it must not change between builds.
+// Same pattern as mac-sign-core.mjs (not imported: that module imports this one).
+const IDENTIFIER_PATTERN = /^[A-Za-z0-9][A-Za-z0-9.-]{0,254}$/;
 
 const isPlainObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
 
@@ -33,7 +38,11 @@ function looksLikePlist(file) {
 }
 
 function validateSettings(settings, label, { root, errors, isFile }) {
-  const out = { entitlements: undefined, hardenedRuntime: true, options: [] };
+  const out = { entitlements: undefined, hardenedRuntime: true, options: [], identifier: undefined };
+  if (settings.identifier !== undefined) {
+    if (typeof settings.identifier !== "string" || !IDENTIFIER_PATTERN.test(settings.identifier)) errors.push(`${label}.identifier must be 1-255 characters of letters, digits, '.' and '-', starting with a letter or digit`);
+    else out.identifier = settings.identifier;
+  }
   if (settings.entitlements !== undefined) {
     const value = settings.entitlements;
     if (typeof value !== "string" || !value.trim()) errors.push(`${label}.entitlements must be a non-empty path string`);
@@ -79,8 +88,8 @@ function validateNestedKey(key) {
 /**
  * Validate and normalize `sign` for a macOS target. Collects every problem, then throws one
  * MAC_SIGN_CONFIG_INVALID error. Returns { entries, nestedCode } where
- *   entries:    [{ file, entitlements?: absolute, options: [] }]   (file stays as declared)
- *   nestedCode: [{ key, entitlements?: absolute, options: [] }]
+ *   entries:    [{ file, identifier?, entitlements?: absolute, options: [] }]   (file stays as declared)
+ *   nestedCode: [{ key, identifier?, entitlements?: absolute, options: [] }]
  * Injectable: isFile.
  */
 export function validateMacSigningConfig(sign, { root, isFile = (file) => existsSync(file) && statSync(file).isFile() } = {}) {
@@ -106,7 +115,7 @@ export function validateMacSigningConfig(sign, { root, isFile = (file) => exists
       if (seen.has(file)) errors.push(`${label}: duplicate signing entry ${file}`);
       seen.add(file);
       const normalized = validateSettings(settings, label, context);
-      entries.push({ file, ...(normalized.entitlements ? { entitlements: normalized.entitlements } : {}), options: normalized.options });
+      entries.push({ file, ...(normalized.identifier ? { identifier: normalized.identifier } : {}), ...(normalized.entitlements ? { entitlements: normalized.entitlements } : {}), options: normalized.options });
     });
   }
   if (sign.nestedCode !== undefined) {
@@ -119,7 +128,7 @@ export function validateMacSigningConfig(sign, { root, isFile = (file) => exists
         if (!isPlainObject(settings)) { errors.push(`${label} must be an object { entitlements?, hardenedRuntime?, options? }`); continue; }
         for (const name of Object.keys(settings)) if (!SETTING_KEYS.has(name)) errors.push(`${label}: unknown key ${JSON.stringify(name)} (allowed: ${[...SETTING_KEYS].join(", ")})`);
         const normalized = validateSettings(settings, label, context);
-        nestedCode.push({ key, ...(normalized.entitlements ? { entitlements: normalized.entitlements } : {}), options: normalized.options });
+        nestedCode.push({ key, ...(normalized.identifier ? { identifier: normalized.identifier } : {}), ...(normalized.entitlements ? { entitlements: normalized.entitlements } : {}), options: normalized.options });
       }
       if (nestedCode.length) {
         const apps = entries.filter((entry) => /\.app\/?$/.test(entry.file));
@@ -132,7 +141,7 @@ export function validateMacSigningConfig(sign, { root, isFile = (file) => exists
 }
 
 /** True when an entry or nested item carries anything beyond the default (hardened runtime, no entitlements). */
-export const hasNonDefaultSettings = (item) => Boolean(item.entitlements) || (item.options?.length ?? 0) > 0;
+export const hasNonDefaultSettings = (item) => Boolean(item.entitlements) || Boolean(item.identifier) || (item.options?.length ?? 0) > 0;
 
 const depth = (file) => file.split(path.sep).length;
 
@@ -162,7 +171,7 @@ export function planMacSigning({ entries, nestedCode = [], expand = expandMacSig
       const real = realpath(file);
       if (real !== appReal && !real.startsWith(appReal + path.sep)) throw invalid(`${label}: resolves outside the bundle`);
       if (real === mainReal) throw invalid(`${label}: the main executable is signed with the bundle; set entitlements on its sign.prePackageFiles entry`);
-      byPath.set(file, { file, ...(item.entitlements ? { entitlements: item.entitlements } : {}), options: item.options });
+      byPath.set(file, { file, ...(item.identifier ? { identifier: item.identifier } : {}), ...(item.entitlements ? { entitlements: item.entitlements } : {}), options: item.options });
     }
   }
   const nested = [...byPath.values()].sort((a, b) => depth(b.file) - depth(a.file) || a.file.localeCompare(b.file));
@@ -178,6 +187,9 @@ export function matrixReceiptProblems(evidenceFiles, entries, hashFile) {
     if (!item) { problems.push(`missing receipt entry for ${entry.file}`); continue; }
     const wantOptions = ["runtime", ...(entry.options ?? [])].join(",");
     if ((item.codesignOptions ?? "runtime") !== wantOptions) problems.push(`${entry.file}: signed with options ${item.codesignOptions ?? "runtime"}, expected ${wantOptions}`);
+    if (entry.identifier) {
+      if (item.identifier !== entry.identifier) problems.push(`${entry.file}: signed with identifier ${item.identifier ?? "(none recorded)"}, expected ${entry.identifier}`);
+    } else if (item.identifier) problems.push(`${entry.file}: signed with identifier ${item.identifier} the plan did not declare`);
     if (entry.entitlements) {
       if (item.entitlements?.sha256 !== hashFile(entry.entitlements)) problems.push(`${entry.file}: receipt entitlements digest does not match ${entry.entitlements}`);
     } else if (item.entitlements) problems.push(`${entry.file}: signed with entitlements the plan did not declare`);

package/managed-cargo.mjs

@@ -1,5 +1,6 @@
 import { discoverBrokerSocket, managedControlCandidates, resolveManagedRoots } from './managed-roots.mjs';
 import { randomUUID } from "node:crypto";
+import { homedir } from "node:os";
 import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { spawnSync } from "./background-process.mjs";
@@ -12,6 +13,11 @@ export function managedRuntimeClient(env = process.env, platform = process.platf
     const client = paths.join(root, "runtime-current", platform === 'win32' ? "rustright.exe" : "rustright");
     if (exists(client)) return client;
   }
+  // RustRight's own install (2026-10-17 cutover): the Mac agent-bin shims exec this client directly.
+  if (platform === 'darwin') {
+    const client = path.posix.join(env.HOME || homedir(), 'Library', 'Application Support', 'RustRight', 'runtime', 'rustright');
+    if (exists(client)) return client;
+  }
   return undefined;
 }