relay-companion 0.1.552 → 0.1.554

package/bootstrap/application-handoff.cjs

@@ -24,6 +24,7 @@ function read(file) {
   catch (error) { if (error.code === "ENOENT") return null; throw error; }
 }
 function updateConsent({ homeDir, env = process.env }) {
+  if (require("./recovery-intent.cjs").stopped(homeDir)) return { ok: false, reason: "intentionally-stopped" };
   if (/^(0|false|off|no)$/i.test(String(env.RELAY_AUTO_UPDATE || ""))
     || read(path.join(homeDir, ".relay", "recovery", "policy.json"))?.autoUpdate === false) return { ok: false, reason: "updates-disabled" };
   const root = path.join(homeDir, ".relay");

package/bootstrap/application-install.cjs

@@ -136,6 +136,7 @@ async function installFromApplication({ resourcesDir, applicationRoot, executabl
       throw new Error("Legacy installation requires the separately planned repair route");
     }
     if (current && versionCompare(bundle.receipt.version, current.version) < 0) throw new Error("An older installer cannot downgrade Relay");
+    require("./recovery-intent.cjs").setStopped(false, homeDir);
     // Live services, not files, decide whether the existing Relay is healthy.
     // A runtime whose daemon and pill are not running gets one repair through
     // its own CLI before it is judged; only a runtime that stays down blocks.

package/bootstrap/lifecycle-ownership.cjs

@@ -0,0 +1,69 @@
+"use strict";
+// All application-facing repairs use the same ownership record as activation.
+// A child of an existing installer joins that exact generation; it never takes
+// an unrelated lock or trusts a caller-supplied boolean saying "updating".
+const fs = require("node:fs"), os = require("node:os"), path = require("node:path");
+const locks = require("./recovery-launcher.cjs");
+const crypto = require("node:crypto");
+const heldLeases = new Map();
+const read = file => { try { return JSON.parse(fs.readFileSync(file, "utf8")); } catch { return null; } };
+
+function lifecycleOwnership({ homeDir = os.homedir(), env = process.env,
+  acquire = locks.acquireCanonicalLock, pid = process.pid, parentPid = process.ppid,
+  alive = locks.processAlive, identity = locks.nativeProcessIdentity } = {}) {
+  const file = path.join(homeDir, ".relay", "runtime", "transaction.lock", "owner.json");
+  const observed = read(file);
+  let lock;
+  const delegated = observed && (observed.pid === parentPid
+    || (env.RELAY_LIFECYCLE_OWNER === `${observed.pid}:${observed.nonce}`));
+  const held = heldLeases.get(file);
+  if (delegated && held?.owner.nonce === observed.nonce) {
+    held.assert();
+    held.references++;
+    let released = false;
+    return { ...held, release: () => { if (released) return; released = true; if (--held.references === 0) { heldLeases.delete(file); held.dispose(); } } };
+  }
+  if (!delegated) lock = acquire(path.dirname(file));
+  const owner = read(file);
+  const lockDir = path.dirname(file);
+  let participant;
+  // Only join while the granting process still exists. A stale environment
+  // capability cannot resurrect a dead transaction.
+  if (delegated && owner?.pid !== pid) {
+    if (!alive(owner?.pid) || (owner.processIdentity && identity(owner.pid) !== owner.processIdentity)) throw Error("lifecycle-owner-ended");
+    participant = path.join(lockDir, `participant-${pid}-${crypto.randomBytes(16).toString("hex")}.json`);
+    fs.writeFileSync(participant, JSON.stringify({ nonce: owner.nonce, pid, createdAt: Date.now(), processIdentity: identity(pid) }), { flag: "wx", mode: 0o600 });
+  }
+  const assert = () => {
+    const current = read(file);
+    if (!owner?.nonce || current?.nonce !== owner.nonce || current.pid !== owner.pid
+      || fs.existsSync(path.join(lockDir, "reclaim.json"))
+      || (!participant && (!alive(owner.pid) || (owner.processIdentity && identity(owner.pid) !== owner.processIdentity)))) {
+      throw Error("lifecycle-owner-changed");
+    }
+  };
+  const dispose = () => {
+    if (participant && read(file)?.nonce === owner.nonce) fs.rmSync(participant, { force: true });
+    lock?.release();
+  };
+  try { assert(); } catch (error) { dispose(); throw error; }
+  const lease = {
+    owner, assert, delegated: !lock,
+    env: { ...env, RELAY_LIFECYCLE_OWNER: `${owner.pid}:${owner.nonce}` },
+    references: 1, dispose,
+  };
+  heldLeases.set(file, lease);
+  let released = false;
+  return { ...lease, release: () => {
+    if (released) return;
+    released = true;
+    if (--lease.references === 0) { heldLeases.delete(file); dispose(); }
+  } };
+}
+function ownerEnvironment({ homeDir = os.homedir(), env = process.env } = {}) {
+  const owner = read(path.join(homeDir, ".relay", "runtime", "transaction.lock", "owner.json"));
+  // Only the actual owner may hand its generation to a worker.
+  return owner?.pid === process.pid && owner.nonce
+    ? { ...env, RELAY_LIFECYCLE_OWNER: `${owner.pid}:${owner.nonce}` } : { ...env };
+}
+module.exports = { lifecycleOwnership, ownerEnvironment };

package/bootstrap/mac-service-recovery.cjs

@@ -26,6 +26,7 @@ function readRegistration(label, { homeDir = os.homedir(), run = defaultRun, fsI
   const plist = JSON.parse(decoded.stdout);
   const args = plist.ProgramArguments;
   if (plist.Label !== label || !Array.isArray(args) || !args.every(x => typeof x === "string") || plist.Program) throw Error(`invalid-service-plist: ${label}`);
+  if (label === LABELS[0] && require("./node-contract.cjs").isElectronExecutable(args[0])) throw Error(`invalid-service-interpreter: ${label}`);
   const suffix = label === LABELS[0] ? /[\\/]bin[\\/]relay\.js$/ : /[\\/]overlay[\\/]main\.cjs$/;
   const script = args.find(x => /[\\/]node_modules[\\/]relay-companion[\\/]/.test(x) && suffix.test(x));
   if (!script || !path.isAbsolute(args[0]) || !path.isAbsolute(script) || (label === LABELS[0] && !args.includes("daemon"))) throw Error(`invalid-service-target: ${label}`);
@@ -84,7 +85,7 @@ async function restartMacRegisteredServices(target, {
   healthCheck = require("./runtime-health.cjs").exactRuntimeHealth,
   sleep = ms => new Promise(resolve => setTimeout(resolve, ms)),
 } = {}) {
-  let lock;
+  let lock, releaseDrain;
   try { lock = acquireLock(path.join(homeDir, ".relay", "runtime", "transaction.lock")); }
   catch { return { ok: false, reason: "deferred-update-owner" }; }
   try {
@@ -92,6 +93,7 @@ async function restartMacRegisteredServices(target, {
     if (!current?.active || current.packageRoot !== target.packageRoot) return { ok: false, reason: "runtime-changed" };
     const records = LABELS.map(label => readRegistration(label, { homeDir, run }));
     if (records.some(r => r.packageRoot !== target.packageRoot)) return { ok: false, reason: "runtime-changed" };
+    releaseDrain = await require("./update-activity.cjs").drainCalls({ homeDir, sleep });
     for (const record of records) {
       const observed = registration(record.label, { run, userId });
       if (!observed.known) return { ok: false, reason: "service-registration-query-failed" };
@@ -105,7 +107,7 @@ async function restartMacRegisteredServices(target, {
     }
     return { ok: false, reason: "restarted-runtime-not-healthy" };
   } catch (error) { return { ok: false, reason: error.message }; }
-  finally { lock.release(); }
+  finally { releaseDrain?.(); lock.release(); }
 }
 
 module.exports = { LABELS, registration, readRegistration, repairMacServiceRegistrations, restartMacRegisteredServices };

package/bootstrap/node-contract.cjs

@@ -0,0 +1,41 @@
+"use strict";
+// Shared by setup, application workers and the independent recovery bundle.
+// An interpreter is an executable contract, never the identity of its caller.
+const fs = require("node:fs"), os = require("node:os"), path = require("node:path");
+const { spawnSync } = require("node:child_process");
+
+function isElectronExecutable(executable, { realpath = fs.realpathSync } = {}) {
+  const electron = value => /(?:^|[\\/])(?:electron|relay)(?:\.exe|\.app(?:[\\/]|$)|$)|\.app[\\/]Contents[\\/]MacOS[\\/]/i.test(String(value || ""));
+  if (electron(executable) || (executable === process.execPath && process.versions.electron)) return true;
+  try { return electron(realpath(executable)); } catch { return false; }
+}
+function nodeEnvironment(env = process.env) {
+  const clean = { ...env };
+  for (const key of Object.keys(clean)) {
+    if (/^(NODE_OPTIONS|NODE_PATH|ELECTRON_RUN_AS_NODE)$/i.test(key)) delete clean[key];
+  }
+  return clean;
+}
+function verifyNode(executable, { run = spawnSync, env = process.env, realpath = fs.realpathSync } = {}) {
+  if (!executable || isElectronExecutable(executable, { realpath })) return { ok: false, reason: "node-is-electron" };
+  try {
+    const result = run(executable, ["-p", "process.versions.electron ? '' : process.versions.node"],
+      { encoding: "utf8", windowsHide: true, timeout: 5000, env: nodeEnvironment(env) });
+    const version = String(result?.stdout ?? result?.out ?? "").trim();
+    const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(version);
+    const ok = !result?.error && (result?.status === 0 || result?.ok === true)
+      && match && (Number(match[1]) > 22 || (Number(match[1]) === 22 && Number(match[2]) >= 12));
+    return { ok: Boolean(ok), version, reason: ok ? null : "node-contract-failed" };
+  } catch (error) { return { ok: false, reason: "node-contract-failed", detail: error.message }; }
+}
+function resolveManagedNode({ homeDir = os.homedir(), node = process.execPath, run = spawnSync,
+  env = process.env, read = file => JSON.parse(fs.readFileSync(file, "utf8")) } = {}) {
+  const candidates = [];
+  for (const file of ["recovery/current.json", "recovery/known-good.json", "recovery/launcher-node.json", "runtime/current.json"]) {
+    try { const value = read(path.join(homeDir, ".relay", file)); if (value?.node) candidates.push(value.node); } catch {}
+  }
+  candidates.push(node);
+  for (const candidate of new Set(candidates)) if (verifyNode(candidate, { run, env }).ok) return candidate;
+  throw Error("No verified Relay Node runtime is available; open the Relay installer to restore it.");
+}
+module.exports = { isElectronExecutable, nodeEnvironment, verifyNode, resolveManagedNode };

package/bootstrap/owned-node-runtime.cjs

@@ -5,6 +5,7 @@ const fs = require("node:fs");
 const os = require("node:os");
 const path = require("node:path");
 const { spawnSync } = require("node:child_process");
+const { isElectronExecutable, nodeEnvironment } = require("./node-contract.cjs");
 
 function nodeVersionSupported(version) {
   const match = /^(\d+)\.(\d+)\.(\d+)/.exec(String(version || "").trim());
@@ -19,11 +20,13 @@ function commandOutput(result) {
 }
 
 function verifiedNodeVersion(executable, { runCommand = spawnSync, timeout = 5_000 } = {}) {
+  if (isElectronExecutable(executable)) return { ok: false, version: "", detail: "Electron is not a service Node runtime" };
   try {
-    const result = runCommand(executable, ["-p", "process.versions.node"], {
+    const result = runCommand(executable, ["-p", "process.versions.electron ? '' : process.versions.node"], {
       encoding: "utf8",
       timeout,
       windowsHide: true,
+      env: nodeEnvironment(),
     });
     const ok = result?.ok === true || (!result?.error && result?.status === 0);
     const version = commandOutput(result);
@@ -71,6 +74,7 @@ function relayOwnedNodePath(executable, {
   isTemporary = isTemporaryNodePath,
   randomBytes = crypto.randomBytes,
 } = {}) {
+  if (isElectronExecutable(executable, { realpath: realpathSync })) throw new Error("Electron is not a service Node runtime");
   if (!executable || !isTemporary(executable, { platform, realpathSync })) return executable;
 
   let source;

package/bootstrap/recovery-client.cjs

@@ -0,0 +1,74 @@
+"use strict";
+// Observation is not permission to edit service registrations. Wake the
+// independently installed controller and let it judge the current generation.
+const fs = require("node:fs"), os = require("node:os"), path = require("node:path");
+const { spawnSync } = require("node:child_process");
+const { atomicFile } = require("./mac-registration-transaction.cjs");
+const { resolveManagedNode, nodeEnvironment } = require("./node-contract.cjs");
+const { lifecycleOwnership } = require("./lifecycle-ownership.cjs");
+const { Worker, isMainThread, workerData, parentPort } = require("node:worker_threads");
+const ok = r => !r?.error && (r?.status === 0 || r?.ok === true);
+
+function requestRecovery({ homeDir = os.homedir(), platform = process.platform, reason = "health-check",
+  packageRoot, node, env = process.env, now = Date.now,
+  run = (file, args, options) => spawnSync(file, args, { encoding: "utf8", windowsHide: true, timeout: 15_000, ...options }),
+  install = options => require("./recovery-install.cjs").installRecovery(options),
+  own = lifecycleOwnership, userId = process.getuid?.() ?? 0 } = {}) {
+  const root = path.join(homeDir, ".relay", "recovery");
+  if (require("./recovery-intent.cjs").stopped(homeDir)) return { ok: false, reason: "intentionally-stopped" };
+  const label = "work.relay.companion.recovery", task = "Relay Companion Recovery";
+  const query = platform === "win32" ? ["schtasks.exe", ["/Query", "/TN", task]]
+    : platform === "darwin" ? ["/bin/launchctl", ["print", `gui/${userId}/${label}`]]
+    : ["systemctl", ["--user", "show", "--property=LoadState", "--value", `${label}.service`]];
+  const observed = run(...query);
+  const text = String(observed?.stdout ?? observed?.out ?? "");
+  const present = ok(observed) && (platform !== "linux" || text.trim() === "loaded");
+  if (!present) {
+    // A failed query is not proof of absence. In particular, do not rewrite a
+    // launch agent because its GUI domain is temporarily unavailable at login.
+    const detail = String(observed?.stderr ?? observed?.out ?? "");
+    const missing = !observed?.error && (platform === "darwin"
+      ? observed.status === 113 || /Could not find service/i.test(detail)
+      : platform === "linux" ? text.trim() === "not-found"
+      : /cannot find|does not exist|not found/i.test(detail));
+    if (!missing || !packageRoot) return { ok: false, reason: "recovery-registration-unavailable" };
+    let lease;
+    try {
+      lease = own({ homeDir, env });
+      const interpreter = resolveManagedNode({ homeDir, node, run, env });
+      lease.assert();
+      const result = install({ packageRoot, node: interpreter, homeDir, platform, reload: true, runCommand: run });
+      if (!result.ok) return { ok: false, reason: result.reason, detail: result.detail };
+    } catch (error) { return { ok: false, reason: "recovery-bootstrap-deferred", detail: error.message }; }
+    finally { lease?.release(); }
+  }
+  fs.mkdirSync(root, { recursive: true, mode: 0o700 });
+  atomicFile(path.join(root, "request.json"), JSON.stringify({ schema: 1, reason, at: now() }));
+  const command = platform === "win32" ? ["schtasks.exe", ["/Run", "/TN", task]]
+    : platform === "darwin" ? ["/bin/launchctl", ["kickstart", `gui/${userId}/${label}`]]
+    : ["systemctl", ["--user", "start", "--no-block", `${label}.service`]];
+  const submitted = run(...command, { env: nodeEnvironment(env) });
+  return { ok: ok(submitted), reason: ok(submitted) ? "recovery-requested" : "recovery-start-failed",
+    detail: ok(submitted) ? "" : String(submitted?.error?.message || submitted?.stderr || submitted?.out || "") };
+}
+// launchctl, Task Scheduler and interpreter verification must never block the
+// Electron event loop whose responsiveness we are trying to preserve.
+function requestRecoveryAsync(options = {}) {
+  return new Promise((resolve) => {
+    const worker = new Worker(__filename, { workerData: { relayRecoveryRequest: options } });
+    let settled = false;
+    const finish = result => { if (!settled) { settled = true; clearTimeout(timer); resolve(result); } };
+    const timer = setTimeout(() => {
+      void worker.terminate();
+      finish({ ok: false, reason: "recovery-request-deadline" });
+    }, 120_000);
+    worker.once("message", finish);
+    worker.once("error", error => finish({ ok: false, reason: "recovery-request-failed", detail: error.message }));
+    worker.once("exit", () => finish({ ok: false, reason: "recovery-request-exited" }));
+  });
+}
+if (!isMainThread && workerData?.relayRecoveryRequest) {
+  try { parentPort.postMessage(requestRecovery(workerData.relayRecoveryRequest)); }
+  catch (error) { parentPort.postMessage({ ok: false, reason: "recovery-request-failed", detail: error.message }); }
+}
+module.exports = { requestRecovery, requestRecoveryAsync };

package/bootstrap/recovery-install.cjs

@@ -52,7 +52,7 @@ function windowsRecoveryTaskXml(script, startAt = new Date()) {
   <Triggers>
     <TimeTrigger>
       <StartBoundary>${boundary}</StartBoundary>
-      <Repetition><Interval>PT5M</Interval><StopAtDurationEnd>false</StopAtDurationEnd></Repetition>
+      <Repetition><Interval>PT1M</Interval><StopAtDurationEnd>false</StopAtDurationEnd></Repetition>
       <Enabled>true</Enabled>
     </TimeTrigger>
   </Triggers>
@@ -183,7 +183,8 @@ function installRecovery({ packageRoot, node = process.execPath, homeDir = os.ho
     } else if (platform === "darwin") {
       const plist = path.join(homeDir, "Library", "LaunchAgents", `${LABEL}.plist`);
       fs.mkdirSync(path.dirname(plist), { recursive: true });
-      atomicFile(plist, `<?xml version="1.0"?><plist version="1.0"><dict><key>Label</key><string>${LABEL}</string><key>ProgramArguments</key><array><string>${xml(launcherNode)}</string><string>${xml(launcher)}</string></array><key>EnvironmentVariables</key><dict><key>HOME</key><string>${xml(homeDir)}</string></dict><key>StartInterval</key><integer>300</integer><key>RunAtLoad</key><true/><key>ProcessType</key><string>Background</string><key>StandardOutPath</key><string>${xml(log)}</string><key>StandardErrorPath</key><string>${xml(log)}</string></dict></plist>`);
+      const priorSchedule = fs.existsSync(plist) ? fs.readFileSync(plist) : null;
+      atomicFile(plist, `<?xml version="1.0"?><plist version="1.0"><dict><key>Label</key><string>${LABEL}</string><key>ProgramArguments</key><array><string>${xml(launcherNode)}</string><string>${xml(launcher)}</string></array><key>EnvironmentVariables</key><dict><key>HOME</key><string>${xml(homeDir)}</string></dict><key>StartInterval</key><integer>60</integer><key>RunAtLoad</key><true/><key>ProcessType</key><string>Background</string><key>StandardOutPath</key><string>${xml(log)}</string><key>StandardErrorPath</key><string>${xml(log)}</string></dict></plist>`);
       // The job dispatches through the stable host. Do not unload it on update.
       const observed = runCommand("launchctl", ["print", `gui/${userId}/${LABEL}`]);
       if (!ok(observed)) {
@@ -191,12 +192,23 @@ function installRecovery({ packageRoot, node = process.execPath, homeDir = os.ho
         if (!missing) throw Error("recovery-registration-query-failed");
         results.push(runCommand("launchctl", ["bootstrap", `gui/${userId}`, plist]));
         results.push(runCommand("launchctl", ["print", `gui/${userId}/${LABEL}`]));
+        write(path.join(root, "scheduler.json"), { schema: 1, intervalSeconds: 60, at: Date.now() });
+      }
+      if (ok(observed) && read(path.join(root, "scheduler.json"))?.intervalSeconds !== 60) {
+        const job = "work.relay.recovery.schedule-handover";
+        const pending = runCommand("launchctl", ["list", job]);
+        if (!(ok(pending) && /"PID"\s*=\s*[1-9]\d*/.test(String(pending.stdout || pending.out || "")))) {
+          if (ok(pending)) runCommand("launchctl", ["remove", job]);
+          if (priorSchedule) atomicFile(path.join(root, "scheduler-previous.plist"), priorSchedule);
+          results.push(runCommand("launchctl", ["submit", "-l", job, "-o", log, "-e", log, "--", runtimeNode,
+            path.join(bundle, "bootstrap", "recovery-schedule-handover.cjs"), homeDir, String(userId)]));
+        }
       }
     } else {
       const dir = path.join(homeDir, ".config", "systemd", "user");
       fs.mkdirSync(dir, { recursive: true });
       atomicFile(path.join(dir, `${LABEL}.service`), `[Unit]\nDescription=Relay update recovery\n[Service]\nType=oneshot\nExecStart=${unit(launcherNode)} ${unit(launcher)}\nTimeoutStartSec=1800\nKillMode=control-group\n`);
-      atomicFile(path.join(dir, `${LABEL}.timer`), `[Unit]\nDescription=Check Relay update health\n[Timer]\nOnBootSec=2min\nOnUnitInactiveSec=5min\nPersistent=true\n[Install]\nWantedBy=timers.target\n`);
+      atomicFile(path.join(dir, `${LABEL}.timer`), `[Unit]\nDescription=Check Relay update health\n[Timer]\nOnBootSec=15s\nOnUnitInactiveSec=30s\nPersistent=true\n[Install]\nWantedBy=timers.target\n`);
       // The user manager can retain a different HOME from this installer.
       // Registration is required even when thin setup defers starting services.
       for (const ext of ["service", "timer"]) {

package/bootstrap/recovery-intent.cjs

@@ -0,0 +1,11 @@
+"use strict";
+const fs = require("node:fs"), os = require("node:os"), path = require("node:path");
+const file = homeDir => path.join(homeDir, ".relay", "recovery", "intent.json");
+function stopped(homeDir = os.homedir()) {
+  try { return JSON.parse(fs.readFileSync(file(homeDir), "utf8")).stopped === true; }
+  catch (error) { return error.code !== "ENOENT"; }
+}
+function setStopped(value, homeDir = os.homedir()) {
+  require("./recovery-launcher.cjs").write(file(homeDir), { schema: 1, stopped: value, at: Date.now() });
+}
+module.exports = { stopped, setStopped };

package/bootstrap/recovery-launcher.cjs

@@ -6,8 +6,26 @@ function read(file) { try { return JSON.parse(fs.readFileSync(file, "utf8")); }
 function write(file, data) {
   fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
   const temp = `${file}.${process.pid}.${crypto.randomUUID()}.tmp`;
-  fs.writeFileSync(temp, JSON.stringify(data) + "\n", { mode: 0o600 });
-  fs.renameSync(temp, file);
+  let fd;
+  try {
+    fd = fs.openSync(temp, "wx", 0o600);
+    fs.writeFileSync(fd, JSON.stringify(data) + "\n");
+    fs.fsyncSync(fd); fs.closeSync(fd); fd = undefined;
+    const start = Date.now();
+    for (;;) {
+      try { fs.renameSync(temp, file); break; }
+      catch (error) {
+        if (!["EPERM", "EBUSY", "EACCES"].includes(error.code) || Date.now() - start > 3000) throw error;
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 50);
+      }
+    }
+    if (process.platform !== "win32") {
+      fd = fs.openSync(path.dirname(file), "r"); fs.fsyncSync(fd); fs.closeSync(fd); fd = undefined;
+    }
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd);
+    try { fs.unlinkSync(temp); } catch (error) { if (error.code !== "ENOENT") throw error; }
+  }
 }
 function validPointer(p, root) {
   return p?.schema === 1 && /^\d+\.\d+\.\d+$/.test(p.version || "")
@@ -198,6 +216,27 @@ function acquireCanonicalReclaimClaim(reclaimPath, {
   return false;
 }
 
+// Delegated mutation workers retain the generation after their parent dies.
+// Unknown records fail closed. Reclaimers check again after winning the claim;
+// workers publish before checking that no reclaim is underway.
+function liveLockParticipants(lockPath, nonce, {
+  readdirSync = fs.readdirSync, readFileSync = fs.readFileSync,
+  isProcessAlive = processAlive, processIdentity = nativeProcessIdentity,
+} = {}) {
+  let names;
+  try { names = readdirSync(lockPath); } catch (error) { return error.code !== "ENOENT"; }
+  for (const name of names) {
+    const match = /^participant-([1-9][0-9]*)-[0-9a-f]+\.json$/.exec(name);
+    if (!match) continue;
+    let member;
+    try { member = JSON.parse(readFileSync(path.join(lockPath, name), "utf8")); }
+    catch (error) { if (error.code === "ENOENT" || !isProcessAlive(Number(match[1]))) continue; return true; }
+    if (member.nonce !== nonce) continue;
+    if (canonicalLockOwnerState(member, { isProcessAlive, processIdentity }) !== "dead") return true;
+  }
+  return false;
+}
+
 function acquireCanonicalLock(lockPath, {
   now = Date.now,
   // Preserve the shipped bootstrap's two-hour grace for incomplete records.
@@ -285,7 +324,7 @@ function acquireCanonicalLock(lockPath, {
         release() {
           let owner = null;
           try { owner = JSON.parse(readFileSync(ownerPath, "utf8")); } catch {}
-          if (owner?.nonce === nonce) rmSync(lockPath, { recursive: true, force: true });
+          if (owner?.nonce === nonce && !liveLockParticipants(lockPath, nonce)) rmSync(lockPath, { recursive: true, force: true });
         },
       };
     } catch (error) {
@@ -314,7 +353,7 @@ function acquireCanonicalLock(lockPath, {
       // have observed the directory between mkdir and owner.json being written.
       const stale = ownerState === "dead"
         || (ownerState === "unknown" && observedAt > 0 && now() - observedAt > staleAfterMs);
-      if (!stale || attempt > 0) lockFail("Another verified Relay install or update is already in progress.");
+      if (!stale || attempt > 0 || liveLockParticipants(lockPath, owner?.nonce, { readdirSync, readFileSync, isProcessAlive, processIdentity })) lockFail("Another verified Relay install or update is already in progress.");
 
       // Serialize reclaimers inside this exact lock generation, then re-read the
       // owner after winning. This closes the race where one retry replaced the
@@ -356,7 +395,7 @@ function acquireCanonicalLock(lockPath, {
         const confirmedState = canonicalLockOwnerState(confirmedOwner, { isProcessAlive, processIdentity });
         const confirmedStale = confirmedState === "dead"
           || (confirmedState === "unknown" && confirmedAt > 0 && now() - confirmedAt > staleAfterMs);
-        if (!confirmedStale) lockFail("Another verified Relay install or update is already in progress.");
+        if (!confirmedStale || liveLockParticipants(lockPath, confirmedOwner?.nonce, { readdirSync, readFileSync, isProcessAlive, processIdentity })) lockFail("Another verified Relay install or update is already in progress.");
         let confirmedClaim = null;
         try { confirmedClaim = JSON.parse(readFileSync(reclaimPath, "utf8")); } catch {}
         if (confirmedClaim?.nonce !== nonce) lockFail("Another verified Relay install or update is already in progress.");
@@ -525,5 +564,5 @@ async function launch({ root = __dirname, run = runChild, now = Date.now, env =
     return { ok: false, status: "failed" };
   } finally { release(); }
 }
-module.exports = { launch, validPointer, read, write, acquireLauncherLock, appendRecoveryLog, acquireCanonicalLock, processAlive, nativeProcessIdentity, nativeIdentityBirth };
+module.exports = { launch, validPointer, read, write, acquireLauncherLock, appendRecoveryLog, acquireCanonicalLock, processAlive, nativeProcessIdentity, nativeIdentityBirth, liveLockParticipants };
 if (require.main === module) launch().then(result => { process.exitCode = result.ok ? 0 : 1; }).catch(e => { console.error(e.message); process.exitCode = 1; });

package/bootstrap/recovery-runner.cjs

@@ -11,7 +11,7 @@ const { stageVerifiedRuntime, releasePlatform } = require("./relay-setup.cjs");
 const { verifyReleaseEnvelope } = require("./release-signature.cjs");
 const { inFlightTransaction, workerLostLock } = require("./recovery-transaction.cjs");
 const trust = require("./trust.json");
-const CHECK_MS = 5 * 60_000;
+const CHECK_MS = 60_000;
 const DEADLINE_MS = 25 * 60_000;
 const HEARTBEAT_MS = 60_000;
 const BUSY_GRACE_MS = 15 * 60_000;
@@ -22,10 +22,7 @@ const STARTUP_GRACE_MS = 3 * 60_000;
 
 function read(file) { try { return JSON.parse(fs.readFileSync(file, "utf8")); } catch { return null; } }
 function write(file, value) {
-  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
-  const tmp = `${file}.${process.pid}.${crypto.randomBytes(4).toString("hex")}.tmp`;
-  fs.writeFileSync(tmp, JSON.stringify(value) + "\n", { mode: 0o600 });
-  fs.renameSync(tmp, file);
+  require("./recovery-launcher.cjs").write(file, value);
 }
 function compare(a, b) {
   if (!/^\d+\.\d+\.\d+$/.test(a || "") || !/^\d+\.\d+\.\d+$/.test(b || "")) return null;
@@ -118,10 +115,9 @@ function execute(node, entry, args, { timeoutMs = DEADLINE_MS, spawnImpl = spawn
 // daemon, or a machine so starved that a healthy daemon missed a few ticks.
 // Only a heartbeat that stays stale across two scheduled checks proves the
 // former while the process is still alive. A missing process needs no second look.
-// Ten minutes, two scheduled checks apart: a daemon whose process is present
-// and whose heartbeat was recent is far more often slow than dead, and every
-// false restart takes the person's Companion away with it.
-const STALE_CONFIRM_MS = 10 * 60_000;
+// Confirm across consecutive awake observations. A gap caused by sleep or a
+// stalled scheduler resets this window rather than counting as a live hang.
+const STALE_CONFIRM_MS = 60_000;
 const MAX_IN_PLACE_RESTARTS = 2;
 
 // A runner killed mid-extraction by the launcher's deadline leaves its staged
@@ -163,8 +159,13 @@ async function recoverLocked({ homeDir = os.homedir(), env = process.env, now =
   policyFactory = require("./recovery-policy.cjs").recoveryPolicy,
   validateLocal = require("./recovery-local.cjs").validateLocalRuntime,
   transactions = inFlightTransaction,
-  repairServices = require("./mac-service-recovery.cjs").repairMacServiceRegistrations } = {}) {
+  repairServices = require("./service-recovery.cjs").repairServiceRegistrations } = {}) {
   const root = path.join(homeDir, ".relay");
+  if (require("./recovery-intent.cjs").stopped(homeDir)) {
+    const result = { ok: true, status: "intentionally-stopped", runtimeHealthy: false };
+    write(path.join(root, "recovery", "status.json"), { schema: 1, checkedAt: now(), runId: env.RELAY_RECOVERY_RUN_ID || null, launcherVersion: require("../package.json").version, ...result });
+    return result;
+  }
   // Local availability is independent of update eligibility, network, memory,
   // and the journal's active flag. This helper shares the activation lock.
   let progress, reservedService;
@@ -177,9 +178,10 @@ async function recoverLocked({ homeDir = os.homedir(), env = process.env, now =
     return { ...repaired, ok: false, status: "repair-progress-unavailable", runtimeHealthy: false, lastError: error.message };
   }
   let services;
-  try { services = await repairServices({ homeDir, platform }); }
+  try { services = reservedService ? await repairServices({ homeDir, platform }) : { ok: true, changed: false, status: "service-budget-exhausted" }; }
   catch (error) { services = { ok: false, status: "service-repair-failed", lastError: error.message }; }
-  if (reservedService && (services.status === "deferred-update-owner" || (services.ok && !services.changed))) progress.refund("services");
+  const serviceQueryUncertain = /^service-registration-query-failed/.test(services.lastError || "");
+  if (reservedService && (serviceQueryUncertain || services.status === "deferred-update-owner" || (services.ok && !services.changed))) progress.refund("services");
   const ready = (target = null, after = 0) => verifyReady({ homeDir, platform, target, after, now, sleep, health });
   const rememberReady = observed => {
     const active = observed?.current || read(path.join(root, "runtime", "current.json"));
@@ -225,6 +227,7 @@ async function recoverLocked({ homeDir = os.homedir(), env = process.env, now =
       transaction: { pid: transaction.pid, requestId: transaction.requestId, version: transaction.version } });
   };
   if (services.status === "deferred-update-owner") return status({ ...services, runtimeHealthy: false });
+  if (serviceQueryUncertain) return status({ ...services, runtimeHealthy: false });
   if (services.changed || !services.ok) {
     const observed = await ready();
     if (observed.ok) return proven({ ok: true, status: "current", version: observed.current?.version, repair: "services", lastSuccessAt: now() }, observed);
@@ -235,7 +238,7 @@ async function recoverLocked({ homeDir = os.homedir(), env = process.env, now =
     // Accepted commands are not recovery. Repeated failure advances even when
     // an inactive journal or unusable registration snapshot is still present.
   }
-  if (/^(0|false|off|no)$/i.test(String(env.RELAY_AUTO_UPDATE || "")) || read(path.join(root, "recovery", "policy.json"))?.autoUpdate === false) return status({ ok: true, status: "disabled" });
+  const updatesEnabled = !/^(0|false|off|no)$/i.test(String(env.RELAY_AUTO_UPDATE || "")) && read(path.join(root, "recovery", "policy.json"))?.autoUpdate !== false;
   const downloads = path.join(root, "recovery", "downloads");
   let staged = null;
   let discoveryError = null;
@@ -243,18 +246,23 @@ async function recoverLocked({ homeDir = os.homedir(), env = process.env, now =
   let current = null;
   let runtimeResponsive = false;
   let runtimeVerified = false;
-  try {
-    sweepAbandonedDownloads(downloads, log);
-    // Discovery still comes first, but an unreachable registry no longer blocks
-    // the local rungs: a dead daemon with the right code on disk needs a restart,
-    // not a network connection.
+  let discoveryAttempted = false;
+  const discoverDesired = async () => {
+    if (!updatesEnabled || discoveryAttempted) return;
+    discoveryAttempted = true;
     try { desiredVersion = await discoverImpl(channel); log(`discovered ${desiredVersion} on ${channel}`); }
     catch (error) { discoveryError = error; log(`discovery failed: ${error.message}`); }
+  };
+  try {
+    sweepAbandonedDownloads(downloads, log);
     current = read(path.join(root, "runtime", "current.json"));
     const heartbeat = read(path.join(root, "recovery", "daemon.json"));
     const heartbeatFresh = heartbeat?.at <= now() && now() - heartbeat.at < HEARTBEAT_MS;
     const installedIsDesired = current?.active === true;
     const live = installedIsDesired ? await health(current, { platform }) : null;
+    // Local repairs never wait behind registry timeouts. Healthy installations
+    // still check for new releases; unavailable ones exhaust retained repairs first.
+    if (!installedIsDesired || (live?.ok && heartbeatFresh)) await discoverDesired();
     if (live && platform === "darwin" && !services.ok) live.ok = false;
     let readiness = null;
     if (installedIsDesired && heartbeatFresh && heartbeat.version === current.version && live.ok) {
@@ -277,7 +285,9 @@ async function recoverLocked({ homeDir = os.homedir(), env = process.env, now =
       repairState.version = current.version;
       const sameTarget = previous?.version === current.version;
       repairState.restarts = progress.count(`restart:${current.packageRoot || current.version}`);
-      repairState.staleSince = sameTarget && Number.isFinite(previous.staleSince) && previous.staleSince <= now() ? previous.staleSince : now();
+      const cadence = platform === "darwin" && read(path.join(root, "recovery", "scheduler.json"))?.intervalSeconds !== 60 ? 5 * 60_000 : CHECK_MS;
+      const consecutive = previous?.checkedAt <= now() && now() - previous.checkedAt <= cadence * 2;
+      repairState.staleSince = sameTarget && consecutive && Number.isFinite(previous.staleSince) && previous.staleSince <= now() ? previous.staleSince : now();
     }
     if (installedIsDesired && !(live.ok && heartbeatFresh && heartbeat.version === current.version)) {
       // The code on disk is the code we want; the problem is liveness. Repair in
@@ -377,6 +387,8 @@ async function recoverLocked({ homeDir = os.homedir(), env = process.env, now =
         progress.fail(error.message); log('local recovery failed: ' + error.message);
       }
     }
+    if (!updatesEnabled) return status({ ok: true, status: "disabled", runtimeHealthy: runtimeVerified, runtimeAvailable: runtimeResponsive });
+    await discoverDesired();
     if (discoveryError) throw discoveryError;
     let quarantine = policy.decision(channel, desiredVersion);
     if (quarantine.blocked && !runtimeResponsive) {

package/bootstrap/recovery-schedule-handover.cjs

@@ -0,0 +1,52 @@
+"use strict";
+// A launchd job cannot reload itself without killing its installer. This small
+// independent worker waits for the old controller, owns its exclusion locks,
+// and restores the previous plist if the new schedule cannot be loaded.
+const fs = require("node:fs"), path = require("node:path");
+const { spawnSync } = require("node:child_process");
+const io = require("./recovery-launcher.cjs");
+async function handover({ homeDir, userId, sleep = ms => new Promise(resolve => setTimeout(resolve, ms)),
+  run = (file, args) => spawnSync(file, args, { encoding: "utf8", timeout: 15_000, windowsHide: true }), attempts = 360 } = {}) {
+  const root = path.join(homeDir, ".relay", "recovery");
+  const label = "work.relay.companion.recovery", domain = `gui/${userId}`;
+  const plist = path.join(homeDir, "Library", "LaunchAgents", `${label}.plist`);
+  const previous = path.join(root, "scheduler-previous.plist");
+  const ok = r => !r?.error && r?.status === 0;
+  for (let attempt = 0; attempt < attempts; attempt++) {
+    if (require("./recovery-intent.cjs").stopped(homeDir)) return { ok: true, reason: "intentionally-stopped" };
+    let release, runner, transaction;
+    try {
+      release = io.acquireLauncherLock(root);
+      if (!release) continue;
+      runner = io.acquireCanonicalLock(path.join(root, "run.lock"));
+      transaction = io.acquireCanonicalLock(path.join(homeDir, ".relay", "runtime", "transaction.lock"));
+      if (require("./recovery-intent.cjs").stopped(homeDir)) return { ok: true, reason: "intentionally-stopped" };
+      // The old job is no longer running. Keep the old file until bootstrap is
+      // proven; an interrupted handover remains repairable by the app/installer.
+      const removed = run("/bin/launchctl", ["bootout", `${domain}/${label}`]);
+      if (!ok(removed)) throw Error("recovery-schedule-bootout-failed");
+      const started = run("/bin/launchctl", ["bootstrap", domain, plist]);
+      if (!ok(started)) {
+        if (fs.existsSync(previous)) {
+          require("./mac-registration-transaction.cjs").atomicFile(plist, fs.readFileSync(previous));
+          run("/bin/launchctl", ["bootstrap", domain, plist]);
+        }
+        throw Error("recovery-schedule-bootstrap-failed");
+      }
+      io.write(path.join(root, "scheduler.json"), { schema: 1, intervalSeconds: 60, at: Date.now() });
+      return { ok: true };
+    } catch (error) {
+      if (transaction) { io.write(path.join(root, "scheduler-error.json"), { at: Date.now(), error: error.message }); return { ok: false, reason: error.message }; }
+    } finally {
+      transaction?.release(); runner?.release(); release?.();
+      // Sleep also on contention, without retaining any mutation authority.
+      if (!transaction) await sleep(5000);
+    }
+  }
+  return { ok: false, reason: "recovery-schedule-handover-deadline" };
+}
+module.exports = { handover };
+if (require.main === module) handover({ homeDir: process.argv[2], userId: Number(process.argv[3]) }).then(result => {
+  console.log(JSON.stringify(result));
+  // launchctl submit restarts nonzero exits; a failed migration must be bounded.
+}).catch(error => { console.error(error.message); });

package/bootstrap/recovery-transaction.cjs

@@ -11,7 +11,7 @@
 // is a canonical runtime transaction currently owned by a live process?
 const fs = require("node:fs");
 const path = require("node:path");
-const { processAlive, nativeProcessIdentity } = require("./recovery-launcher.cjs");
+const { processAlive, nativeProcessIdentity, liveLockParticipants } = require("./recovery-launcher.cjs");
 
 // An admitted update request older than this is debris from a worker that died
 // without writing its terminal state; the lock engine reclaims after owner death.
@@ -53,7 +53,7 @@ function inFlightTransaction({ homeDir, now = Date.now(), alive = processAlive,
     break;
   }
   if (request) return request;
-  if (owner && liveOwner(owner, { alive, identity })) {
+  if (owner && (liveOwner(owner, { alive, identity }) || liveLockParticipants(path.join(root, "transaction.lock"), owner.nonce, { isProcessAlive: alive, processIdentity: identity }))) {
     return { source: "lock", pid: Number(owner.pid), requestId: owner.requestId || null, version: null, admittedAt: Number(owner.createdAt) || null };
   }
   return null;

package/bootstrap/relay-setup.cjs

@@ -77,6 +77,10 @@ function stableNodePath(execPath = process.execPath, {
   spawnImpl = spawnSync,
 } = {}) {
   if (!execPath) return execPath;
+  const contract = require("./node-contract.cjs");
+  if (contract.isElectronExecutable(execPath, { realpath: realpathSync })) {
+    return contract.resolveManagedNode({ node: null, run: spawnImpl, env });
+  }
   let realExec = execPath;
   try { realExec = realpathSync(execPath); } catch {}
   const volatile = VERSION_MANAGED_NODE_RE.test(execPath)

package/bootstrap/runtime-health.cjs

@@ -407,11 +407,23 @@ async function activateWindowsRuntimeServices(target, {
 }
 
 /** One entry point for "restart what is already installed" on every platform. */
-function restartInstalledRuntimeServices(target, { platform = process.platform, ...options } = {}) {
+async function restartInstalledRuntimeServices(target, { platform = process.platform, ...options } = {}) {
+  if (!["darwin", "linux", "win32"].includes(platform)) return { ok: false, reason: "activation-platform-unsupported" };
   if (platform === "darwin") return require("./mac-service-recovery.cjs").restartMacRegisteredServices(target, options);
-  if (platform === "linux") return activateLinuxRuntimeServices(target, { platform, ...options });
-  if (platform === "win32") return activateWindowsRuntimeServices(target, { platform, ...options });
-  return Promise.resolve({ ok: false, reason: "activation-platform-unsupported" });
+  let lease, releaseDrain;
+  const homeDir = options.homeDir || require("node:os").homedir();
+  try {
+    try { lease = require("./lifecycle-ownership.cjs").lifecycleOwnership({ homeDir }); }
+    catch { return { ok: false, reason: "deferred-update-owner" }; }
+    const current = JSON.parse(fs.readFileSync(path.join(homeDir, ".relay", "runtime", "current.json"), "utf8"));
+    if (!current?.active || current.packageRoot !== target.packageRoot) return { ok: false, reason: "runtime-changed" };
+    releaseDrain = await require("./update-activity.cjs").drainCalls({ homeDir });
+    lease.assert();
+    if (platform === "linux") return await activateLinuxRuntimeServices(target, { platform, ...options });
+    if (platform === "win32") return await activateWindowsRuntimeServices(target, { platform, ...options });
+    return { ok: false, reason: "activation-platform-unsupported" };
+  } catch (error) { return { ok: false, reason: error.message }; }
+  finally { releaseDrain?.(); lease?.release(); }
 }
 
 module.exports = {

package/bootstrap/service-recovery.cjs

@@ -0,0 +1,58 @@
+"use strict";
+const os = require("node:os"), path = require("node:path");
+const { spawnSync } = require("node:child_process");
+const io = require("./recovery-launcher.cjs");
+const nodeContract = require("./node-contract.cjs");
+
+// Registration restoration is part of the controller's canonical transaction.
+// The UI may bootstrap the controller, but never constructs daemon/pill jobs.
+async function repairServiceRegistrations({ homeDir = os.homedir(), platform = process.platform,
+  run = (file, args) => spawnSync(file, args, { encoding: "utf8", windowsHide: true, timeout: 10_000 }),
+  validate = require("./recovery-local.cjs").validateLocalRuntime,
+  execute = (...args) => require("./recovery-runner.cjs").execute(...args),
+  own = require("./lifecycle-ownership.cjs").lifecycleOwnership,
+  drain = require("./update-activity.cjs").drainCalls,
+  activate,
+} = {}) {
+  if (platform === "darwin") {
+    const observed = await require("./mac-service-recovery.cjs").repairMacServiceRegistrations({ homeDir, platform, run });
+    if (observed.ok || observed.blocked) return observed;
+    // Invalid/missing plist bytes cannot be bootstrapped. A verified retained
+    // runtime can rebuild them under the same ownership contract below.
+  } else if (["win32", "linux"].includes(platform)) {
+    let missing = false;
+    for (const role of ["Daemon", "Pill"]) {
+      const result = platform === "win32"
+        ? run("schtasks.exe", ["/Query", "/TN", `Relay Companion ${role}`])
+        : run("systemctl", ["--user", "show", "--property=LoadState", "--value", `work.relay.companion${role === "Pill" ? ".pill" : ""}.service`]);
+      const text = String(result?.stdout || "").trim();
+      const present = !result?.error && result.status === 0 && (platform === "win32" || text === "loaded");
+      if (present) continue;
+      const absent = !result?.error && (platform === "linux" ? text === "not-found" : /cannot find|does not exist|not found/i.test(String(result?.stderr || result?.stdout || "")));
+      if (!absent) return { ok: false, changed: false, blocked: true, status: "service-repair-failed", lastError: "service-registration-query-failed" };
+      missing = true;
+    }
+    if (!missing) return { ok: true, changed: false, status: "services-present" };
+  } else return { ok: true, changed: false, status: "unsupported" };
+
+  let lease, releaseDrain;
+  try {
+    try { lease = own({ homeDir }); }
+    catch { return { ok: true, changed: false, status: "deferred-update-owner" }; }
+    const target = io.read(path.join(homeDir, ".relay", "runtime", "current.json"));
+    if (!target?.active || !validate(target, { platform })) return { ok: false, changed: false, status: "service-repair-failed", lastError: "no-verified-registration-source" };
+    const node = nodeContract.resolveManagedNode({ homeDir, node: target.node, run });
+    releaseDrain = await drain({ homeDir });
+    lease.assert();
+    await execute(node, path.join(target.packageRoot, "bin", "relay.js"), ["repair-runtime", "--no-restart"],
+      { env: nodeContract.nodeEnvironment(lease.env), timeoutMs: 90_000 });
+    lease.assert();
+    const health = require("./runtime-health.cjs");
+    const activateRuntime = activate || (platform === "darwin" ? health.activateMacRuntimeServices
+      : platform === "win32" ? health.activateWindowsRuntimeServices : health.activateLinuxRuntimeServices);
+    const result = await activateRuntime(target, { homeDir, platform });
+    return { ok: result.ok, changed: true, status: result.ok ? "services-restored" : "service-repair-failed", lastError: result.reason };
+  } catch (error) { return { ok: false, changed: false, status: "service-repair-failed", lastError: error.message }; }
+  finally { releaseDrain?.(); lease?.release(); }
+}
+module.exports = { repairServiceRegistrations };

package/bootstrap/update-watchdog.cjs

@@ -22,6 +22,7 @@ function updateLogStdio(platform = process.platform, homeDir = os.homedir()) {
 }
 
 if (require.main === module) {
+  if (process.versions.electron) throw Error("Relay update workers require the verified Node runtime, not Electron");
   const [entry, mode, payload] = process.argv.slice(2);
   if (!entry || mode !== "--worker" || !payload) throw Error("Missing update worker arguments");
   const { stdio, logPath } = updateLogStdio();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "relay-companion",
-  "version": "0.1.552",
+  "version": "0.1.554",
   "description": "Install Relay for Claude Code, Cowork, and Codex, then sign in from the Relay pill.",
   "homepage": "https://sendrelays.com/get-started",
   "repository": {