@rightkit/release 0.2.133 → 0.2.135

package/artifact-storage.mjs

@@ -11,6 +11,7 @@ import {
   writeFileSync,
 } from "node:fs";
 import path from "node:path";
+import os from "node:os";
 
 export const ARTIFACT_MARKER_SCHEMA = 1;
 export const DEFAULT_MANAGED_ROOT = process.platform === "win32"
@@ -19,9 +20,12 @@ export const DEFAULT_MANAGED_ROOT = process.platform === "win32"
 
 const SAFE_COMPONENT = /^[A-Za-z0-9][A-Za-z0-9._+-]{0,159}$/;
 
-export function resolveManagedRoot({ env = process.env } = {}) {
-  const value = env.RIGHTKIT_MANAGED_ROOT || DEFAULT_MANAGED_ROOT;
-  return path.resolve(value);
+export function resolveManagedRoot({ env = process.env, exists = existsSync } = {}) {
+  if (env.RIGHTKIT_MANAGED_ROOT) return path.resolve(env.RIGHTKIT_MANAGED_ROOT);
+  // Workstation default only when its drive exists; hosted CI runners fall back to RUNNER_TEMP, then the system temp dir.
+  const volume = process.platform === "win32" ? "D:\\" : "/Volumes/D";
+  if (exists(volume)) return path.resolve(DEFAULT_MANAGED_ROOT);
+  return path.join(env.RUNNER_TEMP && exists(env.RUNNER_TEMP) ? env.RUNNER_TEMP : os.tmpdir(), "rightkit-managed");
 }
 
 export function resolveArtifactRoot({ app, managedRoot } = {}) {

package/build-release.mjs

@@ -39,13 +39,14 @@ import { acquireHeavyWorkSlot, heavyCommandEnvironment, summarizePreBrokerWaits,
 import { processGroupCpuSeconds } from "./process-liveness.mjs";
 import { cancelAndReapManagedRequest, firstManagedRequestId, releaseProgressLimits } from "./progress-control.mjs";
 import { beginArtifactLease, completeArtifactLease, materializeArtifacts, retainArtifacts, resolveArtifactDir, resolveManagedRoot } from "./artifact-storage.mjs";
+import { macosCodesignEnvironment } from "./codesign-environment.mjs";
 
 // Fingerprint of the pipeline code that can change the bytes we ship or the way
 // they are signed — deliberately NOT the package version, which moves for docs
 // and test-only edits and would force a cold Rust rebuild of every app each time.
 // Cached target directories must not outlive changes to these signing helpers.
 
-const PIPELINE_FINGERPRINT_SOURCES = ["release.mjs", "sign-windows.mjs", "sign-macos.mjs", "macos-signing-session.mjs", "notarize-macos.mjs", "macos-notarization.mjs", "signing-receipts.mjs", "tauri-bundle-marker.mjs", "nsis-payload.mjs"];
+const PIPELINE_FINGERPRINT_SOURCES = ["release.mjs", "sign-windows.mjs", "sign-macos.mjs", "macos-signing-session.mjs", "codesign-environment.mjs", "codesign-shim.mjs", "codesign-argv.mjs", "rightkit-signing-agent.mjs", "notarize-macos.mjs", "macos-notarization.mjs", "signing-receipts.mjs", "tauri-bundle-marker.mjs", "nsis-payload.mjs"];
 const PIPELINE_FINGERPRINT = createHash("sha256")
   .update(PIPELINE_FINGERPRINT_SOURCES.map((file) => `${file}:${createHash("sha256").update(readFileSync(path.join(path.dirname(fileURLToPath(import.meta.url)), file))).digest("hex")}`).join("\n"))
   .digest("hex")
@@ -251,7 +252,7 @@ try {
   // resolves to MSYS Perl, which cannot configure OpenSSL. Put the real Windows
   // Perl first so the build behaves the same from any shell.
   const pathPrefix = buildPathPrefix({ platform });
-  const env = {
+  const env = macosCodesignEnvironment({
     ...heavyCommandEnvironment(process.env),
     ...releaseEnvironment({ root: vaultRoot, cacheRoot: sharedCacheRoot, platform, architecture: cacheIdentity.architecture, app: config.app, cacheKey, kind: "release", appRoot, mode: cacheMode }),
     ...(pathPrefix ? { PATH: `${pathPrefix}${path.delimiter}${process.env.PATH ?? ""}` } : {}),
@@ -259,7 +260,7 @@ try {
     RIGHT_RELEASE_APP_ROOT: layout.appRoot,
     RIGHTKIT_MANAGED_ROOT: resolveManagedRoot({ env: process.env }),
     RIGHT_RELEASE_ARTIFACT_DIR: resolveArtifactDir({ app: config.app, version: config.version, managedRoot: resolveManagedRoot({ env: process.env }) }),
-  };
+  });
   if (managedCargoTarget) {
     for (const name of ["CARGO_HOME", "CARGO_TARGET_DIR", "RUSTC_WRAPPER", "SCCACHE_DIR", "SCCACHE_BASEDIRS", "SCCACHE_CACHE_SIZE", "RUSTFLAGS"]) {
       delete env[name];

package/codesign-argv.mjs

@@ -0,0 +1,64 @@
+import path from "node:path";
+
+// Closed grammar shared by shim & agent. Never accept executable names, an
+// environment, keychains, detached signatures, or file-producing display flags.
+export function parseCodesignArgv(argv, cwd) {
+  const deny = () => { const error = new Error("Unsupported codesign argv"); error.code = "MAC_SIGNING_AGENT_ARGV_DENIED"; throw error; };
+  if (!Array.isArray(argv) || !argv.length || argv.length > 8192
+    || argv.some((arg) => typeof arg !== "string" || !arg || arg.includes("\0") || arg.length > 32768)
+    || typeof cwd !== "string" || !path.isAbsolute(cwd)) deny();
+  const targets = [], inputs = [], options = [];
+  let mode, verbose = false, operands = false;
+  const operation = (next) => { if (mode) deny(); mode = next; };
+  const value = (inline, i) => {
+    const result = inline ?? argv[i + 1];
+    if (!result || result.startsWith("--")) deny();
+    return result;
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (operands || !arg.startsWith("-")) { targets.push(path.isAbsolute(arg) ? arg : `${cwd}/${arg}`); continue; }
+    if (arg === "--") { operands = true; continue; }
+    if (/^-[dv]+$/.test(arg)) {
+      if (arg.includes("d")) { if ((arg.match(/d/g) ?? []).length !== 1) deny(); operation("display"); }
+      if (arg.includes("v")) verbose = true;
+      continue;
+    }
+    const equal = arg.indexOf("=");
+    const flag = equal < 0 ? arg : arg.slice(0, equal);
+    const inline = equal < 0 ? undefined : arg.slice(equal + 1);
+    if (flag === "--display" && inline === undefined) { operation("display"); continue; }
+    if (flag === "--verify" && inline === undefined) { operation("verify"); continue; }
+    if (flag === "--verbose") { if (inline !== undefined && !/^\d{1,2}$/.test(inline)) deny(); verbose = true; continue; }
+    if (["-s", "--sign"].includes(flag) || /^-s.+/.test(arg)) {
+      const attached = flag === "-s" || flag === "--sign" ? inline : arg.slice(2);
+      const identity = value(attached, i);
+      if (identity.length > 512 || (identity.startsWith("-") && identity !== "-")) deny();
+      operation("sign"); if (attached === undefined) i++;
+      continue;
+    }
+    if (["--force", "--deep", "--strict"].includes(flag) && inline === undefined) { options.push(flag); continue; }
+    if (flag === "--timestamp" && (inline === undefined || inline === "none")) { options.push(flag); continue; }
+    if (["--options", "--identifier", "--preserve-metadata", "--entitlements", "--requirements"].includes(flag) || arg === "-r-") {
+      const parameter = arg === "-r-" ? "-" : value(inline, i);
+      if (arg !== "-r-" && inline === undefined) i++;
+      if (flag === "--options" && !/^(runtime|hard|kill|host|expires|restrict|library)(,(runtime|hard|kill|host|expires|restrict|library))*$/.test(parameter)) deny();
+      if (flag === "--preserve-metadata" && !/^(identifier|entitlements|requirements|flags|runtime)(,(identifier|entitlements|requirements|flags|runtime))*$/.test(parameter)) deny();
+      if (flag === "--identifier" && (parameter.startsWith("-") || parameter.length > 512)) deny();
+      options.push(arg === "-r-" ? "--requirements" : flag);
+      if (flag === "--entitlements") inputs.push({ value: parameter, path: path.isAbsolute(parameter) ? parameter : `${cwd}/${parameter}` });
+      if ((flag === "--requirements" || arg === "-r-") && parameter !== "-") deny();
+      continue;
+    }
+    deny();
+  }
+  mode ??= verbose ? "verify" : undefined;
+  if (!mode || !targets.length || targets.length > 4096) deny();
+  const permitted = mode === "sign"
+    ? ["--force", "--options", "--timestamp", "--entitlements", "--deep", "--preserve-metadata", "--identifier"]
+    : mode === "verify" ? ["--strict", "--deep"] : ["--entitlements", "--requirements"];
+  if (options.some((flag) => !permitted.includes(flag))) deny();
+  if (mode === "display" && inputs.some((input) => ![":-", "-"].includes(input.value))) deny();
+  if (mode === "sign" && inputs.some((input) => [":-", "-"].includes(input.value))) deny();
+  return { mode, targets, entitlements: mode === "sign" ? inputs.map((input) => input.path) : [] };
+}

package/codesign-environment.mjs

@@ -0,0 +1,34 @@
+import * as fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { fileURLToPath } from "node:url";
+import { detectMacSigningSession } from "./macos-signing-session.mjs";
+import { ensurePrivateDirectory, privatePath } from "./rightkit-signing-agent.mjs";
+import { resolveManagedRoot } from "./artifact-storage.mjs";
+
+const quote = (text) => `'${String(text).replaceAll("'", "'\\''")}'`;
+export function codesignShimScript({ route, node = process.execPath,
+  entrypoint = fileURLToPath(new URL("./codesign-shim.mjs", import.meta.url)), realCodesign = "/usr/bin/codesign" }) {
+  return `#!/bin/sh\nif [ -n "\${SSH_CONNECTION-}\${SSH_TTY-}\${SSH_CLIENT-}" ] || [ ${quote(route)} = agent ]; then
+  exec ${quote(node)} ${quote(entrypoint)} "$@"
+fi
+exec ${quote(realCodesign)} "$@"\n`;
+}
+
+export function macosCodesignEnvironment(env = process.env, { platform = process.platform, io = fs,
+  detect = detectMacSigningSession, node = process.execPath } = {}) {
+  if (platform !== "darwin") return env;
+  const route = detect({ env }).guiRunner ? "agent" : "direct";
+  const script = codesignShimScript({ route, node });
+  // Immutable wrappers avoid races between GUI & SSH builds or package versions.
+  const identity = createHash("sha256").update(script).digest("hex").slice(0, 24);
+  const bin = path.join(resolveManagedRoot({ env }), "signing", "codesign-bin", identity);
+  ensurePrivateDirectory(bin, { io });
+  const file = path.join(bin, "codesign");
+  if (io.existsSync(file)) {
+    privatePath(file, 0o700, { io });
+    if (io.readFileSync(file, "utf8") !== script) throw new Error("Managed codesign shim content changed");
+  } else io.writeFileSync(file, script, { mode: 0o700, flag: "wx" });
+  // Keep every other shim (especially managed Cargo) in its original order.
+  return { ...env, PATH: [bin, ...(env.PATH ?? "").split(path.delimiter).filter((entry) => entry !== bin)].join(path.delimiter) };
+}

package/codesign-shim.mjs

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+import * as fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "./background-process.mjs";
+import { parseCodesignArgv } from "./codesign-argv.mjs";
+import { detectMacSigningSession } from "./macos-signing-session.mjs";
+import { requestSigningAgent } from "./signing-agent-client.mjs";
+import { defaultSigningRoots, privatePath, signingAgentPaths, SigningAgentError } from "./rightkit-signing-agent.mjs";
+
+export async function runCodesignShim(argv, { cwd = process.cwd(), env = process.env, home = os.userInfo().homedir,
+  io = fs, run = spawnSync, detect = detectMacSigningSession, request = requestSigningAgent } = {}) {
+  if (!detect({ env, run }).guiRunner) {
+    // Installed shell shim uses exec here; this branch also supports API callers.
+    const result = run("/usr/bin/codesign", argv, { cwd, env, stdio: "inherit", shell: false, windowsHide: true });
+    if (result.error) throw result.error;
+    return { status: result.status ?? 1, stdout: "", stderr: "" };
+  }
+  const paths = signingAgentPaths(home);
+  let roots = defaultSigningRoots(home, env.RIGHTKIT_MANAGED_ROOT);
+  if (io.existsSync(paths.config)) {
+    privatePath(paths.config, 0o600, { io });
+    roots = JSON.parse(io.readFileSync(paths.config, "utf8")).roots;
+  }
+  const { targets } = parseCodesignArgv(argv, cwd);
+  const report = await request({ schema: 1, type: "codesign-argv", argv, cwd, targets,
+    allowedRoots: roots.filter((root) => io.existsSync(root)), timeoutMs: 180000 }, { paths });
+  const result = report.results?.[0];
+  if (report.schema !== 1 || report.ok !== true || report.results?.length !== 1
+    || !Number.isInteger(result?.status) || result.status < 0 || result.status > 255
+    || typeof result.stdout !== "string" || typeof result.stderr !== "string") {
+    throw new SigningAgentError("MAC_SIGNING_AGENT_PROTOCOL", "Invalid codesign result");
+  }
+  return result;
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try {
+    // Only the managed shell wrapper invokes this entry: session detection was
+    // already performed by right-release before selecting its wrapper directory.
+    const result = await runCodesignShim(process.argv.slice(2), { detect: () => ({ guiRunner: true }) });
+    process.stdout.write(result.stdout);
+    process.stderr.write(result.stderr);
+    process.exitCode = result.status;
+  } catch (error) {
+    process.stderr.write(`rightkit codesign: [${error.code ?? "MAC_SIGNING_AGENT_JOB_FAILED"}] ${error.message}\n`);
+    process.exitCode = 1;
+  }
+}

package/development.mjs

@@ -9,6 +9,7 @@ import { acquireManagedRunLease, managedRuntimeClient, runCargoSync } from "./ma
 import { BUNDLE_MARKERS, bundleMarkerBuffer, readTauriBundleMarkers } from "./tauri-bundle-marker.mjs";
 import { installPortableDevelopment } from "./portable-development.mjs";
 import { signMacosDevelopmentBundle } from "./development-signing.mjs";
+import { macosCodesignEnvironment } from "./codesign-environment.mjs";
 
 export const DEVELOPMENT_PROFILE = "release-iterate";
 const RELEASE_ONLY_APPLE_ENV = ["APPLE_ID", "APPLE_PASSWORD", "APPLE_API_KEY", "APPLE_API_ISSUER", "APPLE_API_KEY_PATH", "APPLE_CERTIFICATE", "APPLE_CERTIFICATE_PASSWORD"];
@@ -60,7 +61,8 @@ export function validateDevelopmentConfig(config, platform) {
   return target;
 }
 
-export function runDevelopment({ root, platform, config, buildOnly = false, dryRun = false, env = process.env, run = spawnSync }) {
+export function runDevelopment({ root, platform, config, buildOnly = false, dryRun = false, env = process.env, run = spawnSync,
+  codesignEnvironment = macosCodesignEnvironment }) {
   if (!new Set(["win", "mac"]).has(platform)) throw new Error("--platform must be win or mac");
   assertNativeDevelopmentHost(platform);
   const target = validateDevelopmentConfig(config, platform);
@@ -68,7 +70,7 @@ export function runDevelopment({ root, platform, config, buildOnly = false, dryR
   assertPrimaryReleaseCheckout(repoRoot, env);
   if (dryRun) return { built: false, installed: false, plan: { build: target.build, install: buildOnly ? null : target.install ?? null, profile: DEVELOPMENT_PROFILE } };
   assertReleaseExecutionAllowed({ cwd: repoRoot, environment: env, command: `right-release dev --platform ${platform}` });
-  const childEnv = developmentEnvironment(env);
+  const childEnv = codesignEnvironment(developmentEnvironment(env));
   // One lease spans every managed request this run makes, so a broker cutover cannot land between them.
   const lease = acquireManagedRunLease({ command: `right-release dev --platform ${platform}`, env });
   try {

package/installer-storage-doctor.mjs

@@ -72,13 +72,21 @@ function destinationFor(line) {
 }
 
 /** Find repository subdirectories above storage threshold outside managed root. */
-export function findLargeRepositorySubdirectories({ appRoot, managedRoot = resolveManagedRoot(), thresholdBytes = DEFAULT_STORAGE_THRESHOLD_BYTES, ignored = gitIgnored } = {}) {
+export function findLargeRepositorySubdirectories({ appRoot, managedRoot = resolveManagedRoot(), thresholdBytes = DEFAULT_STORAGE_THRESHOLD_BYTES, ignored = gitIgnored, declared = [] } = {}) {
   if (!Number.isFinite(thresholdBytes) || thresholdBytes < 1) throw new TypeError("thresholdBytes must be positive");
   const root = path.resolve(appRoot);
   const ignoredRoot = managedRoot ? path.resolve(managedRoot) : null;
   const findings = [];
   const inside = (candidate, parent) => candidate === parent || candidate.startsWith(`${parent}${path.sep}`);
   const managedIgnored = ignoredRoot && inside(ignoredRoot, root) ? Boolean(ignored(ignoredRoot, root)) : false;
+  // App-declared durable stores (model stores, test fixture roots) are intentional and exempt.
+  // Each needs a reason: config `storage.declaredStores: [{ path, reason }]`, paths relative to the app root.
+  const declaredRoots = (declared ?? []).map((item) => {
+    if (!item?.path || !String(item.reason ?? "").trim()) throw new TypeError("storage.declaredStores entries need path and reason");
+    const resolved = path.resolve(root, item.path);
+    if (!inside(resolved, root) || resolved === root) throw new TypeError(`storage.declaredStores path must be inside the app root: ${item.path}`);
+    return resolved;
+  });
   const walk = (directory) => {
     let total = 0;
     let entries;
@@ -91,6 +99,7 @@ export function findLargeRepositorySubdirectories({ appRoot, managedRoot = resol
       if (stat.isSymbolicLink()) continue;
       if (stat.isDirectory()) {
         if (managedIgnored && inside(file, ignoredRoot)) continue;
+        if (declaredRoots.some((declaredRoot) => inside(file, declaredRoot))) continue;
         total += walk(file);
       } else if (stat.isFile()) total += stat.size;
     }

package/macos-notarization.mjs

@@ -1,8 +1,10 @@
 import { createHash } from "node:crypto";
-import { mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { mkdirSync, readFileSync, realpathSync, statSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { spawnSync } from "./background-process.mjs";
 import { MACOS_PORTABLE_SIGNING_CONTRACT } from "./macos-signing-contract.mjs";
+import { detectMacSigningSession, runMacGuiNotarization } from "./macos-signing-session.mjs";
+import { notarytoolAuthArgs } from "./notary-auth.mjs";
 
 function checkedRun(args, run) {
   const result = run("xcrun", args, { encoding: "utf8" });
@@ -10,9 +12,13 @@ function checkedRun(args, run) {
   return result.stdout ?? "";
 }
 
-export function stapleMacosArtifact(file, { run = spawnSync } = {}) {
+export function stapleMacosArtifact(file, options = {}) {
+  const { run = spawnSync, env = process.env } = options;
   file = path.resolve(file);
   if (!/\.(dmg|pkg|app)$/i.test(file)) throw new Error(`not a stapleable macOS artifact: ${file}`);
+  if (detectMacSigningSession({ env, run }).guiRunner) {
+    return { ...runMacGuiNotarization({ ...options, kind: "staple", file }).stapling[0], file };
+  }
   const probe = run("xcrun", ["stapler", "validate", file], { encoding: "utf8" });
   if (probe.error) throw new Error(`cannot validate macOS staple: ${probe.error.message}`);
   const alreadyStapled = probe.status === 0;
@@ -27,7 +33,7 @@ function fileEvidence(file) {
 
 // DMG/PKG receive their own ticket. For a separately submitted app ZIP,
 // target.notarize.app (CLI --app) identifies the bundle to staple before packaging.
-export function notarizeMacosArtifact({ archive, receiptPath, authArgs, app, run = spawnSync }) {
+export function notarizeMacosArtifact({ archive, receiptPath, authArgs, profile, app, run = spawnSync, env = process.env, ...agentOptions }) {
   archive = path.resolve(archive);
   const stapleTargets = /\.(dmg|pkg)$/i.test(archive) ? [archive] : [];
   if (app) {
@@ -36,11 +42,21 @@ export function notarizeMacosArtifact({ archive, receiptPath, authArgs, app, run
     stapleTargets.push(bundle);
   }
   if (!stapleTargets.length) throw new Error("notarization archives require notarize.app (or --app) for stapling their app bundle");
-  let result;
-  try { result = JSON.parse(checkedRun(["notarytool", "submit", archive, "--wait", "--output-format", "json", ...authArgs], run)); }
-  catch (error) { throw new Error(`macOS notarization failed for ${archive}: ${error.message}`); }
-  if (result.status !== "Accepted") throw new Error(`notarization was not accepted for ${archive}: ${result.status ?? "missing status"}`);
-  const stapling = [...new Set(stapleTargets)].map((file) => stapleMacosArtifact(file, { run }));
+  let result, stapling;
+  if (detectMacSigningSession({ env, run }).guiRunner) {
+    // SSH ignores API credential environment/argv entirely. Only profile name
+    // reaches Aqua, where Keychain authentication already works.
+    const selectedProfile = profile ?? (authArgs?.[0] === "--keychain-profile" && authArgs.length === 2 ? authArgs[1] : undefined);
+    const report = runMacGuiNotarization({ ...agentOptions, kind: "notarize", file: archive, app, profile: selectedProfile, env, run });
+    result = report.notarization;
+    stapling = report.stapling.map((item) => ({ ...item, file: stapleTargets.find((file) => realpathSync.native(file) === item.file) ?? item.file }));
+  } else {
+    authArgs ??= notarytoolAuthArgs({ profile, env });
+    try { result = JSON.parse(checkedRun(["notarytool", "submit", archive, "--wait", "--output-format", "json", ...authArgs], run)); }
+    catch (error) { throw new Error(`macOS notarization failed for ${archive}: ${error.message}`); }
+    if (result.status !== "Accepted") throw new Error(`notarization was not accepted for ${archive}: ${result.status ?? "missing status"}`);
+    stapling = [...new Set(stapleTargets)].map((file) => stapleMacosArtifact(file, { run, env }));
+  }
   // Stapling changes container bytes. Record final bytes, never the submission digest.
   const receipt = {
     schema: 1,

package/macos-signing-session.mjs

@@ -3,9 +3,9 @@ import os from "node:os";
 import path from "node:path";
 import { spawnSync } from "./background-process.mjs";
 
-import { requestSigningAgentSync } from "./signing-agent-client.mjs";
+import { requestSigningAgentSync, validateNotaryAgentReport } from "./signing-agent-client.mjs";
 import { installSigningAgent, requireMacGuiSession } from "./signing-agent-install.mjs";
-import { signingAgentPaths, defaultSigningRoots, ensurePrivateDirectory, privatePath, within } from "./rightkit-signing-agent.mjs";
+import { signingAgentPaths, defaultSigningRoots, ensurePrivateDirectory, privatePath, within, NOTARIZATION_TIMEOUT_MS, MAX_NOTARIZATION_TIMEOUT_MS } from "./rightkit-signing-agent.mjs";
 
 export class MacSigningSessionError extends Error {
   constructor(code, message) {
@@ -126,6 +126,51 @@ export function runMacCodesignCommands(commands, options = {}) {
   return results;
 }
 
+export function runMacGuiNotarization({ kind = "notarize", file, profile = "apple-dev-notary", app, validateOnly,
+  cwd = process.cwd(), env = process.env, run = spawnSync, io = fs, home = os.userInfo().homedir,
+  uid = process.getuid?.(), username = os.userInfo().username, allowedRoots, timeoutMs = NOTARIZATION_TIMEOUT_MS,
+  request = requestSigningAgentSync, install = installSigningAgent } = {}) {
+  if (!["notarize", "staple"].includes(kind) || !Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > MAX_NOTARIZATION_TIMEOUT_MS) throw new TypeError("Invalid notarization request or timeout");
+  if (kind === "notarize" && (typeof profile !== "string" || !/^[A-Za-z0-9][A-Za-z0-9_. -]{0,127}$/.test(profile))) throw new TypeError("Notarization requires a profile name only");
+  requireMacGuiSession({ run, uid });
+  const paths = signingAgentPaths(home);
+  let roots = allowedRoots ?? defaultSigningRoots(home, env.RIGHTKIT_MANAGED_ROOT);
+  if (!allowedRoots && io.existsSync(paths.config)) {
+    privatePath(paths.config, 0o600, { io, uid });
+    roots = JSON.parse(io.readFileSync(paths.config, "utf8")).roots;
+  }
+  const plan = { schema: 1, type: kind, path: path.resolve(file), cwd: path.resolve(cwd),
+    allowedRoots: roots.filter((root) => io.existsSync(root)), timeoutMs,
+    ...(kind === "notarize" ? { profile, staple: true, ...(app ? { app: path.resolve(app) } : {}) } : { validateOnly: validateOnly === true }) };
+  const options = { home, timeoutMs: timeoutMs + 5000 };
+  let report;
+  try { report = request(plan, options); }
+  catch (error) {
+    let missing = error.code === "MAC_SIGNING_AGENT_UNAVAILABLE";
+    // Upgrade earlier installed agents once; never turn a rejected path or
+    // malformed request into an install/retry loop.
+    if (error.code === "MAC_SIGNING_AGENT_PROTOCOL") {
+      const health = request({ schema: 1, type: "health" }, { home, timeoutMs: 1500 });
+      missing = !health.capabilities?.includes(kind);
+    }
+    if (!missing) throw error;
+    install({ home, username, uid, run, io, managedRoot: env.RIGHTKIT_MANAGED_ROOT });
+    report = request(plan, options);
+  }
+  validateNotaryAgentReport(report);
+  const targets = kind === "staple" ? [plan.path] : [...new Set([...( /\.(dmg|pkg)$/i.test(plan.path) ? [plan.path] : []), ...(plan.app ? [plan.app] : [])])];
+  const canonical = (value) => (io.realpathSync.native ?? io.realpathSync)(value);
+  if (!report.ok || (kind === "notarize" && (report.notarization.status !== "Accepted" || !report.notarization.id
+    || !report.steps.some((step) => step.step === "submit" && step.exitCode === 0)))
+    || report.stapling.length !== targets.length || targets.some((target) => !report.stapling.some((item) => item.file === canonical(target)
+      && report.steps.some((step) => step.step === "validate" && step.file === item.file && step.exitCode === 0)
+      && (kind !== "notarize" || report.steps.some((step) => step.step === "staple" && step.file === item.file && step.exitCode === 0))))
+    || report.steps.some((step) => step.step !== "probe" && step.exitCode !== 0)) {
+    throw new MacSigningSessionError("MAC_SIGNING_AGENT_PROTOCOL", "Signing agent returned incomplete notarization or stapling evidence");
+  }
+  return report;
+}
+
 export function signMacUpdaterFiles(files, options = {}) {
   const { cwd = process.cwd(), env = process.env, run = spawnSync, username = os.userInfo().username } = options;
   const commands = files.map((file) => ["exec", "tauri", "signer", "sign", file]);

package/notarize-macos.mjs

@@ -1,7 +1,6 @@
 #!/usr/bin/env node
 import { existsSync } from "node:fs";
 import path from "node:path";
-import { notarytoolAuthArgs } from "./notary-auth.mjs";
 import { notarizeMacosArtifact } from "./macos-notarization.mjs";
 
 const args = process.argv.slice(2);
@@ -24,10 +23,11 @@ if (dryRun) {
 if (process.platform !== "darwin") fail("macOS notarization must run on macOS");
 if (!existsSync(archive)) fail(`missing archive: ${archive}`);
 
-let authArgs;
-try { authArgs = notarytoolAuthArgs({ profile }); } catch (error) { fail(error.message); }
-try { notarizeMacosArtifact({ archive, receiptPath, authArgs, app }); }
-catch (error) { fail(error.message); }
+try { notarizeMacosArtifact({ archive, receiptPath, profile, app }); }
+catch (error) {
+  if (error.report) console.error(JSON.stringify(error.report));
+  fail(`${error.code ? `[${error.code}] ` : ""}${error.message}`);
+}
 
 function fail(message) {
   console.error(`right-notarize-macos: ${message}`);

package/ownership-helper-paths.json

@@ -5,7 +5,7 @@
     "sha256": "8d12e39ee6bac3bf8332df8dc61c74637e2eda6becbcc39746fe1ed5a1fe7ef6"
   },
   "macos": {
-    "path": "/Users/adrdsouza/.rightkit-managed/ownership-approval/macos/content-54224936edb74c9044dbaaa38a0773ee77acec21826237572b9b7c67a87b8ccc/ownership-approval",
-    "sha256": "54224936edb74c9044dbaaa38a0773ee77acec21826237572b9b7c67a87b8ccc"
+    "path": "/Users/adrdsouza/.rightkit-managed/ownership-approval/macos/content-2c30864bdb666a1ca1e4388ea7a3bc83cb985196d666b96cc30e1da7cd5b0e6b/RightKitOwnershipApproval.app/Contents/MacOS/ownership-approval",
+    "sha256": "2c30864bdb666a1ca1e4388ea7a3bc83cb985196d666b96cc30e1da7cd5b0e6b"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rightkit/release",
-  "version": "0.2.133",
+  "version": "0.2.135",
   "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/release.mjs

@@ -28,6 +28,7 @@ import { MACOS_PORTABLE_SIGNING_CONTRACT } from "./macos-signing-contract.mjs";
 import { runConfiguredChecks } from "./release-checks.mjs";
 import { resolveMacosDeveloperIdIdentity } from "./macos-signing-identity.mjs";
 import { DEFAULT_STORAGE_THRESHOLD_BYTES, findInstallerCopyScripts, findLargeRepositorySubdirectories } from "./installer-storage-doctor.mjs";
+import { macosCodesignEnvironment } from "./codesign-environment.mjs";
 
 const TOOL_ROOT = path.dirname(fileURLToPath(import.meta.url));
 const HARDENING_SCAN = path.resolve(TOOL_ROOT, "hardeningscan.mjs");
@@ -210,7 +211,7 @@ if (opts.doctor) {
   });
   const storageFindings = [
     ...installerCopyFindings,
-    ...findLargeRepositorySubdirectories({ appRoot: root, managedRoot, thresholdBytes: Number(process.env.RIGHTKIT_ARTIFACT_STORAGE_THRESHOLD_BYTES ?? DEFAULT_STORAGE_THRESHOLD_BYTES) }),
+    ...findLargeRepositorySubdirectories({ appRoot: root, managedRoot, declared: config.storage?.declaredStores ?? [], thresholdBytes: Number(process.env.RIGHTKIT_ARTIFACT_STORAGE_THRESHOLD_BYTES ?? DEFAULT_STORAGE_THRESHOLD_BYTES) }),
   ];
   if (storageFindings.length) {
     console.log("artifact-storage: report-only storage findings detected:");
@@ -281,8 +282,9 @@ if (opts.platform === "win") {
     });
   }
 } else if (opts.platform === "mac") {
-  const signingFiles = target.sign.prePackageFiles.map((p) => path.resolve(root, p));
   if (runMacPhase("prepackage")) await runCommand(target.prePackage, root);
+  // Resolve after prePackage: with storage governance the artifact may live only in RIGHT_RELEASE_ARTIFACT_DIR.
+  const signingFiles = target.sign.prePackageFiles.map((p) => resolveReleaseArtifactPath(root, p));
   for (const file of signingFiles) await mustExist(file, `missing macOS Developer ID signing artifact: ${file}`);
   if (runMacPhase("sign")) await signMacos(signingFiles, root);
 } else if (nativeAssembly) {
@@ -961,7 +963,7 @@ function run(cmd, runArgs, cwd, env = {}, options = {}) {
     const useShell = process.platform === "win32" && !/\.(?:exe|com)$/i.test(cmd);
     const child = spawn(cmd, runArgs, {
       cwd,
-      env: { ...process.env, ...releaseEnv, ...env },
+      env: macosCodesignEnvironment({ ...process.env, ...releaseEnv, ...env }),
       stdio: options.captureStdout ? ["inherit", "pipe", "inherit"] : "inherit",
       shell: useShell,
       windowsHide: true,

package/rightkit-signing-agent.mjs

@@ -5,10 +5,13 @@ import os from "node:os";
 import path from "node:path";
 import { randomBytes, timingSafeEqual, randomUUID } from "node:crypto";
 import { fileURLToPath } from "node:url";
-import { spawnSync } from "./background-process.mjs";
+import { spawn, spawnSync } from "./background-process.mjs";
+import { parseCodesignArgv } from "./codesign-argv.mjs";
 
 export const AGENT_LABEL = "dev.rightkit.signing-agent";
 export const MAX_FRAME = 1024 * 1024;
+export const NOTARIZATION_TIMEOUT_MS = 1800000;
+export const MAX_NOTARIZATION_TIMEOUT_MS = 7200000;
 export class SigningAgentError extends Error {
   constructor(code, message) { super(message); this.name = "SigningAgentError"; this.code = code; }
 }
@@ -19,8 +22,9 @@ export function signingAgentPaths(home = os.userInfo().homedir) {
     config: path.join(directory, "config.json"), runtime: path.join(directory, "runtime"),
     log: path.join(directory, "requests.jsonl"), plist: path.join(home, "Library/LaunchAgents", `${AGENT_LABEL}.plist`) };
 }
-export function defaultSigningRoots(home = os.userInfo().homedir, managedRoot = "/Volumes/D/.rightkit-managed") {
-  return ["/Volumes/D/claude", managedRoot, "/Volumes/D/rightkit-build-control", path.join(home, "Library/Caches/RightSuite/release")];
+export function defaultSigningRoots(home = os.userInfo().homedir, managedRoot = "/Volumes/D/.rightkit-managed", cargoTargetDirs = []) {
+  return [...new Set(["/Volumes/D/claude", managedRoot, "/Volumes/D/rightkit-build-control",
+    path.join(home, "Library/Caches/RightSuite/release"), "/tmp", "/private/tmp", os.tmpdir(), ...cargoTargetDirs])];
 }
 export const within = (root, file) => file === root || file.startsWith(`${root}${path.sep}`);
 export function privatePath(file, mode, { io = fs, uid = process.getuid?.(), kind = "file" } = {}) {
@@ -55,15 +59,19 @@ function absolute(value) {
   return path.resolve(value);
 }
 export function validateSigningRequest(request, { roots, stagingRoot, io = fs } = {}) {
+  // Node's JS realpath normalizes .. before following links. Native realpath
+  // follows the same path traversal as codesign & catches link/.. escapes.
+  const realpath = io.realpathSync.native ?? io.realpathSync;
   const common = ["schema", "token", "type", "allowedRoots", "cwd", "timeoutMs"];
   if (request?.type === "health") {
     shape(request, ["schema", "token", "type"]);
     if (request.schema !== 1) fail("MAC_SIGNING_AGENT_PROTOCOL", "Unsupported protocol schema");
     return request;
   }
-  if (!["codesign", "updater"].includes(request?.type)) fail("MAC_SIGNING_AGENT_PROTOCOL", "Unsupported signing request type");
-  shape(request, [...common, request.type === "codesign" ? "items" : "files"]);
-  if (request.schema !== 1 || !Number.isInteger(request.timeoutMs) || request.timeoutMs < 1 || request.timeoutMs > 180000) {
+  const notary = ["notarize", "staple"].includes(request?.type);
+  if (!["codesign", "codesign-argv", "updater", "notarize", "staple"].includes(request?.type)) fail("MAC_SIGNING_AGENT_PROTOCOL", "Unsupported signing request type");
+  shape(request, [...common, ...(notary ? ["path", "profile", "staple", "app", "validateOnly"] : request.type === "codesign-argv" ? ["argv", "targets"] : [request.type === "codesign" ? "items" : "files"])]);
+  if (request.schema !== 1 || !Number.isInteger(request.timeoutMs) || request.timeoutMs < 1 || request.timeoutMs > (notary ? MAX_NOTARIZATION_TIMEOUT_MS : 180000)) {
     fail("MAC_SIGNING_AGENT_PROTOCOL", "Invalid schema or signing deadline");
   }
   if (!Array.isArray(request.allowedRoots) || !request.allowedRoots.length || request.allowedRoots.length > 32) fail("MAC_SIGNING_AGENT_PATH_DENIED", "Allowed roots required");
@@ -73,15 +81,16 @@ export function validateSigningRequest(request, { roots, stagingRoot, io = fs }
   const allowed = request.allowedRoots.map((root) => {
     const lexical = absolute(root);
     if (![...installed, stagingRoot].filter(Boolean).some((base) => within(base, lexical))) fail("MAC_SIGNING_AGENT_PATH_DENIED", "Caller root is outside installed signing policy");
-    const canonical = io.realpathSync(lexical);
+    const canonical = realpath(root);
     if (![...installed, stagingRoot].filter(Boolean).some((base) => {
-      try { return within(io.realpathSync(base), canonical); } catch { return false; }
+      try { return within(realpath(base), canonical); } catch { return false; }
     })) fail("MAC_SIGNING_AGENT_PATH_DENIED", "Allowed root escapes installed policy");
     return { lexical, canonical };
   });
   function checked(file, { directory = false, entitlements = false } = {}) {
     const lexical = absolute(file);
-    const canonical = io.realpathSync(lexical);
+    let canonical;
+    try { canonical = realpath(file); } catch { fail("MAC_SIGNING_AGENT_PATH_DENIED", "Signing path is unavailable"); }
     if (!allowed.some((root) => within(root.lexical, lexical) && within(root.canonical, canonical))
       || (!entitlements && stagingRoot && within(stagingRoot, canonical))) fail("MAC_SIGNING_AGENT_PATH_DENIED", "Signing path escapes allowed roots");
     const info = io.statSync(canonical);
@@ -89,6 +98,33 @@ export function validateSigningRequest(request, { roots, stagingRoot, io = fs }
     return canonical;
   }
   const cwd = checked(request.cwd, { directory: true });
+  if (notary) {
+    const file = checked(request.path);
+    if (request.type === "staple") {
+      if (request.profile !== undefined || request.app !== undefined || request.staple !== undefined
+        || (request.validateOnly !== undefined && typeof request.validateOnly !== "boolean")) fail("MAC_SIGNING_AGENT_PROTOCOL", "Invalid stapling options");
+      if (!/\.(dmg|pkg|app)$/i.test(file) || (/\.app$/i.test(file) ? !io.statSync(file).isDirectory() : !io.statSync(file).isFile())) fail("MAC_SIGNING_AGENT_PATH_DENIED", "Invalid staple target");
+      return { ...request, cwd, path: file };
+    }
+    const profile = request.profile ?? "apple-dev-notary";
+    if (typeof profile !== "string" || !/^[A-Za-z0-9][A-Za-z0-9_. -]{0,127}$/.test(profile)
+      || request.staple !== true || request.validateOnly !== undefined) fail("MAC_SIGNING_AGENT_PROTOCOL", "Notarization requires a profile name & staple: true");
+    if (!/\.(dmg|zip|pkg)$/i.test(file) || !io.statSync(file).isFile()) fail("MAC_SIGNING_AGENT_PATH_DENIED", "Notarization requires DMG, ZIP, or PKG");
+    const app = request.app === undefined ? undefined : checked(request.app, { directory: true });
+    if (app && !/\.app$/i.test(app)) fail("MAC_SIGNING_AGENT_PATH_DENIED", "Stapling app must be an app bundle");
+    if (/\.zip$/i.test(file) && !app) fail("MAC_SIGNING_AGENT_PROTOCOL", "ZIP submission requires app bundle for stapling");
+    return { ...request, cwd, path: file, profile, ...(app ? { app } : {}) };
+  }
+  if (request.type === "codesign-argv") {
+    const parsed = parseCodesignArgv(request.argv, request.cwd);
+    if (!Array.isArray(request.targets) || request.targets.length !== parsed.targets.length
+      || request.targets.some((target, index) => target !== parsed.targets[index])) fail("MAC_SIGNING_AGENT_PROTOCOL", "Codesign target paths do not match argv");
+    for (const target of parsed.targets) checked(target);
+    for (const file of parsed.entitlements) checked(file, { entitlements: true });
+    // Preserve argv & cwd spelling: relative arguments must resolve exactly as
+    // they would for the original caller, including symlink/.. semantics.
+    return { ...request };
+  }
   if (request.type === "updater") {
     if (!Array.isArray(request.files) || !request.files.length || request.files.length > 4096) fail("MAC_SIGNING_AGENT_PROTOCOL", "Updater files required");
     const files = request.files.map((file) => {
@@ -119,9 +155,17 @@ export function authenticateSigningToken(candidate, token) {
 }
 export function executeSigningRequest(request, { run = spawnSync, home = os.userInfo().homedir,
   username = os.userInfo().username, pnpm, environmentPath, now = Date.now } = {}) {
-  if (request.type === "health") return { schema: 1, ok: true, service: AGENT_LABEL, pid: process.pid };
+  if (request.type === "health") return { schema: 1, ok: true, service: AGENT_LABEL, pid: process.pid, capabilities: ["codesign", "codesign-argv", "updater", "notarize", "staple"] };
   const deadline = now() + request.timeoutMs;
   const env = { HOME: home, PATH: environmentPath, TMPDIR: path.join(signingAgentPaths(home).directory, "tmp") };
+  if (request.type === "codesign-argv") {
+    const r = run("/usr/bin/codesign", request.argv, { cwd: request.cwd, env, encoding: "utf8", stdio: "pipe", shell: false,
+      windowsHide: true, timeout: request.timeoutMs, killSignal: "SIGKILL", maxBuffer: MAX_FRAME });
+    if (r.error || !Number.isInteger(r.status)) fail(r.error?.code === "ETIMEDOUT" ? "MAC_SIGNING_AGENT_TIMEOUT" : "MAC_SIGNING_AGENT_JOB_FAILED", "Codesign execution failed");
+    const report = { schema: 1, ok: true, results: [{ status: r.status, stdout: String(r.stdout ?? ""), stderr: String(r.stderr ?? "") }] };
+    if (Buffer.byteLength(`${JSON.stringify(report)}\n`) > MAX_FRAME) fail("MAC_SIGNING_AGENT_PROTOCOL", "Codesign output exceeds protocol limit");
+    return report;
+  }
   const results = [];
   const outputLimit = Math.min(4096, Math.floor(MAX_FRAME / (4 * (request.items?.length ?? request.files.length))));
   const invoke = (command, args, sensitive = false) => {
@@ -158,6 +202,92 @@ export function executeSigningRequest(request, { run = spawnSync, home = os.user
     throw error;
   } finally { delete env.TAURI_SIGNING_PRIVATE_KEY; delete env.TAURI_SIGNING_PRIVATE_KEY_PASSWORD; }
 }
+// No notarytool/stapler output is forwarded verbatim: diagnostics can contain
+// account details. Only typed status, submission UUID, counts & issue codes leave Aqua.
+export async function executeNotarizationRequest(request, { launch = spawn, home = os.userInfo().homedir,
+  environmentPath = "/usr/bin:/bin", now = Date.now, id = randomUUID(), progress = () => {}, signal } = {}) {
+  const deadline = now() + request.timeoutMs;
+  const env = { HOME: home, PATH: environmentPath, TMPDIR: path.join(signingAgentPaths(home).directory, "tmp") };
+  const report = { schema: 1, ok: false, id, notarization: { id: null, status: "Unknown", logSummary: null }, steps: [], stapling: [] };
+  const invoke = async (step, args, file) => {
+    progress({ schema: 1, event: "status", id, step });
+    const remaining = deadline - now();
+    if (remaining <= 0 || signal?.aborted) throw new SigningAgentError("MAC_SIGNING_AGENT_TIMEOUT", "Notarization deadline expired");
+    const result = await new Promise((resolve) => {
+      let child, output = "", bytes = 0, timedOut = false, overflow = false, failed = false;
+      let timer;
+      const kill = () => { try { child?.kill("SIGKILL"); } catch {} };
+      const cancel = () => { timedOut = true; kill(); };
+      const finish = (exitCode) => {
+        clearTimeout(timer); signal?.removeEventListener("abort", cancel);
+        resolve({ exitCode: Number.isInteger(exitCode) ? exitCode : null, output, timedOut, overflow, failed });
+      };
+      try {
+        child = launch("/usr/bin/xcrun", args, { cwd: request.cwd, env, stdio: ["ignore", "pipe", "pipe"], shell: false });
+        timer = setTimeout(cancel, remaining);
+        signal?.addEventListener("abort", cancel, { once: true });
+        child.stdout.on("data", (chunk) => {
+          bytes += chunk.length;
+          if (bytes > MAX_FRAME) { overflow = true; kill(); } else output += chunk.toString();
+        });
+        child.stderr.on("data", () => {}); // Drain, never disclose.
+        child.once("error", () => { failed = true; finish(null); });
+        child.once("close", finish);
+      } catch { failed = true; finish(null); }
+    });
+    report.steps.push({ step, ...(file ? { file } : {}), exitCode: result.exitCode });
+    if (result.timedOut) throw new SigningAgentError("MAC_SIGNING_AGENT_TIMEOUT", "Notarization deadline expired");
+    if (result.failed || result.overflow) throw new SigningAgentError("MAC_SIGNING_AGENT_JOB_FAILED", `${step} execution failed`);
+    return result;
+  };
+  const parse = (output) => { try { return JSON.parse(output); } catch { return {}; } };
+  try {
+    if (request.type === "notarize") {
+      const submitted = await invoke("submit", ["notarytool", "submit", request.path, "--keychain-profile", request.profile ?? "apple-dev-notary", "--wait", "--output-format", "json"]);
+      const result = parse(submitted.output);
+      const submissionId = result.id ?? result.submissionId;
+      report.notarization.id = typeof submissionId === "string" && /^[a-f0-9-]{36}$/i.test(submissionId) ? submissionId : null;
+      report.notarization.status = ["Accepted", "Invalid", "In Progress", "Rejected"].includes(result.status) ? result.status : "Unknown";
+      if (report.notarization.status === "Invalid" && report.notarization.id) {
+        const logged = await invoke("log", ["notarytool", "log", report.notarization.id, "--keychain-profile", request.profile ?? "apple-dev-notary", "--output-format", "json"]);
+        if (logged.exitCode === 0) {
+          const log = parse(logged.output);
+          const issues = Array.isArray(log.issues) ? log.issues : [];
+          report.notarization.logSummary = { statusCode: Number.isInteger(log.statusCode) ? log.statusCode : null,
+            errors: issues.filter((issue) => issue.severity === "error").length,
+            warnings: issues.filter((issue) => issue.severity === "warning").length,
+            issues: issues.slice(0, 100).map((issue) => ({ severity: ["error", "warning"].includes(issue.severity) ? issue.severity : "unknown",
+              code: Number.isInteger(issue.code) ? issue.code : null })) };
+        }
+      }
+      if (submitted.exitCode !== 0 || report.notarization.status !== "Accepted" || !report.notarization.id) {
+        throw new SigningAgentError("MAC_SIGNING_NOTARIZATION_FAILED", `Notarization ${report.notarization.status}`);
+      }
+    }
+    const targets = request.type === "staple" ? [request.path]
+      : [...new Set([...( /\.(dmg|pkg)$/i.test(request.path) ? [request.path] : []), ...(request.app ? [request.app] : [])])];
+    for (const file of targets) {
+      let alreadyStapled = false;
+      if (request.type === "staple" && !request.validateOnly) {
+        const probe = await invoke("probe", ["stapler", "validate", file], file);
+        alreadyStapled = probe.exitCode === 0;
+      }
+      if (!request.validateOnly && !alreadyStapled) {
+        const stapled = await invoke("staple", ["stapler", "staple", file], file);
+        if (stapled.exitCode !== 0) throw new SigningAgentError("MAC_SIGNING_STAPLE_FAILED", "Stapling failed");
+      }
+      const validated = await invoke("validate", ["stapler", "validate", file], file);
+      if (validated.exitCode !== 0) throw new SigningAgentError("MAC_SIGNING_STAPLE_FAILED", "Staple validation failed");
+      report.stapling.push({ file, alreadyStapled, validated: true });
+    }
+    report.ok = true;
+  } catch (error) {
+    report.code = error.code?.startsWith("MAC_SIGNING_") ? error.code : "MAC_SIGNING_AGENT_JOB_FAILED";
+    report.message = report.code === "MAC_SIGNING_AGENT_TIMEOUT" ? "Notarization deadline expired" : "Notarization or stapling failed inside signing agent";
+  }
+  return report;
+}
+
 export function managedSigningLog(file, event, { io = fs } = {}) {
   if (io.existsSync(file)) {
     privatePath(file, 0o600, { io });
@@ -170,7 +300,7 @@ export function managedSigningLog(file, event, { io = fs } = {}) {
   // Only service-authored metadata is logged, never request/token/key/argv/output.
   io.appendFileSync(file, `${JSON.stringify({ at: new Date().toISOString(), ...event })}\n`, { mode: 0o600 });
 }
-export async function startSigningAgent({ paths = signingAgentPaths(), config, io = fs, run = spawnSync,
+export async function startSigningAgent({ paths = signingAgentPaths(), config, io = fs, run = spawnSync, launch = spawn, heartbeatMs = 10000,
   log = (event) => managedSigningLog(paths.log, event), createServer = net.createServer } = {}) {
   privatePath(paths.directory, 0o700, { io, kind: "directory" });
   privatePath(paths.config, 0o600, { io });
@@ -211,9 +341,14 @@ export async function startSigningAgent({ paths = signingAgentPaths(), config, i
         return;
       }
       const receivedAt = Date.now();
+      const notary = ["notarize", "staple"].includes(request.type);
+      const controller = new AbortController();
+      const progress = (frame) => { if (!socket.destroyed) socket.write(`${JSON.stringify(frame)}\n`); };
+      const heartbeat = notary ? setInterval(() => progress({ schema: 1, event: "heartbeat", id }), heartbeatMs) : null;
+      if (notary) socket.on("close", () => { clearInterval(heartbeat); controller.abort(); });
       pending++;
-      log({ event: "request.accepted", id, type: request.type, count: request.items?.length ?? request.files?.length ?? 0 });
-      queue = queue.then(() => {
+      log({ event: "request.accepted", id, type: request.type, count: notary ? 1 : request.targets?.length ?? request.items?.length ?? request.files?.length ?? 0 });
+      queue = queue.then(async () => {
         if (socket.destroyed) { log({ event: "request.cancelled", id, type: request.type }); return; }
         log({ event: "request.started", id, type: request.type });
         try {
@@ -223,15 +358,20 @@ export async function startSigningAgent({ paths = signingAgentPaths(), config, i
             // Revalidate immediately before effects, not merely on admission.
             request = validateSigningRequest(request, { roots: config.roots, stagingRoot: path.join(paths.directory, "requests"), io });
           }
-          const report = executeSigningRequest(request, { run, home: config.home, username: config.username, pnpm: config.pnpm, environmentPath: config.environmentPath });
+          const report = notary
+            ? await executeNotarizationRequest(request, { launch, home: config.home, environmentPath: config.environmentPath, id, progress, signal: controller.signal })
+            : executeSigningRequest(request, { run, home: config.home, username: config.username, pnpm: config.pnpm, environmentPath: config.environmentPath });
           respond(report);
-          log({ event: "request.completed", id, type: request.type });
+          log({ event: report.ok ? "request.completed" : "request.failed", id, type: request.type,
+            ...(report.code ? { code: report.code } : {}),
+            ...(notary ? { status: report.notarization.status, steps: report.steps.map(({ step, exitCode }) => ({ step, exitCode })) } : {}),
+            ...(request.type === "codesign-argv" ? { status: report.results[0].status } : {}) });
         } catch (error) {
           const code = error.code?.startsWith("MAC_SIGNING_") ? error.code : "MAC_SIGNING_AGENT_JOB_FAILED";
-          respond({ schema: 1, ok: false, code, message: request.type === "updater" ? "Updater signing failed" : error.message });
+          respond({ schema: 1, ok: false, ...(notary ? { id } : {}), code, message: request.type === "updater" ? "Updater signing failed" : notary ? "Notarization job failed" : error.message });
           log({ event: "request.failed", id, type: request.type, code });
         }
-      }).finally(() => { pending--; }).catch(() => { socket.destroy(); });
+      }).finally(() => { clearInterval(heartbeat); pending--; }).catch(() => { socket.destroy(); });
     });
   });
   await new Promise((resolve, reject) => { server.once("error", reject); server.listen(paths.socket, resolve); });

package/rightkit-versions.json

@@ -27,9 +27,9 @@
     "@rightkit/onboarding": "0.2.3",
     "@rightkit/pdf-ui": "0.1.2",
     "@rightkit/platform-ui": "0.1.2",
-    "@rightkit/qa": "0.3.0",
+    "@rightkit/qa": "0.3.2",
     "@rightkit/qa-chrome": "0.1.3",
-    "@rightkit/release": "0.2.133",
+    "@rightkit/release": "0.2.135",
     "@rightkit/settings-ui": "0.2.7",
     "@rightkit/shell": "0.1.0",
     "@rightkit/tauri": "0.1.1",
@@ -156,7 +156,9 @@
       "0.2.129",
       "0.2.130",
       "0.2.131",
-      "0.2.132"
+      "0.2.132",
+      "0.2.133",
+      "0.2.134"
     ],
     "@rightkit/qa": [
       "0.1.0",
@@ -164,7 +166,9 @@
       "0.2.1",
       "0.2.2",
       "0.2.3",
-      "0.2.4"
+      "0.2.4",
+      "0.3.0",
+      "0.3.1"
     ],
     "@rightkit/app-shell": [
       "0.1.0",
@@ -238,7 +242,7 @@
     "rightkit-automation": "0.1.0",
     "rightkit-browser": "0.2.2",
     "rightkit-cache": "0.1.0",
-    "rightkit-control": "0.1.8",
+    "rightkit-control": "0.1.9",
     "rightkit-crash": "0.1.0",
     "rightkit-db": "0.3.0",
     "rightkit-embed": "0.2.2",
@@ -256,7 +260,7 @@
     "rightkit-pdf": "0.1.0",
     "rightkit-playback": "0.1.1",
     "rightkit-process": "0.3.1",
-    "rightkit-qa": "0.2.10",
+    "rightkit-qa": "0.2.12",
     "rightkit-qts": "0.2.1",
     "rightkit-qts-ggml": "0.1.0",
     "rightkit-qts-ggml-sys": "0.1.0",
@@ -288,7 +292,7 @@
       "rightkit-audio": "0.1.1",
       "rightkit-browser": "0.2.2",
       "rightkit-cache": "0.1.0",
-      "rightkit-control": "0.1.8",
+      "rightkit-control": "0.1.9",
       "rightkit-crash": "0.1.0",
       "rightkit-db": "0.3.0",
       "rightkit-embed": "0.2.2",
@@ -306,7 +310,7 @@
       "rightkit-pdf": "0.1.0",
       "rightkit-playback": "0.1.1",
       "rightkit-process": "0.3.1",
-      "rightkit-qa": "0.2.10",
+      "rightkit-qa": "0.2.12",
       "rightkit-qts": "0.2.1",
       "rightkit-qts-ggml": "0.1.0",
       "rightkit-qts-ggml-sys": "0.1.0",
@@ -335,9 +339,9 @@
       "@rightkit/onboarding": "0.2.3",
       "@rightkit/pdf-ui": "0.1.2",
       "@rightkit/platform-ui": "0.1.2",
-      "@rightkit/qa": "0.3.0",
+      "@rightkit/qa": "0.3.2",
       "@rightkit/qa-chrome": "0.1.3",
-      "@rightkit/release": "0.2.132",
+      "@rightkit/release": "0.2.134",
       "@rightkit/settings-ui": "0.2.7",
       "@rightkit/shell": "0.1.0",
       "@rightkit/tauri": "0.1.1",
@@ -389,7 +393,9 @@
     "rightkit-qa": [
       "0.2.7",
       "0.2.8",
-      "0.2.9"
+      "0.2.9",
+      "0.2.10",
+      "0.2.11"
     ],
     "rightkit-sandbox": [
       "0.1.0",
@@ -413,7 +419,8 @@
     ],
     "rightkit-control": [
       "0.1.6",
-      "0.1.7"
+      "0.1.7",
+      "0.1.8"
     ]
   }
 }

package/signing-agent-client.mjs

@@ -6,7 +6,34 @@ import { fileURLToPath } from "node:url";
 import { spawnSync } from "./background-process.mjs";
 import { signingAgentPaths, privatePath, SigningAgentError, MAX_FRAME } from "./rightkit-signing-agent.mjs";
 
-export async function requestSigningAgent(request, { paths = signingAgentPaths(), timeoutMs = 185000,
+export function validateNotaryAgentReport(report) {
+  const fields = (value, allowed) => value && typeof value === "object" && !Array.isArray(value) && Object.keys(value).every((key) => allowed.includes(key));
+  const uuid = (value) => typeof value === "string" && /^[a-f0-9-]{36}$/i.test(value);
+  const n = report?.notarization;
+  const summary = n?.logSummary;
+  if (!fields(report, ["schema", "ok", "id", "notarization", "steps", "stapling", "code", "message"])
+    || report.schema !== 1 || typeof report.ok !== "boolean" || !uuid(report.id)
+    || (report.code !== undefined && !["MAC_SIGNING_AGENT_TIMEOUT", "MAC_SIGNING_AGENT_JOB_FAILED", "MAC_SIGNING_NOTARIZATION_FAILED", "MAC_SIGNING_STAPLE_FAILED"].includes(report.code))
+    || (report.message !== undefined && !["Notarization deadline expired", "Notarization or stapling failed inside signing agent"].includes(report.message))
+    || !fields(n, ["id", "status", "logSummary"]) || !(n.id === null || uuid(n.id))
+    || !["Accepted", "Invalid", "Unknown", "In Progress", "Rejected"].includes(n.status)
+    || !(summary === null || (fields(summary, ["statusCode", "errors", "warnings", "issues"])
+      && (summary.statusCode === null || Number.isInteger(summary.statusCode))
+      && Number.isInteger(summary.errors) && summary.errors >= 0 && Number.isInteger(summary.warnings) && summary.warnings >= 0
+      && Array.isArray(summary.issues) && summary.issues.length <= 100 && summary.issues.every((issue) => fields(issue, ["severity", "code"])
+        && ["error", "warning", "unknown"].includes(issue.severity) && (issue.code === null || Number.isInteger(issue.code)))))
+    || !Array.isArray(report.steps) || report.steps.length > 10 || report.steps.some((step) => !fields(step, ["step", "file", "exitCode"])
+      || !["submit", "log", "probe", "staple", "validate"].includes(step.step)
+      || !(step.exitCode === null || (Number.isInteger(step.exitCode) && step.exitCode >= 0 && step.exitCode <= 255)))
+    || !Array.isArray(report.stapling) || report.stapling.length > 2 || report.stapling.some((item) => !fields(item, ["file", "alreadyStapled", "validated"])
+      || typeof item.file !== "string" || !path.isAbsolute(item.file) || typeof item.alreadyStapled !== "boolean" || item.validated !== true)) {
+    throw new SigningAgentError("MAC_SIGNING_AGENT_PROTOCOL", "Invalid notarization agent report");
+  }
+  return report;
+}
+
+export async function requestSigningAgent(request, { paths = signingAgentPaths(), timeoutMs = (request.timeoutMs ?? 180000) + 5000,
+  onProgress = () => {},
   io = fs, connect = net.createConnection } = {}) {
   try {
     privatePath(paths.directory, 0o700, { io, kind: "directory" });
@@ -23,7 +50,7 @@ export async function requestSigningAgent(request, { paths = signingAgentPaths()
   if (frame.length > MAX_FRAME) throw new SigningAgentError("MAC_SIGNING_AGENT_PROTOCOL", "Signing request is too large");
   return new Promise((resolve, reject) => {
     const socket = connect({ path: paths.socket });
-    let input = Buffer.alloc(0), settled = false;
+    let input = Buffer.alloc(0), settled = false, jobId;
     const finish = (error, report) => {
       if (settled) return;
       settled = true; clearTimeout(timer); socket.destroy();
@@ -38,30 +65,53 @@ export async function requestSigningAgent(request, { paths = signingAgentPaths()
     socket.on("data", (chunk) => {
       input = Buffer.concat([input, chunk]);
       if (input.length > MAX_FRAME) { finish(new SigningAgentError("MAC_SIGNING_AGENT_PROTOCOL", "Signing agent response is too large")); return; }
-      const end = input.indexOf(10);
-      if (end < 0) return;
       try {
-        const report = JSON.parse(input.subarray(0, end).toString("utf8"));
-        if (end !== input.length - 1 || report.schema !== 1 || typeof report.ok !== "boolean") throw new Error();
-        if (!report.ok) {
-          const code = typeof report.code === "string" && report.code.startsWith("MAC_SIGNING_") ? report.code : "MAC_SIGNING_AGENT_JOB_FAILED";
-          finish(new SigningAgentError(code, request.type === "updater" ? "Updater signing failed inside signing agent" : String(report.message ?? "Signing agent rejected request")));
-          return;
+        while (input.indexOf(10) >= 0 && !settled) {
+          const end = input.indexOf(10);
+          const report = JSON.parse(input.subarray(0, end).toString("utf8"));
+          input = input.subarray(end + 1);
+          const notary = ["notarize", "staple"].includes(request.type);
+          if (report.event) {
+            if (!notary || report.schema !== 1 || !["status", "heartbeat"].includes(report.event)
+              || typeof report.id !== "string" || !/^[a-f0-9-]{36}$/i.test(report.id)
+              || Object.keys(report).some((key) => !["schema", "event", "id", "step"].includes(key))
+              || (report.step !== undefined && !["submit", "log", "probe", "staple", "validate"].includes(report.step))) throw new Error();
+            if (jobId && jobId !== report.id) throw new Error();
+            jobId = report.id;
+            onProgress(report);
+            continue;
+          }
+          if (input.length || report.schema !== 1 || typeof report.ok !== "boolean") throw new Error();
+          if (notary && report.notarization) validateNotaryAgentReport(report);
+          if (notary && jobId && jobId !== report.id) throw new Error();
+          if (!report.ok) {
+            const code = typeof report.code === "string" && report.code.startsWith("MAC_SIGNING_") ? report.code : "MAC_SIGNING_AGENT_JOB_FAILED";
+            const error = new SigningAgentError(code, request.type === "updater" ? "Updater signing failed inside signing agent" : notary ? "Notarization or stapling failed inside signing agent" : String(report.message ?? "Signing agent rejected request"));
+            if (notary && report.notarization) error.report = report;
+            finish(error);
+            return;
+          }
+          if (notary) {
+            validateNotaryAgentReport(report);
+          } else if (request.type === "health") {
+            if (report.service !== "dev.rightkit.signing-agent" || !Number.isInteger(report.pid)) throw new Error();
+          } else if (request.type === "codesign-argv") {
+            if (!Array.isArray(report.results) || report.results.length !== 1
+              || report.results.some((r) => !Number.isInteger(r.status) || r.status < 0 || r.status > 255
+                || typeof r.stdout !== "string" || typeof r.stderr !== "string")) throw new Error();
+          } else if (!Array.isArray(report.results) || report.results.length !== (request.items?.length ?? request.files?.length)
+            || report.results.some((r) => r.status !== 0 || typeof r.stdout !== "string" || typeof r.stderr !== "string")
+            || (request.type === "updater" && report.results.some((r) => r.stdout || r.stderr))) throw new Error();
+          finish(null, report);
         }
-        if (request.type === "health") {
-          if (report.service !== "dev.rightkit.signing-agent" || !Number.isInteger(report.pid)) throw new Error();
-        } else if (!Array.isArray(report.results) || report.results.length !== (request.items?.length ?? request.files?.length)
-          || report.results.some((r) => r.status !== 0 || typeof r.stdout !== "string" || typeof r.stderr !== "string")
-          || (request.type === "updater" && report.results.some((r) => r.stdout || r.stderr))) throw new Error();
-        finish(null, report);
       } catch { finish(new SigningAgentError("MAC_SIGNING_AGENT_PROTOCOL", "Invalid signing agent response")); }
     });
   });
 }
-export function requestSigningAgentSync(request, { runClient = spawnSync, home, timeoutMs = 185000 } = {}) {
+export function requestSigningAgentSync(request, { runClient = spawnSync, home, timeoutMs = (request.timeoutMs ?? 180000) + 5000 } = {}) {
   // Existing signing call sites are synchronous. Only typed JSON goes to this
   // child's stdin; credentials & authentication token never enter argv/env.
-  const result = runClient(process.execPath, [fileURLToPath(import.meta.url)], { encoding: "utf8", stdio: "pipe", shell: false,
+  const result = runClient(process.execPath, [fileURLToPath(import.meta.url)], { encoding: "utf8", stdio: ["pipe", "pipe", "inherit"], shell: false,
     input: JSON.stringify({ request, home, timeoutMs }), timeout: timeoutMs + 1000, maxBuffer: MAX_FRAME,
     env: { PATH: process.env.PATH, HOME: process.env.HOME } });
   let report;
@@ -69,17 +119,22 @@ export function requestSigningAgentSync(request, { runClient = spawnSync, home,
     throw new SigningAgentError(result.error?.code === "ETIMEDOUT" ? "MAC_SIGNING_AGENT_TIMEOUT" : "MAC_SIGNING_AGENT_CONNECTION", "Signing agent client failed");
   }
   if (report.schema !== 1 || typeof report.ok !== "boolean") throw new SigningAgentError("MAC_SIGNING_AGENT_PROTOCOL", "Invalid signing agent client report");
-  if (!report.ok) throw new SigningAgentError(report.code ?? "MAC_SIGNING_AGENT_JOB_FAILED", report.message ?? "Signing agent failed");
+  if (!report.ok) {
+    const error = new SigningAgentError(report.code ?? "MAC_SIGNING_AGENT_JOB_FAILED", report.message ?? "Signing agent failed");
+    if (["notarize", "staple"].includes(request.type) && report.notarization) error.report = validateNotaryAgentReport(report);
+    throw error;
+  }
   if (result.error || result.status !== 0) throw new SigningAgentError("MAC_SIGNING_AGENT_CONNECTION", "Signing agent client failed");
   return report;
 }
 if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
   try {
     const { request, home, timeoutMs } = JSON.parse(fs.readFileSync(0, "utf8"));
-    const report = await requestSigningAgent(request, { paths: signingAgentPaths(home), timeoutMs });
+    const report = await requestSigningAgent(request, { paths: signingAgentPaths(home), timeoutMs,
+      onProgress: (frame) => process.stderr.write(`right-release signing-agent: ${frame.id} ${frame.step ?? frame.event}\n`) });
     process.stdout.write(JSON.stringify(report));
   } catch (error) {
-    process.stdout.write(JSON.stringify({ schema: 1, ok: false, code: error.code ?? "MAC_SIGNING_AGENT_PROTOCOL", message: error.message }));
+    process.stdout.write(JSON.stringify(error.report ?? { schema: 1, ok: false, code: error.code ?? "MAC_SIGNING_AGENT_PROTOCOL", message: error.message }));
     process.exitCode = 1;
   }
 }

package/signing-agent-command.mjs

@@ -5,10 +5,11 @@ const [command, ...args] = process.argv.slice(2);
 try {
   let result;
   if (command === "install") {
-    const options = {};
-    if (args.length) {
-      if (args.length !== 2 || args[0] !== "--managed-root" || !args[1]) throw new TypeError("Expected install [--managed-root <absolute-directory>]");
-      options.managedRoot = args[1];
+    const options = { cargoTargetDirs: [] };
+    for (let i = 0; i < args.length; i += 2) {
+      if (!["--managed-root", "--cargo-target-dir"].includes(args[i]) || !args[i + 1]) throw new TypeError("Expected install [--managed-root <directory>] [--cargo-target-dir <directory>]...");
+      if (args[i] === "--managed-root") options.managedRoot = args[i + 1];
+      else options.cargoTargetDirs.push(args[i + 1]);
     }
     result = installSigningAgent(options);
   } else if (command === "uninstall" && !args.length) result = uninstallSigningAgent();

package/signing-agent-install.mjs

@@ -6,6 +6,8 @@ import { AGENT_LABEL, signingAgentPaths, defaultSigningRoots, ensurePrivateDirec
 import { requestSigningAgentSync } from "./signing-agent-client.mjs";
 
 const capture = { encoding: "utf8", stdio: "pipe", shell: false, timeout: 10000 };
+function sleepMs(ms) { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); }
+
 export function requireMacGuiSession({ run = spawnSync, uid = process.getuid?.() } = {}) {
   const session = run("/bin/launchctl", ["print", `gui/${uid}`], capture);
   if (session.error || session.status !== 0) throw new SigningAgentError("MAC_SIGNING_NO_GUI_SESSION", `No logged-in Aqua session for uid ${uid}`);
@@ -27,7 +29,7 @@ export function signingAgentPlist({ paths, node = process.execPath, home }) {
 }
 export function installSigningAgent({ home = os.userInfo().homedir, username = os.userInfo().username,
   uid = process.getuid?.(), platform = process.platform, run = spawnSync, io = fs, node = process.execPath,
-  managedRoot = "/Volumes/D/.rightkit-managed", health = requestSigningAgentSync,
+  managedRoot = "/Volumes/D/.rightkit-managed", cargoTargetDirs = [], health = requestSigningAgentSync,
   now = Date.now, sleep = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms) } = {}) {
   if (platform !== "darwin") throw new SigningAgentError("MAC_SIGNING_AGENT_PLATFORM", "Signing agent requires macOS");
   requireMacGuiSession({ run, uid });
@@ -41,14 +43,26 @@ export function installSigningAgent({ home = os.userInfo().homedir, username = o
   const pnpm = String(found.stdout ?? "").trim();
   if (found.error || found.status !== 0 || !path.isAbsolute(pnpm) || pnpm.includes("\n")) throw new SigningAgentError("MAC_SIGNING_AGENT_INSTALL_FAILED", "Provisioned pnpm executable is unavailable");
   // Resident runtime is self-contained; no package/checkout imports after install.
-  for (const name of ["rightkit-signing-agent.mjs", "background-process.mjs"]) {
+  for (const root of cargoTargetDirs) {
+    if (typeof root !== "string" || !path.isAbsolute(root) || ["/", home, "/Volumes", "/Volumes/D"].includes(path.resolve(root))) throw new SigningAgentError("MAC_SIGNING_AGENT_PATH_DENIED", "Cargo target root must be a dedicated absolute directory");
+  }
+  for (const name of ["rightkit-signing-agent.mjs", "background-process.mjs", "codesign-argv.mjs"]) {
     const target = path.join(paths.runtime, name);
     if (io.existsSync(target)) privatePath(target, 0o600, { io, uid });
     io.writeFileSync(target, io.readFileSync(new URL(`./${name}`, import.meta.url)), { mode: 0o600 });
   }
   if (io.existsSync(paths.config)) privatePath(paths.config, 0o600, { io, uid });
+  // SSH & Aqua can inherit different TMPDIR spellings. Include both aliases of
+  // this uid's Darwin temp root, since bundlers can canonicalize temporary paths.
+  const temp = run("/usr/bin/getconf", ["DARWIN_USER_TEMP_DIR"], capture);
+  const directory = String(temp.stdout ?? "").trim();
+  const temporaryRoots = [];
+  if (!temp.error && temp.status === 0 && path.isAbsolute(directory) && !directory.includes("\n")) {
+    temporaryRoots.push(path.resolve(directory));
+    try { temporaryRoots.push((io.realpathSync.native ?? io.realpathSync)(directory)); } catch {}
+  }
   io.writeFileSync(paths.config, JSON.stringify({ schema: 1, home, username, pnpm,
-    roots: defaultSigningRoots(home, path.resolve(managedRoot)),
+    roots: defaultSigningRoots(home, path.resolve(managedRoot), [...cargoTargetDirs.map((root) => path.resolve(root)), ...temporaryRoots]),
     environmentPath: [...new Set([path.dirname(node), path.dirname(pnpm), "/opt/homebrew/bin", "/usr/local/bin", "/usr/bin", "/bin", "/usr/sbin", "/sbin"])].join(":") }), { mode: 0o600 });
   ensurePrivateDirectory(path.dirname(paths.plist), { io, uid });
   if (io.existsSync(paths.plist)) privatePath(paths.plist, 0o600, { io, uid });
@@ -57,8 +71,20 @@ export function installSigningAgent({ home = os.userInfo().homedir, username = o
   if (!loaded.error && loaded.status === 0) {
     const stopped = run("/bin/launchctl", ["bootout", `gui/${uid}/${AGENT_LABEL}`], capture);
     if (stopped.error || stopped.status !== 0) throw new SigningAgentError("MAC_SIGNING_AGENT_INSTALL_FAILED", "Could not stop existing signing agent");
+    // bootout is asynchronous: wait until launchd has released the label before bootstrapping again.
+    const gone = now() + 10000;
+    while (now() < gone) {
+      const still = run("/bin/launchctl", ["print", `gui/${uid}/${AGENT_LABEL}`], capture);
+      if (still.error || still.status !== 0) break;
+      sleepMs(100);
+    }
+  }
+  let boot = run("/bin/launchctl", ["bootstrap", `gui/${uid}`, paths.plist], capture);
+  // Exit 5 (EIO) is launchd still tearing the old job down; retry briefly.
+  for (let attempt = 0; attempt < 20 && !boot.error && boot.status === 5; attempt++) {
+    sleepMs(250);
+    boot = run("/bin/launchctl", ["bootstrap", `gui/${uid}`, paths.plist], capture);
   }
-  const boot = run("/bin/launchctl", ["bootstrap", `gui/${uid}`, paths.plist], capture);
   if (boot.error || boot.status !== 0) {
     requireMacGuiSession({ run, uid });
     throw new SigningAgentError("MAC_SIGNING_AGENT_INSTALL_FAILED", `Signing agent bootstrap failed (exit ${boot.status ?? "unavailable"})`);