relay-companion 0.1.554 → 0.1.556

package/bootstrap/mac-service-recovery.cjs

@@ -49,6 +49,7 @@ async function repairMacServiceRegistrations({
   catch { return { ok: true, changed: false, status: "deferred-update-owner" }; }
   const repaired = [];
   try {
+    if (require("./recovery-intent.cjs").stopped(homeDir)) return { ok: true, changed: false, status: "intentionally-stopped" };
     const recovery = require("./mac-registration-transaction.cjs");
     const pending = recovery.readSnapshot({ homeDir, fsImpl });
     if (pending) {
@@ -67,6 +68,7 @@ async function repairMacServiceRegistrations({
       const args = observed.present
         ? ["kickstart", `gui/${userId}/${record.label}`]
         : ["bootstrap", `gui/${userId}`, record.file];
+      if (require("./recovery-intent.cjs").stopped(homeDir)) return { ok: true, changed: repaired.length > 0, status: "intentionally-stopped" };
       const result = run("/bin/launchctl", args);
       if (!commandOk(result)) throw Error(`service-registration-repair-failed: ${record.label}`);
       repaired.push(record.label);
@@ -89,6 +91,7 @@ async function restartMacRegisteredServices(target, {
   try { lock = acquireLock(path.join(homeDir, ".relay", "runtime", "transaction.lock")); }
   catch { return { ok: false, reason: "deferred-update-owner" }; }
   try {
+    if (require("./recovery-intent.cjs").stopped(homeDir)) return { ok: false, reason: "intentionally-stopped" };
     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" };
     const records = LABELS.map(label => readRegistration(label, { homeDir, run }));
@@ -97,6 +100,7 @@ async function restartMacRegisteredServices(target, {
     for (const record of records) {
       const observed = registration(record.label, { run, userId });
       if (!observed.known) return { ok: false, reason: "service-registration-query-failed" };
+      if (require("./recovery-intent.cjs").stopped(homeDir)) return { ok: false, reason: "intentionally-stopped" };
       const args = observed.present ? ["kickstart", "-k", `gui/${userId}/${record.label}`] : ["bootstrap", `gui/${userId}`, record.file];
       if (!commandOk(run("/bin/launchctl", args))) return { ok: false, reason: "service-restart-failed" };
     }

package/bootstrap/recovery-launcher.cjs

@@ -547,7 +547,7 @@ async function launch({ root = __dirname, run = runChild, now = Date.now, env =
       // A worker that lost the canonical lock to a live installer judged nothing
       // about this bundle either; the runner normally reports that as a deferral.
       const lostTransaction = /recovery-worker-exit-75|transaction-in-progress/i.test(report?.lastError || "");
-      const retryableReport = ["disabled", "backoff", "emergency-backoff", "restart-failed", "reactivate-failed", "service-repair-failed", "service-repair-unhealthy"].includes(report?.status) || (report?.status === "failed" && (networkFailure || lostTransaction));
+      const retryableReport = ["disabled", "backoff", "emergency-backoff", "restart-failed", "pill-repair-failed", "observation-unavailable", "reactivate-failed", "service-repair-failed", "service-repair-unhealthy"].includes(report?.status) || (report?.status === "failed" && (networkFailure || lostTransaction));
       if (reported && retryableReport && result.reason !== "deadline") {
         write(path.join(root, "launcher-status.json"), { schema: 1, at: now(), status: "runner-error", version: candidate.version });
         log("done status=runner-error");

package/bootstrap/recovery-progress.cjs

@@ -27,6 +27,19 @@ function repairProgress(homeDir, now = Date.now) {
   const save = () => atomicFile(file, JSON.stringify({ ...state, updatedAt: now() }));
   if (damaged) save();
   return {
+    // Observation belongs to the same durable repair record as its budget, not
+    // the replaceable human-facing status. A new process/root or an unwatched
+    // interval cannot inherit the old process's failure evidence.
+    observe(identity, { startedAt = now(), gapMs } = {}) {
+      const at = now(), old = state.observation;
+      const continuing = old?.identity === identity && Number.isFinite(old.since) && Number.isFinite(old.at)
+        && old.since <= old.at && old.at <= startedAt && startedAt <= at
+        && startedAt - old.at <= gapMs;
+      const since = continuing ? old.since : startedAt;
+      state.observation = { identity, since, at }; save();
+      return since;
+    },
+    clearObservation() { if (state.observation) { delete state.observation; save(); } },
     count: key => Number(state.attempts[key]) || 0,
     claim(key, limit) {
       if (state.localExhausted || (Number(state.attempts[key]) || 0) >= limit) return false;

package/bootstrap/recovery-readiness.cjs

@@ -42,6 +42,7 @@ async function waitForRecoveryReady({ homeDir = os.homedir(), platform = process
   let firstProgress = null, firstProgressAt = null, progressAdvanced = false;
   // Why the last sample did not count, for the log line a failed proof leaves.
   let block = null, samples = 0, slowestSampleMs = 0;
+  let observationInvalid = false;
   const reset = (key) => { since = null; firstBeat = null; identity = key; probeSeen = false; probeIdentity = null; legacy = false; firstProgress = null; firstProgressAt = null; progressAdvanced = false; };
   const healthSummary = (value) => value ? JSON.stringify({ daemon: value.daemon, pill: value.pill, daemonCount: value.daemonCount, pillCount: value.pillCount, oldDaemon: value.oldDaemon, oldPill: value.oldPill, oldBroker: value.oldBroker }) : "null";
   const probeSummary = (value) => value?.reason || value?.daemon?.reason || value?.pill?.reason || "answer-did-not-match-the-live-processes";
@@ -67,6 +68,10 @@ async function waitForRecoveryReady({ homeDir = os.homedir(), platform = process
     const alive = Boolean(live?.ok) && jobsReady && fresh;
     const probeIdentityNow = probeMatches && !responsive.legacy ? responsive.identity || null : null;
     const suspended = gap < 0 || gap > SAMPLE_GAP_MAX_MS || sampleMs > SAMPLE_MAX_MS;
+    // Incomplete observation is neither proof of a hung application nor a
+    // reason to charge its release. A later successful proof may still win.
+    if (suspended || live?.known === false || (identity !== null && key !== identity)
+      || (platform === "darwin" && jobs.some(job => !job.known))) observationInvalid = true;
     if (suspended || !alive || key !== identity
       || (probeIdentityNow && probeIdentity && probeIdentityNow !== probeIdentity)) {
       block = suspended ? `not-watched-continuously:gap=${gap}ms,sample=${sampleMs}ms`
@@ -105,7 +110,7 @@ async function waitForRecoveryReady({ homeDir = os.homedir(), platform = process
     if (at - started >= timeoutMs) break;
     await sleep(1000);
   }
-  return { ok: false, reason: "runtime-did-not-stay-responsive",
+  return { ok: false, reason: "runtime-did-not-stay-responsive", observationInvalid,
     detail: `${block || "no-sample"}; samples=${samples} slowestSampleMs=${slowestSampleMs} probeSeen=${probeSeen}` };
 }
 module.exports = { waitForRecoveryReady, HEARTBEAT_FRESH_MS, PROBE_TIMEOUT_MS, SAMPLE_GAP_MAX_MS, SAMPLE_MAX_MS };

package/bootstrap/recovery-runner.cjs

@@ -113,8 +113,8 @@ function execute(node, entry, args, { timeoutMs = DEADLINE_MS, spawnImpl = spawn
 
 // A stale daemon heartbeat has two very different causes: a dead or wedged
 // 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.
+// A live process needs sustained failure evidence before disruptive repair.
+// Confirmed absence can use an idempotent service start without that evidence.
 // 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;
@@ -154,6 +154,7 @@ async function recoverLocked({ homeDir = os.homedir(), env = process.env, now =
   sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms)),
   health = require("./runtime-health.cjs").exactRuntimeHealth,
   restart = require("./runtime-health.cjs").restartInstalledRuntimeServices,
+  restorePill = require("./runtime-health.cjs").restoreMissingPill,
   memory = require("./runtime-health.cjs").memoryPressure,
   verifyReady = require("./recovery-readiness.cjs").waitForRecoveryReady,
   policyFactory = require("./recovery-policy.cjs").recoveryPolicy,
@@ -184,6 +185,7 @@ async function recoverLocked({ homeDir = os.homedir(), env = process.env, now =
   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 => {
+    progress.clearObservation();
     const active = observed?.current || read(path.join(root, "runtime", "current.json"));
     const probation = policy.observe(channel, { ...observed, current: active });
     if (!probation.proven) return probation;
@@ -226,7 +228,7 @@ async function recoverLocked({ homeDir = os.homedir(), env = process.env, now =
     return status({ ok: true, status: "deferred-update-in-flight", runtimeHealthy: false, ...extra,
       transaction: { pid: transaction.pid, requestId: transaction.requestId, version: transaction.version } });
   };
-  if (services.status === "deferred-update-owner") return status({ ...services, runtimeHealthy: false });
+  if (["deferred-update-owner", "intentionally-stopped"].includes(services.status)) return status({ ...services, runtimeHealthy: false });
   if (serviceQueryUncertain) return status({ ...services, runtimeHealthy: false });
   if (services.changed || !services.ok) {
     const observed = await ready();
@@ -260,21 +262,44 @@ async function recoverLocked({ homeDir = os.homedir(), env = process.env, now =
     const heartbeatFresh = heartbeat?.at <= now() && now() - heartbeat.at < HEARTBEAT_MS;
     const installedIsDesired = current?.active === true;
     const live = installedIsDesired ? await health(current, { platform }) : null;
+    // Slow OS inspection (including suspension while it runs) is not evidence
+    // of a stalled application. Begin at the completed process observation;
+    // subsequent responsiveness sampling reports its own continuity failures.
+    const observationStartedAt = now();
+    if (live?.known === false) {
+      progress.clearObservation(); policy.interrupt();
+      return status({ ok: false, status: "observation-unavailable", runtimeHealthy: false, lastError: live.reason });
+    }
     // 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 (!installedIsDesired) await discoverDesired();
     if (live && platform === "darwin" && !services.ok) live.ok = false;
     let readiness = null;
     if (installedIsDesired && heartbeatFresh && heartbeat.version === current.version && live.ok) {
       const observed = await ready(current);
       readiness = observed;
       if (observed.ok) {
+        await discoverDesired();
         runtimeResponsive = true;
         runtimeVerified = !observed.legacy;
         if (!desiredVersion || compare(current.version, desiredVersion) >= 0) return proven({ ok: true, status: current.version === desiredVersion || !desiredVersion ? "current" : "ahead", desiredVersion: desiredVersion || current.version, lastSuccessAt: previous?.lastSuccessAt || now() }, observed);
         const probation = rememberReady(observed);
         if (!probation.proven && !observed.legacy) return status({ ok: true, status: "probation", runtimeHealthy: true, runtimeProven: false, desiredVersion, version: current.version, probationRemainingMs: probation.remainingMs });
-      } else { live.ok = false; policy.interrupt(); }
+      } else {
+        live.ok = false; policy.interrupt();
+        if (observed.observationInvalid) {
+          progress.clearObservation();
+          return status({ ok: false, status: "observation-unavailable", runtimeHealthy: false, lastError: observed.detail || observed.reason });
+        }
+      }
+    }
+    const latestPointer = read(path.join(root, "runtime", "current.json"));
+    const latestHeartbeat = read(path.join(root, "recovery", "daemon.json"));
+    if (installedIsDesired && (latestPointer?.packageRoot !== current.packageRoot
+      || latestPointer?.committedAt !== current.committedAt || latestPointer?.active !== true
+      || latestHeartbeat?.pid !== heartbeat?.pid)) {
+      progress.clearObservation();
+      return status({ ok: true, status: "runtime-changed", runtimeHealthy: false });
     }
     const memoryNow = memory();
     // Repair progress for the installed version survives every later status
@@ -283,11 +308,12 @@ async function recoverLocked({ homeDir = os.homedir(), env = process.env, now =
     const repairState = {};
     if (installedIsDesired) {
       repairState.version = current.version;
-      const sameTarget = previous?.version === current.version;
       repairState.restarts = progress.count(`restart:${current.packageRoot || current.version}`);
       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();
+      const incarnation = read(path.join(root, "recovery", "daemon-progress.json"));
+      const identity = JSON.stringify([current.packageRoot, current.version, current.committedAt,
+        heartbeat?.pid, incarnation?.pid === heartbeat?.pid ? incarnation?.startedAt : null]);
+      repairState.staleSince = progress.observe(identity, { startedAt: observationStartedAt, gapMs: cadence * 2 });
     }
     if (installedIsDesired && !(live.ok && heartbeatFresh && heartbeat.version === current.version)) {
       // The code on disk is the code we want; the problem is liveness. Repair in
@@ -298,7 +324,6 @@ async function recoverLocked({ homeDir = os.homedir(), env = process.env, now =
       const base = { desiredVersion: desiredVersion || version, version, staleSince, restarts, discoveryError: discoveryError ? String(discoveryError.message).slice(0, 300) : undefined,
         memoryFreeMB: memoryNow.freeMB };
       log(`installed ${version} not healthy: heartbeatFresh=${heartbeatFresh} daemonAlive=${daemonAlive} health=${JSON.stringify({ daemon: live?.daemon, pill: live?.pill, oldDaemon: live?.oldDaemon, oldPill: live?.oldPill })} readiness=${readiness ? `${readiness.reason || "ok"}${readiness.detail ? ` (${readiness.detail})` : ""}` : "not-attempted"} memoryPressured=${memoryNow.pressured}`);
-      if (daemonAlive && now() - staleSince < STALE_CONFIRM_MS) return status({ ok: true, status: "stale-observed", ...base });
       const deferred = deferToTransaction(base);
       if (deferred) return deferred;
       const repeatedCrash = require("./daemon-progress.cjs").repeatedStartupCrash(current, { homeDir, now: now() });
@@ -308,9 +333,27 @@ async function recoverLocked({ homeDir = os.homedir(), env = process.env, now =
       if (!repeatedCrash && Number.isFinite(committedAt) && committedAt <= now() && now() - committedAt < STARTUP_GRACE_MS) {
         return status({ ok: true, status: "starting", ...base, startupGraceRemainingMs: STARTUP_GRACE_MS - (now() - committedAt) });
       }
+      if (require("./recovery-intent.cjs").stopped(homeDir)) return status({ ok: true, status: "intentionally-stopped", runtimeHealthy: false });
+      const pillMissing = live?.known === true && live.daemonCount === 1 && live.pillCount === 0
+        && !live.oldDaemon && !live.oldPill && !live.oldBroker;
+      // Starting an absent UI does not interrupt daemon work. Reserve the same
+      // bounded restart budget; a runner death cannot grant unlimited attempts.
+      const restartKey = `restart:${current.packageRoot || current.version}`;
+      if (pillMissing && heartbeatFresh && progress.claim(restartKey, MAX_IN_PLACE_RESTARTS)) {
+        const startedAt = now();
+        const outcome = await restorePill(current, { homeDir, platform });
+        if (outcome.deferred) {
+          progress.refund(restartKey); progress.clearObservation();
+          return status({ ok: true, status: outcome.reason, runtimeHealthy: false, ...base });
+        }
+        const observed = outcome.ok ? await ready(current, startedAt) : null;
+        if (observed?.ok) return proven({ ok: true, status: "current", version, desiredVersion: base.desiredVersion, repair: "pill", lastSuccessAt: now() }, observed);
+        progress.fail(outcome.reason || observed?.reason);
+        return status({ ok: false, status: "pill-repair-failed", ...base, lastError: outcome.reason || observed?.detail || observed?.reason });
+      }
+      if (daemonAlive && now() - staleSince < STALE_CONFIRM_MS) return status({ ok: true, status: "stale-observed", ...base });
       const busy = busyDecision(heartbeat, { homeDir, now: now() });
       if (busy) return status({ ok: true, status: busy, ...base });
-      const restartKey = `restart:${current.packageRoot || current.version}`;
       if (repeatedCrash) {
         log(`repeated startup crash; skipping restart/reactivation for ${version}`);
         policy.failure(channel, version, { id: `startup:${current.packageRoot}:${repeatedCrash.fingerprint}`, reason: "repeated-startup-crash" });
@@ -322,7 +365,7 @@ async function recoverLocked({ homeDir = os.homedir(), env = process.env, now =
         try { outcome = await restart(current, { platform, homeDir }); }
         catch (error) { outcome = { ok: false, reason: error.message }; }
         log(`restart ${outcome?.ok ? "ok" : `failed: ${outcome?.reason || "unknown"}`} terminated=${JSON.stringify(outcome?.terminated || [])}`);
-        if (outcome?.reason === "deferred-update-owner" || outcome?.reason === "runtime-changed") {
+        if (outcome?.reason === "deferred-update-owner" || outcome?.reason === "runtime-changed" || outcome?.reason === "intentionally-stopped" || outcome?.reason === "service-process-query-failed") {
           progress.refund(restartKey);
           return status({ ok: true, status: outcome.reason, runtimeHealthy: false, ...base });
         }

package/bootstrap/runtime-health.cjs

@@ -34,7 +34,7 @@ function defaultRun(command, args, options = {}) {
 
 function runtimeProcessQuery(platform) {
   if (platform === "win32") {
-    const script = "$relaySid = [System.Security.Principal.WindowsIdentity]::GetCurrent().User.Value; Get-CimInstance Win32_Process -ErrorAction Stop | Where-Object { $_.CommandLine -match 'node_modules[\\\\/]relay-companion[\\\\/]' } | ForEach-Object { $relayOwner = Invoke-CimMethod -InputObject $_ -MethodName GetOwnerSid -ErrorAction SilentlyContinue; if ($relayOwner.Sid -eq $relaySid) { $_.CommandLine } }";
+    const script = "$ErrorActionPreference = 'Stop'; $relaySid = [System.Security.Principal.WindowsIdentity]::GetCurrent().User.Value; Get-CimInstance Win32_Process -ErrorAction Stop | Where-Object { $_.CommandLine -match 'node_modules[\\\\/]relay-companion[\\\\/]' } | ForEach-Object { $relayOwner = Invoke-CimMethod -InputObject $_ -MethodName GetOwnerSid -ErrorAction Stop; if (-not $relayOwner.Sid) { throw 'service-owner-query-failed' }; if ($relayOwner.Sid -eq $relaySid) { $_.CommandLine } }";
     return { command: "powershell.exe", args: ["-NoProfile", "-NonInteractive", "-Command", script] };
   }
   return { command: "/bin/ps", args: ["-axo", "uid=,command="] };
@@ -63,7 +63,16 @@ function exactRuntimeHealth(target, {
   userId = typeof process.getuid === "function" ? process.getuid() : 0,
 } = {}) {
   const api = platform === "win32" ? path.win32 : path.posix;
-  const lines = withoutWindowsShellWrappers(commands || runtimeProcessCommands(platform, run, userId));
+  let observed = commands;
+  if (observed === null) {
+    const query = runtimeProcessQuery(platform);
+    let result;
+    try { result = run(query.command, query.args); } catch (error) { result = { error }; }
+    // An unavailable observer is not evidence that either service disappeared.
+    if (!commandOk(result)) return { ok: false, known: false, reason: "service-process-query-failed", packageRoot: target.packageRoot };
+    observed = parseRuntimeProcessCommands(result.stdout, platform, userId);
+  }
+  const lines = withoutWindowsShellWrappers(observed);
   const normalize = (value) => (platform === "win32" ? String(value).toLowerCase() : String(value)).replaceAll("\\", "/");
   const daemonNeedle = normalize(target.bin);
   const pillNeedle = normalize(api.join(target.packageRoot, "overlay", "main.cjs"));
@@ -77,7 +86,7 @@ function exactRuntimeHealth(target, {
   const oldBroker = brokers.some((line) => !normalize(line).includes(normalize(target.packageRoot)));
   const oldDaemon = relayDaemons.some((line) => !normalize(line).includes(daemonNeedle));
   const oldPill = relayPills.some((line) => !normalize(line).includes(pillNeedle));
-  return { ok: daemon && pill && !oldDaemon && !oldPill && !oldBroker, daemon, pill, daemonCount, pillCount, brokerCount: brokers.length, oldBroker, oldDaemon, oldPill, packageRoot: target.packageRoot };
+  return { ok: daemon && pill && !oldDaemon && !oldPill && !oldBroker, known: true, daemon, pill, daemonCount, pillCount, brokerCount: brokers.length, oldBroker, oldDaemon, oldPill, packageRoot: target.packageRoot };
 }
 
 function linuxPillStatusPath({ homeDir = os.homedir(), env = process.env } = {}) {
@@ -406,6 +415,65 @@ async function activateWindowsRuntimeServices(target, {
   return { ok: false, reason: "activation-deadline-exceeded", detail: target.packageRoot, health, terminated };
 }
 
+// Use the existing OS service's idempotent start operation. Never spawn a second
+// pill directly, kill a daemon, rewrite registrations, or drain unrelated work.
+async function restoreMissingPill(target, {
+  homeDir = os.homedir(), platform = process.platform, run = defaultRun,
+  own = require("./lifecycle-ownership.cjs").lifecycleOwnership,
+  healthCheck = exactRuntimeHealth, userId = process.getuid?.() ?? 0,
+} = {}) {
+  let lease;
+  const defer = reason => ({ ok: false, deferred: true, reason });
+  const assertTarget = () => {
+    lease.assert();
+    if (require("./recovery-intent.cjs").stopped(homeDir)) throw Error("intentionally-stopped");
+    const current = JSON.parse(fs.readFileSync(path.join(homeDir, ".relay", "runtime", "current.json"), "utf8"));
+    if (!current.active || current.packageRoot !== target.packageRoot || current.committedAt !== target.committedAt) throw Error("runtime-changed");
+  };
+  try {
+    try { lease = own({ homeDir }); } catch { return defer("deferred-update-owner"); }
+    assertTarget();
+    const health = await healthCheck(target, { platform, run });
+    if (health.known === false) return defer("service-process-query-failed");
+    if (health.ok) return { ok: true, changed: false };
+    if (health.daemonCount !== 1 || health.pillCount !== 0 || health.oldDaemon || health.oldPill || health.oldBroker) return defer("runtime-changed");
+    let command, args;
+    const normalize = text => String(text).replace(/&/g, "&").replace(/"/g, '"').replaceAll("\\", "/").toLowerCase();
+    const script = normalize(path.join(target.packageRoot, "overlay", "main.cjs"));
+    if (platform === "win32") {
+      const task = run("schtasks.exe", ["/Query", "/TN", WINDOWS_PILL_TASK, "/XML"]);
+      if (!commandOk(task)) return defer("service-registration-query-failed");
+      const xml = normalize(task.stdout);
+      // Stock Windows tasks normally delegate to a hidden launcher. Follow only
+      // that exact managed file, never an arbitrary path supplied by task text.
+      const launcher = path.join(homeDir, ".relay", "relay-companion-pill.vbs");
+      const targetsCurrent = xml.includes(script) || (xml.includes(normalize(launcher))
+        && normalize(fs.readFileSync(launcher, "utf8")).includes(script));
+      if (!targetsCurrent || !/<MultipleInstancesPolicy>IgnoreNew<\/MultipleInstancesPolicy>/i.test(task.stdout)) return defer("service-target-unverified");
+      command = "schtasks.exe"; args = ["/Run", "/TN", WINDOWS_PILL_TASK];
+    } else if (platform === "linux") {
+      const unit = `${PILL_LABEL}.service`;
+      const service = run("systemctl", ["--user", "show", "--property=ExecStart", "--value", unit]);
+      if (!commandOk(service)) return defer("service-registration-query-failed");
+      if (!normalize(service.stdout).includes(script)) return defer("service-target-unverified");
+      command = "systemctl"; args = ["--user", "start", unit];
+    } else if (platform === "darwin") {
+      const mac = require("./mac-service-recovery.cjs");
+      const record = mac.readRegistration(PILL_LABEL, { homeDir, run });
+      if (record.packageRoot !== target.packageRoot) return defer("runtime-changed");
+      const observed = mac.registration(PILL_LABEL, { run, userId });
+      if (!observed.known || !observed.present) return defer("service-registration-query-failed");
+      command = "/bin/launchctl"; args = ["kickstart", `gui/${userId}/${PILL_LABEL}`];
+    } else return defer("activation-platform-unsupported");
+    // An updater cannot race this generation. Quit may have arrived while the
+    // observer was waiting; check it again at the mutation boundary.
+    assertTarget();
+    const started = run(command, args);
+    return commandOk(started) ? { ok: true, changed: true } : { ok: false, reason: "service-start-failed" };
+  } catch (error) { return defer(error.message); }
+  finally { lease?.release(); }
+}
+
 /** One entry point for "restart what is already installed" on every platform. */
 async function restartInstalledRuntimeServices(target, { platform = process.platform, ...options } = {}) {
   if (!["darwin", "linux", "win32"].includes(platform)) return { ok: false, reason: "activation-platform-unsupported" };
@@ -417,16 +485,26 @@ async function restartInstalledRuntimeServices(target, { platform = process.plat
     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" };
+    if (require("./recovery-intent.cjs").stopped(homeDir)) return { ok: false, reason: "intentionally-stopped" };
+    const live = await (options.healthCheck || exactRuntimeHealth)(target, { platform, run: options.run });
+    if (live.known === false) return { ok: false, reason: "service-process-query-failed" };
     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 });
+    const run = options.run || defaultRun;
+    const guardedRun = (...args) => {
+      lease.assert();
+      if (require("./recovery-intent.cjs").stopped(homeDir)) throw Error("intentionally-stopped");
+      return run(...args);
+    };
+    if (platform === "linux") return await activateLinuxRuntimeServices(target, { platform, ...options, run: guardedRun });
+    if (platform === "win32") return await activateWindowsRuntimeServices(target, { platform, ...options, run: guardedRun });
     return { ok: false, reason: "activation-platform-unsupported" };
   } catch (error) { return { ok: false, reason: error.message }; }
   finally { releaseDrain?.(); lease?.release(); }
 }
 
 module.exports = {
+  restoreMissingPill,
   activateLinuxRuntimeServices,
   activateMacRuntimeServices,
   activateWindowsRuntimeServices,

package/bootstrap/service-recovery.cjs

@@ -14,6 +14,8 @@ async function repairServiceRegistrations({ homeDir = os.homedir(), platform = p
   drain = require("./update-activity.cjs").drainCalls,
   activate,
 } = {}) {
+  const stopped = () => require("./recovery-intent.cjs").stopped(homeDir);
+  if (stopped()) return { ok: true, changed: false, status: "intentionally-stopped" };
   if (platform === "darwin") {
     const observed = await require("./mac-service-recovery.cjs").repairMacServiceRegistrations({ homeDir, platform, run });
     if (observed.ok || observed.blocked) return observed;
@@ -39,14 +41,17 @@ async function repairServiceRegistrations({ homeDir = os.homedir(), platform = p
   try {
     try { lease = own({ homeDir }); }
     catch { return { ok: true, changed: false, status: "deferred-update-owner" }; }
+    if (stopped()) return { ok: true, changed: false, status: "intentionally-stopped" };
     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();
+    if (stopped()) return { ok: true, changed: false, status: "intentionally-stopped" };
     await execute(node, path.join(target.packageRoot, "bin", "relay.js"), ["repair-runtime", "--no-restart"],
       { env: nodeContract.nodeEnvironment(lease.env), timeoutMs: 90_000 });
     lease.assert();
+    if (stopped()) return { ok: true, changed: false, status: "intentionally-stopped" };
     const health = require("./runtime-health.cjs");
     const activateRuntime = activate || (platform === "darwin" ? health.activateMacRuntimeServices
       : platform === "win32" ? health.activateWindowsRuntimeServices : health.activateLinuxRuntimeServices);

package/package.json

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

package/skill/manifest.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
   "name": "relay",
-  "version": "1.1.68",
+  "version": "1.1.69",
   "consentVersion": 2,
-  "baseUrl": "https://sendrelays.com/skills/relay/v1.1.68",
+  "baseUrl": "https://sendrelays.com/skills/relay/v1.1.69",
   "files": [
     {
       "path": "SKILL.md",
@@ -21,7 +21,7 @@
     },
     {
       "path": "scripts/relay-protocol.mjs",
-      "sha256": "bfbc56ecaf202f77002da7eec4a33c5bfc7f3c6574df3dd385766684eb5458a3"
+      "sha256": "833924fb08ed82e67a66c72e5c895deb43f38a5b92dfcc1765c8f05ef87d38e9"
     },
     {
       "path": "scripts/relay-local.mjs",

package/skill/relay/scripts/relay-protocol.mjs

@@ -746,6 +746,17 @@ function validateDirectArguments(args, schema, label = "arguments") {
   if (schema.type === "integer" && (args < (schema.minimum ?? -Infinity) || args > (schema.maximum ?? Infinity))) throw new Error(`Invalid ${label}.`);
 }
 
+// Match MCP's presentation projection; raw HTTP requests keep their API shape.
+function withoutRedundantPresentation(value) {
+  if (Array.isArray(value)) return value.map(withoutRedundantPresentation);
+  if (!value || typeof value !== "object") return value;
+  return Object.fromEntries(Object.entries(value)
+    .filter(([key]) => key !== "threadTitle" && key !== "replyToRelayId"
+      && !(key === "threadIds" && typeof value.chatId === "string")
+      && !(key === "preview" && typeof value.relayId === "string" && typeof value.forHuman === "string" && value.forHuman.length > 0))
+    .map(([key, child]) => [key, withoutRedundantPresentation(child)]));
+}
+
 async function directToolCommand(command, body, config) {
   transport = "https";
   // Explicit HTTPS verifies the independent credential and account. It never
@@ -819,7 +830,7 @@ async function directToolCommand(command, body, config) {
       value = await request("POST", "/v1/share-links", await prepareSendBody(draft));
     }
   }
-  return { content: [{ type: "text", text: JSON.stringify(value) }], isError: false };
+  return { content: [{ type: "text", text: JSON.stringify(withoutRedundantPresentation(value)) }], isError: false };
 }
 
 async function main(argv = process.argv.slice(2)) {