@remodex/rmx 1.0.3 → 1.0.5

package/src/update/desktop-release.ts

@@ -1,1620 +0,0 @@
-/**
- * Secure updater for the Remodex desktop shell.
- *
- * This module is intentionally separate from the npm self-updater in `job.ts`.
- * Desktop releases are native installers published in the Remodex release
- * repository; treating them as npm packages would either install the wrong
- * payload or replace a running runtime in place.  The tray and dashboard share
- * the small, owner-only state record written here.
- */
-import { createHash } from "node:crypto";
-import {
-  chmodSync,
-  closeSync,
-  createReadStream,
-  existsSync,
-  lstatSync,
-  mkdirSync,
-  openSync,
-  readFileSync,
-  renameSync,
-  statSync,
-  truncateSync,
-  unlinkSync,
-  writeSync,
-} from "node:fs";
-import { spawn } from "node:child_process";
-import { basename, join } from "node:path";
-import { arch as hostArch, platform as hostPlatform } from "node:process";
-import { atomicWriteFile, getConfigDir } from "../config";
-import { isProcessAlive } from "../lib/process-control";
-
-export const DESKTOP_RELEASE_REPOSITORY = "ESCANOR-001/remodex-releases";
-export const DESKTOP_MANIFEST_URL =
-  "https://raw.githubusercontent.com/ESCANOR-001/remodex-releases/main/latest.json";
-export const DESKTOP_MANIFEST_FALLBACK_URL =
-  "https://github.com/ESCANOR-001/remodex-releases/releases/latest/download/latest.json";
-export const DESKTOP_PREVIEW_MANIFEST_URL =
-  "https://raw.githubusercontent.com/ESCANOR-001/remodex-releases/main/preview.json";
-
-const DESKTOP_UPDATE_STATE_FILENAME = "desktop-update.json";
-const DESKTOP_UPDATE_DIRNAME = "desktop-updates";
-const DESKTOP_AUTO_UPDATE_SCHEDULE_FILENAME = "desktop-update-schedule.json";
-const MANIFEST_MAX_BYTES = 256 * 1024;
-const RELEASE_NOTES_MAX_BYTES = 32 * 1024;
-const MAX_ARTIFACT_BYTES = 4 * 1024 * 1024 * 1024;
-const FETCH_TIMEOUT_MS = 20_000;
-const DOWNLOAD_TIMEOUT_MS = 30 * 60_000;
-const INSTALL_TIMEOUT_MS = 15 * 60_000;
-const MAX_REDIRECTS = 4;
-const ACTIVE_JOB_STALE_MS = 10 * 60_000;
-export const DESKTOP_AUTO_UPDATE_INTERVAL_MS = 24 * 60 * 60_000;
-
-export type DesktopReleaseChannel = "latest" | "preview";
-export type DesktopPlatform = "linux" | "windows" | "darwin";
-export type DesktopArtifactFormat = "deb" | "rpm" | "exe" | "msi" | "dmg" | "pkg";
-export type DesktopUpdatePhase =
-  | "idle"
-  | "checking"
-  | "available"
-  | "downloading"
-  | "verifying"
-  | "ready"
-  | "installing"
-  | "up-to-date"
-  | "succeeded"
-  | "failed";
-
-export type DesktopUpdateReason =
-  | "already_latest"
-  | "latest_unavailable"
-  | "invalid_manifest"
-  | "unsupported_platform"
-  | "desktop_required"
-  | "signature_unsupported"
-  | "download_failed"
-  | "checksum_mismatch"
-  | "install_failed";
-
-export interface DesktopReleaseArtifact {
-  format: DesktopArtifactFormat;
-  url: string;
-  size: number;
-  sha256: string;
-  name?: string;
-  signature?: {
-    algorithm: "ed25519";
-    value: string;
-    keyId: string;
-    required?: boolean;
-  };
-}
-
-export interface DesktopReleaseManifest {
-  schemaVersion: 1;
-  version: string;
-  channel: DesktopReleaseChannel;
-  releaseNotes: string;
-  releaseNotesUrl?: string;
-  artifacts: Record<string, DesktopReleaseArtifact>;
-}
-
-export interface DesktopTarget {
-  platform: DesktopPlatform | null;
-  arch: string;
-  key: string | null;
-}
-
-export interface DesktopUpdateCheckResult {
-  currentVersion: string;
-  latestVersion: string | null;
-  channel: DesktopReleaseChannel;
-  platform: DesktopPlatform | null;
-  arch: string;
-  targetKey: string | null;
-  artifact: {
-    format: DesktopArtifactFormat;
-    name: string;
-    size: number;
-    sha256: string;
-    signatureRequired: boolean;
-  } | null;
-  updateAvailable: boolean;
-  canDownload: boolean;
-  canInstall: boolean;
-  desktopShell: boolean;
-  releaseNotes: string;
-  releaseNotesUrl: string | null;
-  manifestUrl: string | null;
-  checkedAt: string;
-  reason?: DesktopUpdateReason;
-}
-
-export interface DesktopUpdateState {
-  schemaVersion: 1;
-  id: string;
-  phase: DesktopUpdatePhase;
-  currentVersion: string;
-  latestVersion: string | null;
-  channel: DesktopReleaseChannel;
-  platform: DesktopPlatform | null;
-  arch: string;
-  targetKey: string | null;
-  artifactFormat: DesktopArtifactFormat | null;
-  artifactName: string | null;
-  artifactSha256: string | null;
-  totalBytes: number | null;
-  downloadedBytes: number;
-  progress: number | null;
-  verification: "pending" | "sha256" | "signature" | "failed";
-  releaseNotes: string;
-  releaseNotesUrl: string | null;
-  manifestUrl: string | null;
-  startedAt: string;
-  updatedAt: string;
-  checkedAt: string | null;
-  pid?: number;
-  errorCode?: DesktopUpdateReason;
-  restartRequired?: boolean;
-}
-
-interface DesktopAutoUpdateSchedule {
-  schemaVersion: 1;
-  lastAttemptAt: string;
-  lastSuccessfulCheckAt?: string;
-  lastNotifiedVersion?: string;
-}
-
-export interface AutomaticDesktopUpdateCheckResult {
-  checked: boolean;
-  updateAvailable: boolean;
-  latestVersion: string | null;
-  notify: boolean;
-  outcome: "checked" | "not_due" | "busy" | "state_changed" | "failed";
-  reason?: DesktopUpdateReason;
-}
-
-export interface DesktopReleaseIo {
-  fetchFn?: typeof fetch;
-  now?: () => number;
-  platform?: NodeJS.Platform;
-  arch?: string;
-  currentVersion?: () => string;
-  desktopShell?: () => boolean;
-  installer?: (format: DesktopArtifactFormat, path: string) => Promise<InstallResult>;
-  isAlive?: (pid: number) => boolean;
-  spawnWorker?: (id: string, install: boolean) => { pid?: number; unref(): void };
-}
-
-export interface InstallResult {
-  ok: boolean;
-  restartRequired?: boolean;
-  code?: DesktopUpdateReason;
-}
-
-export interface StartDesktopUpdateOptions {
-  /** Check and download when false; launch the verified installer when true. */
-  install?: boolean;
-  /**
-   * Bind a dashboard install click to the exact ready record it displayed.
-   * The tray intentionally omits this because its action is derived from the
-   * latest shared state at click time.
-   */
-  expectedReady?: {
-    id: string;
-    channel: DesktopReleaseChannel;
-  };
-}
-
-export class DesktopUpdateError extends Error {
-  constructor(
-    message: string,
-    readonly status = 400,
-    readonly code: DesktopUpdateReason = "download_failed",
-  ) {
-    super(message);
-  }
-}
-
-const FORMAT_EXTENSIONS: Record<DesktopArtifactFormat, string> = {
-  deb: ".deb",
-  rpm: ".rpm",
-  exe: ".exe",
-  msi: ".msi",
-  dmg: ".dmg",
-  pkg: ".pkg",
-};
-
-const ALLOWED_FORMATS = new Set<DesktopArtifactFormat>(Object.keys(FORMAT_EXTENSIONS) as DesktopArtifactFormat[]);
-
-function updateStatePath(): string {
-  return join(getConfigDir(), DESKTOP_UPDATE_STATE_FILENAME);
-}
-
-export function desktopUpdateStatePathForTests(): string {
-  return updateStatePath();
-}
-
-function autoUpdateSchedulePath(): string {
-  return join(getConfigDir(), DESKTOP_AUTO_UPDATE_SCHEDULE_FILENAME);
-}
-
-export function desktopAutoUpdateSchedulePathForTests(): string {
-  return autoUpdateSchedulePath();
-}
-
-export function desktopUpdateDirectory(): string {
-  return join(getConfigDir(), DESKTOP_UPDATE_DIRNAME);
-}
-
-function ensureUpdateDirectory(): void {
-  const dir = desktopUpdateDirectory();
-  if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 });
-  const stat = lstatSync(dir);
-  if (!stat.isDirectory() || stat.isSymbolicLink()) {
-    throw new DesktopUpdateError("The desktop update directory is unavailable.", 500, "download_failed");
-  }
-  try { chmodSync(dir, 0o700); } catch { /* platform may ignore chmod */ }
-}
-
-function isVersion(value: unknown): value is string {
-  return typeof value === "string"
-    && value.length <= 64
-    && /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/.test(value);
-}
-
-function isSafeReleaseUrl(value: unknown): value is string {
-  if (typeof value !== "string" || value.length > 2048) return false;
-  try {
-    const url = new URL(value);
-    if (url.protocol !== "https:") return false;
-    const host = url.hostname.toLowerCase();
-    return host === "github.com"
-      || host === "raw.githubusercontent.com"
-      || host === "objects.githubusercontent.com"
-      || host === "githubusercontent.com"
-      || host.endsWith(".githubusercontent.com");
-  } catch {
-    return false;
-  }
-}
-
-const RELEASE_REPOSITORY_PATH = "/escanor-001/remodex-releases";
-
-/**
- * Manifest fields are expected to point at this repository, while a completed
- * GitHub download commonly redirects to an `*.githubusercontent.com` object
- * host whose URL no longer carries the repository path. Keep those two cases
- * explicit instead of treating every GitHub repository as a Remodex release.
- */
-function isTrustedReleaseRepositoryUrl(value: unknown): value is string {
-  if (!isSafeReleaseUrl(value)) return false;
-  const url = new URL(value);
-  const host = url.hostname.toLowerCase();
-  if (host === "github.com" || host === "raw.githubusercontent.com") {
-    const path = url.pathname.replace(/\/+$/, "").toLowerCase();
-    return path === RELEASE_REPOSITORY_PATH || path.startsWith(`${RELEASE_REPOSITORY_PATH}/`);
-  }
-  return host === "objects.githubusercontent.com"
-    || host === "githubusercontent.com"
-    || host.endsWith(".githubusercontent.com");
-}
-
-function safeArtifactName(value: unknown, url: string, format: DesktopArtifactFormat): string {
-  const candidate = typeof value === "string" && value.trim() ? value.trim() : basename(new URL(url).pathname);
-  if (
-    candidate.length === 0
-    || candidate.length > 180
-    || candidate === "."
-    || candidate === ".."
-    || candidate.includes("/")
-    || candidate.includes("\\")
-    || candidate.includes("\0")
-  ) {
-    return `Remodex${FORMAT_EXTENSIONS[format]}`;
-  }
-  return candidate;
-}
-
-function parseArtifact(value: unknown): DesktopReleaseArtifact | null {
-  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
-  const raw = value as Record<string, unknown>;
-  if (!isTrustedReleaseRepositoryUrl(raw.url)) return null;
-  if (typeof raw.format !== "string" || !ALLOWED_FORMATS.has(raw.format as DesktopArtifactFormat)) return null;
-  const format = raw.format as DesktopArtifactFormat;
-  if (
-    typeof raw.size !== "number"
-    || !Number.isSafeInteger(raw.size)
-    || raw.size <= 0
-    || raw.size > MAX_ARTIFACT_BYTES
-    || typeof raw.sha256 !== "string"
-    || !/^[a-fA-F0-9]{64}$/.test(raw.sha256)
-  ) return null;
-  let signature: DesktopReleaseArtifact["signature"];
-  if (raw.signature !== undefined) {
-    if (!raw.signature || typeof raw.signature !== "object" || Array.isArray(raw.signature)) return null;
-    const candidate = raw.signature as Record<string, unknown>;
-    if (
-      candidate.algorithm !== "ed25519"
-      || typeof candidate.value !== "string"
-      || candidate.value.length < 16
-      || candidate.value.length > 512
-      || typeof candidate.keyId !== "string"
-      || candidate.keyId.length < 1
-      || candidate.keyId.length > 128
-      || (candidate.required !== undefined && typeof candidate.required !== "boolean")
-    ) return null;
-    signature = {
-      algorithm: "ed25519",
-      value: candidate.value,
-      keyId: candidate.keyId,
-      ...(candidate.required === true ? { required: true } : {}),
-    };
-  }
-  return {
-    format,
-    url: raw.url,
-    size: raw.size,
-    sha256: raw.sha256.toLowerCase(),
-    ...(typeof raw.name === "string" ? { name: safeArtifactName(raw.name, raw.url, format) } : {}),
-    ...(signature ? { signature } : {}),
-  };
-}
-
-function artifactFormatMatchesTarget(key: string, format: DesktopArtifactFormat): boolean {
-  if (key.startsWith("linux-")) return format === "deb" || format === "rpm";
-  if (key.startsWith("windows-")) return format === "exe" || format === "msi";
-  if (key.startsWith("darwin-")) return format === "dmg" || format === "pkg";
-  return false;
-}
-
-export function validateDesktopReleaseManifest(value: unknown): DesktopReleaseManifest {
-  if (!value || typeof value !== "object" || Array.isArray(value)) {
-    throw new DesktopUpdateError("The release manifest is invalid.", 502, "invalid_manifest");
-  }
-  const raw = value as Record<string, unknown>;
-  if (raw.schemaVersion !== 1 || !isVersion(raw.version)) {
-    throw new DesktopUpdateError("The release manifest is invalid.", 502, "invalid_manifest");
-  }
-  if (raw.channel !== "latest" && raw.channel !== "preview") {
-    throw new DesktopUpdateError("The release manifest is invalid.", 502, "invalid_manifest");
-  }
-  if (typeof raw.releaseNotes !== "string" || Buffer.byteLength(raw.releaseNotes, "utf8") > RELEASE_NOTES_MAX_BYTES) {
-    throw new DesktopUpdateError("The release manifest is invalid.", 502, "invalid_manifest");
-  }
-  if (raw.releaseNotesUrl !== undefined && !isTrustedReleaseRepositoryUrl(raw.releaseNotesUrl)) {
-    throw new DesktopUpdateError("The release manifest is invalid.", 502, "invalid_manifest");
-  }
-  if (!raw.artifacts || typeof raw.artifacts !== "object" || Array.isArray(raw.artifacts)) {
-    throw new DesktopUpdateError("The release manifest is invalid.", 502, "invalid_manifest");
-  }
-  const artifacts: Record<string, DesktopReleaseArtifact> = {};
-  for (const [key, candidate] of Object.entries(raw.artifacts)) {
-    if (!/^(?:linux|windows|darwin)-(?:x64|arm64|ia32)$/.test(key)) continue;
-    const parsed = parseArtifact(candidate);
-    if (!parsed || !artifactFormatMatchesTarget(key, parsed.format)) {
-      throw new DesktopUpdateError("The release manifest is invalid.", 502, "invalid_manifest");
-    }
-    artifacts[key] = parsed;
-  }
-  if (Object.keys(artifacts).length === 0) {
-    throw new DesktopUpdateError("The release manifest has no supported artifacts.", 502, "invalid_manifest");
-  }
-  return {
-    schemaVersion: 1,
-    version: raw.version,
-    channel: raw.channel,
-    releaseNotes: raw.releaseNotes,
-    ...(typeof raw.releaseNotesUrl === "string" ? { releaseNotesUrl: raw.releaseNotesUrl } : {}),
-    artifacts,
-  };
-}
-
-function normalizePlatform(value: NodeJS.Platform): DesktopPlatform | null {
-  if (value === "linux") return "linux";
-  if (value === "win32") return "windows";
-  if (value === "darwin") return "darwin";
-  return null;
-}
-
-function normalizeArch(value: string): string {
-  if (value === "x64" || value === "amd64") return "x64";
-  if (value === "arm64" || value === "aarch64") return "arm64";
-  if (value === "ia32" || value === "x86") return "ia32";
-  return value;
-}
-
-export function desktopTarget(
-  platform: NodeJS.Platform = hostPlatform,
-  arch: string = hostArch,
-): DesktopTarget {
-  const normalizedPlatform = normalizePlatform(platform);
-  const normalizedArch = normalizeArch(arch);
-  return {
-    platform: normalizedPlatform,
-    arch: normalizedArch,
-    key: normalizedPlatform ? `${normalizedPlatform}-${normalizedArch}` : null,
-  };
-}
-
-type ParsedVersion = {
-  major: number;
-  minor: number;
-  patch: number;
-  pre: string[];
-};
-
-function parseVersion(value: string): ParsedVersion | null {
-  if (!isVersion(value)) return null;
-  const withoutBuild = value.split("+", 1)[0]!;
-  const separator = withoutBuild.indexOf("-");
-  const core = separator === -1 ? withoutBuild : withoutBuild.slice(0, separator);
-  const pre = separator === -1 ? "" : withoutBuild.slice(separator + 1);
-  const [major, minor, patch] = core.split(".").map(Number);
-  return { major, minor, patch, pre: pre ? pre.split(".") : [] };
-}
-
-function compareVersions(a: string, b: string): number {
-  const left = parseVersion(a);
-  const right = parseVersion(b);
-  if (!left || !right) return 0;
-  for (const key of ["major", "minor", "patch"] as const) {
-    if (left[key] !== right[key]) return left[key] > right[key] ? 1 : -1;
-  }
-  if (left.pre.length === 0 && right.pre.length > 0) return 1;
-  if (left.pre.length > 0 && right.pre.length === 0) return -1;
-  for (let index = 0; index < Math.max(left.pre.length, right.pre.length); index += 1) {
-    const l = left.pre[index];
-    const r = right.pre[index];
-    if (l === undefined) return -1;
-    if (r === undefined) return 1;
-    if (l === r) continue;
-    const lNum = /^\d+$/.test(l) ? Number(l) : null;
-    const rNum = /^\d+$/.test(r) ? Number(r) : null;
-    if (lNum !== null && rNum !== null) return lNum > rNum ? 1 : -1;
-    if (lNum !== null) return -1;
-    if (rNum !== null) return 1;
-    return l > r ? 1 : -1;
-  }
-  return 0;
-}
-
-export function isNewerDesktopVersion(latest: string, current: string, channel: DesktopReleaseChannel): boolean {
-  if (channel === "latest" && latest.includes("-")) return false;
-  return compareVersions(latest, current) > 0;
-}
-
-function defaultCurrentVersion(): string {
-  try {
-    const value = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8")) as { version?: unknown };
-    return typeof value.version === "string" && isVersion(value.version) ? value.version : "0.0.0";
-  } catch {
-    return "0.0.0";
-  }
-}
-
-function defaultDesktopShell(): boolean {
-  // `OCX_DESKTOP_UPDATE` identifies the short-lived worker, not the desktop
-  // shell itself.  A service/browser request must not gain installer
-  // privileges merely because it spawned that worker.
-  return process.env.OCX_DESKTOP === "1";
-}
-
-function manifestUrls(channel: DesktopReleaseChannel): readonly string[] {
-  return channel === "preview"
-    ? [DESKTOP_PREVIEW_MANIFEST_URL]
-    : [DESKTOP_MANIFEST_URL, DESKTOP_MANIFEST_FALLBACK_URL];
-}
-
-function allowedManifestUrl(value: string): boolean {
-  return value === DESKTOP_MANIFEST_URL
-    || value === DESKTOP_MANIFEST_FALLBACK_URL
-    || value === DESKTOP_PREVIEW_MANIFEST_URL;
-}
-
-async function fetchBoundedText(
-  url: string,
-  fetchFn: typeof fetch,
-  maxBytes: number,
-): Promise<{ text: string; finalUrl: string }> {
-  let current = url;
-  for (let redirect = 0; redirect <= MAX_REDIRECTS; redirect += 1) {
-    if (!allowedManifestUrl(current)) {
-      // Redirects are permitted only to the trusted GitHub content hosts and
-      // never to an arbitrary host.
-      if (!isTrustedReleaseRepositoryUrl(current)) throw new DesktopUpdateError("The release URL is not trusted.", 502, "invalid_manifest");
-    }
-    const response = await fetchFn(current, {
-      redirect: "manual",
-      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
-      headers: { accept: "application/json" },
-    });
-    if (response.status >= 300 && response.status < 400) {
-      const location = response.headers.get("location");
-      if (!location || redirect === MAX_REDIRECTS) {
-        throw new DesktopUpdateError("The release manifest could not be fetched.", 502, "latest_unavailable");
-      }
-      const next = new URL(location, current).toString();
-      if (!isTrustedReleaseRepositoryUrl(next)) {
-        throw new DesktopUpdateError("The release URL is not trusted.", 502, "invalid_manifest");
-      }
-      current = next;
-      continue;
-    }
-    if (!response.ok) {
-      throw new DesktopUpdateError("The release manifest could not be fetched.", response.status === 404 ? 404 : 502, "latest_unavailable");
-    }
-    const length = Number(response.headers.get("content-length") ?? "0");
-    if (Number.isFinite(length) && length > maxBytes) {
-      throw new DesktopUpdateError("The release manifest is too large.", 502, "invalid_manifest");
-    }
-    // Do not call `arrayBuffer()` for an untrusted response before enforcing the
-    // bound: a server can omit Content-Length and otherwise make a malformed
-    // manifest consume an arbitrary amount of memory. Read at most maxBytes
-    // from the stream and cancel as soon as the limit is crossed.
-    const bytes = await readResponseBytesBounded(response, maxBytes);
-    return {
-      text: new TextDecoder().decode(bytes),
-      finalUrl: response.url && isTrustedReleaseRepositoryUrl(response.url) ? response.url : current,
-    };
-  }
-  throw new DesktopUpdateError("The release manifest could not be fetched.", 502, "latest_unavailable");
-}
-
-async function readResponseBytesBounded(response: Response, maxBytes: number): Promise<Uint8Array> {
-  if (!response.body) {
-    const bytes = new Uint8Array(await response.arrayBuffer());
-    if (bytes.byteLength > maxBytes) {
-      throw new DesktopUpdateError("The release manifest is too large.", 502, "invalid_manifest");
-    }
-    return bytes;
-  }
-
-  const reader = response.body.getReader();
-  const chunks: Uint8Array[] = [];
-  let total = 0;
-  let complete = false;
-  try {
-    for (;;) {
-      const next = await reader.read();
-      if (next.done) {
-        complete = true;
-        break;
-      }
-      total += next.value.byteLength;
-      if (total > maxBytes) {
-        throw new DesktopUpdateError("The release manifest is too large.", 502, "invalid_manifest");
-      }
-      chunks.push(next.value);
-    }
-  } finally {
-    if (!complete) {
-      try { await reader.cancel(); } catch { /* response is already closed */ }
-    }
-  }
-
-  const bytes = new Uint8Array(total);
-  let offset = 0;
-  for (const chunk of chunks) {
-    bytes.set(chunk, offset);
-    offset += chunk.byteLength;
-  }
-  return bytes;
-}
-
-async function fetchManifest(
-  channel: DesktopReleaseChannel,
-  fetchFn: typeof fetch,
-): Promise<{ manifest: DesktopReleaseManifest; url: string }> {
-  let lastError: DesktopUpdateError | null = null;
-  for (const url of manifestUrls(channel)) {
-    try {
-      const fetched = await fetchBoundedText(url, fetchFn, MANIFEST_MAX_BYTES);
-      let parsed: unknown;
-      try {
-        parsed = JSON.parse(fetched.text);
-      } catch {
-        throw new DesktopUpdateError("The release manifest is invalid.", 502, "invalid_manifest");
-      }
-      const manifest = validateDesktopReleaseManifest(parsed);
-      return { manifest, url: fetched.finalUrl };
-    } catch (error) {
-      lastError = error instanceof DesktopUpdateError
-        ? error
-        : new DesktopUpdateError("The release manifest could not be fetched.", 502, "latest_unavailable");
-      if (lastError.code === "invalid_manifest") throw lastError;
-    }
-  }
-  throw lastError ?? new DesktopUpdateError("The release manifest could not be fetched.", 502, "latest_unavailable");
-}
-
-function artifactName(artifact: DesktopReleaseArtifact): string {
-  return safeArtifactName(artifact.name, artifact.url, artifact.format);
-}
-
-export async function checkDesktopReleaseUpdate(
-  requestedChannel: DesktopReleaseChannel = "latest",
-  io: DesktopReleaseIo = {},
-): Promise<DesktopUpdateCheckResult> {
-  const now = io.now ?? Date.now;
-  const currentVersion = io.currentVersion?.() ?? defaultCurrentVersion();
-  const target = desktopTarget(io.platform ?? hostPlatform, io.arch ?? hostArch);
-  const desktopShell = io.desktopShell?.() ?? defaultDesktopShell();
-  const base = {
-    currentVersion,
-    latestVersion: null,
-    channel: requestedChannel,
-    platform: target.platform,
-    arch: target.arch,
-    targetKey: target.key,
-    artifact: null,
-    updateAvailable: false,
-    canDownload: false,
-    canInstall: false,
-    desktopShell,
-    releaseNotes: "",
-    releaseNotesUrl: null,
-    manifestUrl: null,
-    checkedAt: new Date(now()).toISOString(),
-  } satisfies DesktopUpdateCheckResult;
-
-  let fetched: { manifest: DesktopReleaseManifest; url: string };
-  try {
-    fetched = await fetchManifest(requestedChannel, io.fetchFn ?? fetch);
-  } catch (error) {
-    const code = error instanceof DesktopUpdateError ? error.code : "latest_unavailable";
-    return { ...base, reason: code };
-  }
-  return desktopReleaseCheckFromManifest(requestedChannel, fetched.manifest, fetched.url, {
-    ...io,
-    currentVersion: () => currentVersion,
-    desktopShell: () => desktopShell,
-    platform: io.platform ?? hostPlatform,
-    arch: io.arch ?? hostArch,
-    now,
-  }, base);
-}
-
-function desktopReleaseCheckFromManifest(
-  requestedChannel: DesktopReleaseChannel,
-  manifest: DesktopReleaseManifest,
-  url: string,
-  io: DesktopReleaseIo,
-  baseOverride?: DesktopUpdateCheckResult,
-): DesktopUpdateCheckResult {
-  const now = io.now ?? Date.now;
-  const currentVersion = io.currentVersion?.() ?? defaultCurrentVersion();
-  const target = desktopTarget(io.platform ?? hostPlatform, io.arch ?? hostArch);
-  const desktopShell = io.desktopShell?.() ?? defaultDesktopShell();
-  const base = baseOverride ?? {
-    currentVersion,
-    latestVersion: null,
-    channel: requestedChannel,
-    platform: target.platform,
-    arch: target.arch,
-    targetKey: target.key,
-    artifact: null,
-    updateAvailable: false,
-    canDownload: false,
-    canInstall: false,
-    desktopShell,
-    releaseNotes: "",
-    releaseNotesUrl: null,
-    manifestUrl: null,
-    checkedAt: new Date(now()).toISOString(),
-  };
-  if (manifest.channel !== requestedChannel) {
-    return { ...base, latestVersion: manifest.version, manifestUrl: url, releaseNotes: manifest.releaseNotes, releaseNotesUrl: manifest.releaseNotesUrl ?? null, reason: "latest_unavailable" };
-  }
-  const selected = target.key ? manifest.artifacts[target.key] : undefined;
-  const updateAvailable = isNewerDesktopVersion(manifest.version, currentVersion, requestedChannel);
-  // A missing target artifact matters only when there is a newer release to
-  // install. If the installed version already matches the manifest, report
-  // "up to date" rather than making a supported machine look unsupported.
-  if (!updateAvailable) {
-    return {
-      ...base,
-      latestVersion: manifest.version,
-      updateAvailable: false,
-      manifestUrl: url,
-      releaseNotes: manifest.releaseNotes,
-      releaseNotesUrl: manifest.releaseNotesUrl ?? null,
-      reason: "already_latest",
-    };
-  }
-  if (!selected) {
-    return {
-      ...base,
-      latestVersion: manifest.version,
-      updateAvailable,
-      manifestUrl: url,
-      releaseNotes: manifest.releaseNotes,
-      releaseNotesUrl: manifest.releaseNotesUrl ?? null,
-      reason: "unsupported_platform",
-    };
-  }
-  const artifact = {
-    format: selected.format,
-    name: artifactName(selected),
-    size: selected.size,
-    sha256: selected.sha256,
-    signatureRequired: selected.signature?.required === true,
-  };
-  return {
-    ...base,
-    latestVersion: manifest.version,
-    updateAvailable,
-    canDownload: updateAvailable,
-    canInstall: updateAvailable && desktopShell,
-    artifact,
-    manifestUrl: url,
-    releaseNotes: manifest.releaseNotes,
-    releaseNotesUrl: manifest.releaseNotesUrl ?? null,
-    ...(updateAvailable ? {} : { reason: "already_latest" }),
-  };
-}
-
-function safeStateString(value: unknown, max = 2048): string {
-  return typeof value === "string" && value.length <= max && !/[\0\r\n]/.test(value) ? value : "";
-}
-
-function safeReleaseNotes(value: unknown): string {
-  return typeof value === "string"
-    && !value.includes("\0")
-    && Buffer.byteLength(value, "utf8") <= RELEASE_NOTES_MAX_BYTES
-    ? value
-    : "";
-}
-
-function sanitizeState(state: DesktopUpdateState): DesktopUpdateState {
-  const phase = [
-    "idle",
-    "checking",
-    "available",
-    "downloading",
-    "verifying",
-    "ready",
-    "installing",
-    "up-to-date",
-    "succeeded",
-    "failed",
-  ].includes(state.phase) ? state.phase : "failed";
-  const platform = state.platform === "linux" || state.platform === "windows" || state.platform === "darwin"
-    ? state.platform
-    : null;
-  const artifactFormat = state.artifactFormat && ALLOWED_FORMATS.has(state.artifactFormat)
-    ? state.artifactFormat
-    : null;
-  const verification = ["pending", "sha256", "signature", "failed"].includes(state.verification)
-    ? state.verification
-    : "failed";
-  const errorCode = state.errorCode && [
-    "already_latest",
-    "latest_unavailable",
-    "invalid_manifest",
-    "unsupported_platform",
-    "desktop_required",
-    "signature_unsupported",
-    "download_failed",
-    "checksum_mismatch",
-    "install_failed",
-  ].includes(state.errorCode) ? state.errorCode : undefined;
-  return {
-    schemaVersion: 1,
-    id: safeStateString(state.id, 96),
-    phase,
-    currentVersion: isVersion(state.currentVersion) ? state.currentVersion : "0.0.0",
-    latestVersion: state.latestVersion && isVersion(state.latestVersion) ? state.latestVersion : null,
-    channel: state.channel === "preview" ? "preview" : "latest",
-    platform,
-    arch: safeStateString(state.arch, 32),
-    targetKey: state.targetKey ? safeStateString(state.targetKey, 64) : null,
-    artifactFormat,
-    artifactName: state.artifactName ? safeStateString(state.artifactName, 180) : null,
-    artifactSha256: typeof state.artifactSha256 === "string" && /^[a-f0-9]{64}$/i.test(state.artifactSha256)
-      ? state.artifactSha256.toLowerCase()
-      : null,
-    totalBytes: typeof state.totalBytes === "number" && Number.isSafeInteger(state.totalBytes) && state.totalBytes > 0 ? state.totalBytes : null,
-    downloadedBytes: Number.isSafeInteger(state.downloadedBytes) && state.downloadedBytes >= 0 ? state.downloadedBytes : 0,
-    progress: typeof state.progress === "number" && Number.isFinite(state.progress) ? Math.max(0, Math.min(100, state.progress)) : null,
-    verification,
-    releaseNotes: safeReleaseNotes(state.releaseNotes),
-    releaseNotesUrl: state.releaseNotesUrl && isSafeReleaseUrl(state.releaseNotesUrl) ? state.releaseNotesUrl : null,
-    manifestUrl: state.manifestUrl && isSafeReleaseUrl(state.manifestUrl) ? state.manifestUrl : null,
-    startedAt: safeStateString(state.startedAt, 64),
-    updatedAt: safeStateString(state.updatedAt, 64),
-    checkedAt: state.checkedAt ? safeStateString(state.checkedAt, 64) : null,
-    ...(typeof state.pid === "number" && Number.isSafeInteger(state.pid) && state.pid > 0 ? { pid: state.pid } : {}),
-    ...(errorCode ? { errorCode } : {}),
-    ...(state.restartRequired ? { restartRequired: true } : {}),
-  };
-}
-
-function writeState(state: DesktopUpdateState): DesktopUpdateState {
-  const path = updateStatePath();
-  if (existsSync(path)) {
-    const stat = lstatSync(path);
-    if (!stat.isFile() || stat.isSymbolicLink()) {
-      throw new DesktopUpdateError("The desktop update state file is unavailable.", 500, "download_failed");
-    }
-  }
-  const sanitized = sanitizeState(state);
-  atomicWriteFile(path, `${JSON.stringify(sanitized, null, 2)}\n`);
-  return sanitized;
-}
-
-function recoverStaleDesktopUpdateState(
-  state: DesktopUpdateState,
-  now = Date.now(),
-): DesktopUpdateState {
-  if (!["checking", "downloading", "verifying", "installing"].includes(state.phase)) return state;
-
-  const updatedAt = Date.parse(state.updatedAt);
-  const stale = typeof state.pid === "number"
-    ? !isProcessAlive(state.pid)
-    : !Number.isFinite(updatedAt) || now < updatedAt || now - updatedAt >= ACTIVE_JOB_STALE_MS;
-  if (!stale) return state;
-
-  const recovered: DesktopUpdateState = {
-    ...state,
-    phase: "failed",
-    verification: "failed",
-    errorCode: state.phase === "installing" ? "install_failed" : "download_failed",
-    pid: undefined,
-    updatedAt: new Date(now).toISOString(),
-  };
-  try {
-    return writeState(recovered);
-  } catch {
-    // Keep the read useful even if a transient config/state write error prevents
-    // persisting recovery. The next write-capable operation can retry it.
-    return sanitizeState(recovered);
-  }
-}
-
-export function readDesktopUpdateState(now = Date.now()): DesktopUpdateState | null {
-  try {
-    const path = updateStatePath();
-    const stat = lstatSync(path);
-    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > MANIFEST_MAX_BYTES) return null;
-    const parsed = JSON.parse(readFileSync(path, "utf8")) as Partial<DesktopUpdateState>;
-    if (!parsed || parsed.schemaVersion !== 1 || typeof parsed.id !== "string" || typeof parsed.phase !== "string") return null;
-    if (!/^desktop-\d+-[a-z0-9]{1,32}$/.test(parsed.id)) return null;
-    if (!["idle", "checking", "available", "downloading", "verifying", "ready", "installing", "up-to-date", "succeeded", "failed"].includes(parsed.phase)) return null;
-    if (parsed.channel !== "latest" && parsed.channel !== "preview") return null;
-    return recoverStaleDesktopUpdateState(sanitizeState(parsed as DesktopUpdateState), now);
-  } catch {
-    return null;
-  }
-}
-
-function patchState(id: string, patch: Partial<DesktopUpdateState>, now = Date.now()): DesktopUpdateState | null {
-  const current = readDesktopUpdateState(now);
-  if (!current || current.id !== id) return null;
-  return writeState({ ...current, ...patch, updatedAt: new Date(now).toISOString() });
-}
-
-function newJobId(): string {
-  return `desktop-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
-}
-
-function artifactPath(id: string, format: DesktopArtifactFormat): string {
-  ensureUpdateDirectory();
-  return join(desktopUpdateDirectory(), `${id}${FORMAT_EXTENSIONS[format]}`);
-}
-
-function artifactTempPath(id: string, format: DesktopArtifactFormat): string {
-  ensureUpdateDirectory();
-  return join(desktopUpdateDirectory(), `${id}${FORMAT_EXTENSIONS[format]}.part`);
-}
-
-function removeFileSafely(path: string): void {
-  try {
-    const stat = lstatSync(path);
-    if (!stat.isFile() || stat.isSymbolicLink()) return;
-    truncateSync(path, 0);
-    unlinkSync(path);
-  } catch {
-    /* best effort cleanup */
-  }
-}
-
-function removeDesktopUpdateArtifacts(state: DesktopUpdateState | null): void {
-  if (!state?.artifactFormat) return;
-  removeFileSafely(artifactPath(state.id, state.artifactFormat));
-  removeFileSafely(artifactTempPath(state.id, state.artifactFormat));
-}
-
-function writeChunk(fd: number, chunk: Uint8Array): void {
-  let offset = 0;
-  while (offset < chunk.byteLength) {
-    const written = writeSync(fd, chunk, offset, chunk.byteLength - offset);
-    if (written <= 0) throw new Error("download write failed");
-    offset += written;
-  }
-}
-
-async function fetchArtifactResponse(url: string, fetchFn: typeof fetch): Promise<Response> {
-  let current = url;
-  for (let redirect = 0; redirect <= MAX_REDIRECTS; redirect += 1) {
-    if (!isTrustedReleaseRepositoryUrl(current)) throw new DesktopUpdateError("The artifact URL is not trusted.", 502, "invalid_manifest");
-    const response = await fetchFn(current, {
-      redirect: "manual",
-      signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS),
-    });
-    if (response.status >= 300 && response.status < 400) {
-      const location = response.headers.get("location");
-      if (!location || redirect === MAX_REDIRECTS) throw new DesktopUpdateError("The artifact could not be downloaded.", 502, "download_failed");
-      const next = new URL(location, current).toString();
-      if (!isTrustedReleaseRepositoryUrl(next)) throw new DesktopUpdateError("The artifact URL is not trusted.", 502, "invalid_manifest");
-      current = next;
-      continue;
-    }
-    if (!response.ok) throw new DesktopUpdateError("The artifact could not be downloaded.", 502, "download_failed");
-    if (response.url && !isTrustedReleaseRepositoryUrl(response.url)) throw new DesktopUpdateError("The artifact URL is not trusted.", 502, "invalid_manifest");
-    return response;
-  }
-  throw new DesktopUpdateError("The artifact could not be downloaded.", 502, "download_failed");
-}
-
-async function downloadArtifact(
-  id: string,
-  artifact: DesktopReleaseArtifact,
-  onProgress: (downloaded: number) => void,
-  onVerifying: () => void,
-  fetchFn: typeof fetch,
-): Promise<string> {
-  const destination = artifactPath(id, artifact.format);
-  const temporary = artifactTempPath(id, artifact.format);
-  removeFileSafely(temporary);
-  removeFileSafely(destination);
-  const response = await fetchArtifactResponse(artifact.url, fetchFn);
-  const contentLength = Number(response.headers.get("content-length") ?? "0");
-  if (Number.isSafeInteger(contentLength) && contentLength > 0 && contentLength > artifact.size) {
-    throw new DesktopUpdateError("The downloaded artifact is larger than expected.", 502, "download_failed");
-  }
-  if (!response.body) throw new DesktopUpdateError("The artifact response was empty.", 502, "download_failed");
-  const reader = response.body.getReader();
-  const hash = createHash("sha256");
-  let fd: number | null = null;
-  let downloaded = 0;
-  let streamError: unknown;
-  try {
-    fd = openSync(temporary, "wx", 0o600);
-    for (;;) {
-      const next = await reader.read();
-      if (next.done) break;
-      const chunk = next.value;
-      downloaded += chunk.byteLength;
-      if (downloaded > artifact.size || downloaded > MAX_ARTIFACT_BYTES) {
-        throw new DesktopUpdateError("The downloaded artifact is larger than expected.", 502, "download_failed");
-      }
-      hash.update(chunk);
-      writeChunk(fd, chunk);
-      onProgress(downloaded);
-    }
-  } catch (error) {
-    streamError = error;
-  } finally {
-    try { await reader.cancel(); } catch { /* stream already closed */ }
-    if (fd !== null) closeSync(fd);
-  }
-  if (streamError !== undefined) {
-    removeFileSafely(temporary);
-    throw streamError;
-  }
-  if (downloaded !== artifact.size) {
-    removeFileSafely(temporary);
-    throw new DesktopUpdateError("The downloaded artifact size did not match the manifest.", 502, "download_failed");
-  }
-  onVerifying();
-  if (hash.digest("hex").toLowerCase() !== artifact.sha256) {
-    removeFileSafely(temporary);
-    throw new DesktopUpdateError("The downloaded artifact checksum did not match.", 502, "checksum_mismatch");
-  }
-  try {
-    renameSync(temporary, destination);
-  } catch (error) {
-    removeFileSafely(temporary);
-    throw error;
-  }
-  const finalStat = lstatSync(destination);
-  if (!finalStat.isFile() || finalStat.isSymbolicLink() || finalStat.size !== artifact.size) {
-    removeFileSafely(destination);
-    throw new DesktopUpdateError("The downloaded artifact could not be verified.", 502, "checksum_mismatch");
-  }
-  return destination;
-}
-
-async function verifyDownloadedArtifact(
-  path: string,
-  expectedSize: number,
-  expectedSha256: string,
-): Promise<boolean> {
-  let before;
-  try {
-    before = lstatSync(path);
-  } catch {
-    return false;
-  }
-  if (!before.isFile() || before.isSymbolicLink() || before.size !== expectedSize) return false;
-
-  const hash = createHash("sha256");
-  let bytes = 0;
-  try {
-    for await (const chunk of createReadStream(path)) {
-      const buffer = chunk as Buffer;
-      bytes += buffer.byteLength;
-      if (bytes > expectedSize) return false;
-      hash.update(buffer);
-    }
-  } catch {
-    return false;
-  }
-  if (bytes !== expectedSize || hash.digest("hex").toLowerCase() !== expectedSha256.toLowerCase()) {
-    return false;
-  }
-  try {
-    const after = lstatSync(path);
-    return after.isFile()
-      && !after.isSymbolicLink()
-      && after.size === before.size
-      && after.mtimeMs === before.mtimeMs;
-  } catch {
-    return false;
-  }
-}
-
-function trustedExecutable(candidates: string[]): string | null {
-  return candidates.find(candidate => existsSync(candidate) && (() => {
-    try {
-      return statSync(candidate).isFile();
-    } catch {
-      return false;
-    }
-  })()) ?? null;
-}
-
-async function spawnAndWait(command: string, args: string[]): Promise<boolean> {
-  return await new Promise(resolve => {
-    let settled = false;
-    const child = spawn(command, args, { stdio: "ignore", windowsHide: true });
-    const finish = (ok: boolean) => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timer);
-      resolve(ok);
-    };
-    const timer = setTimeout(() => {
-      try { child.kill(); } catch { /* process already exited */ }
-      finish(false);
-    }, INSTALL_TIMEOUT_MS);
-    timer.unref?.();
-    child.once("error", () => finish(false));
-    child.once("exit", code => finish(code === 0));
-  });
-}
-
-async function defaultInstaller(format: DesktopArtifactFormat, path: string): Promise<InstallResult> {
-  // The generated path is inside the owner-only update directory and the
-  // command/arguments are fixed by the validated artifact format.
-  if (process.platform === "linux") {
-    if (format === "deb") {
-      const pkexec = trustedExecutable(["/usr/bin/pkexec", "/bin/pkexec"]);
-      const dpkg = trustedExecutable(["/usr/bin/dpkg", "/bin/dpkg"]);
-      if (!pkexec || !dpkg) return { ok: false, code: "install_failed" };
-      const ok = await spawnAndWait(pkexec, [dpkg, "--install", path]);
-      return ok ? { ok: true, restartRequired: true } : { ok: false, code: "install_failed" };
-    }
-    if (format === "rpm") {
-      const pkexec = trustedExecutable(["/usr/bin/pkexec", "/bin/pkexec"]);
-      const rpm = trustedExecutable(["/usr/bin/rpm", "/bin/rpm"]);
-      if (!pkexec || !rpm) return { ok: false, code: "install_failed" };
-      const ok = await spawnAndWait(pkexec, [rpm, "--upgrade", path]);
-      return ok ? { ok: true, restartRequired: true } : { ok: false, code: "install_failed" };
-    }
-    return { ok: false, code: "desktop_required" };
-  }
-  if (process.platform === "win32") {
-    if (format === "msi") {
-      const msiexec = trustedExecutable([
-        `${process.env.SystemRoot ?? "C:\\Windows"}\\System32\\msiexec.exe`,
-      ]);
-      if (!msiexec) return { ok: false, code: "desktop_required" };
-      const ok = await spawnAndWait(msiexec, ["/i", path]);
-      return ok ? { ok: true, restartRequired: true } : { ok: false, code: "install_failed" };
-    }
-    if (format === "exe") {
-      const child = spawn(path, [], { detached: true, stdio: "ignore", windowsHide: false });
-      child.unref();
-      return { ok: true, restartRequired: true };
-    }
-    return { ok: false, code: "desktop_required" };
-  }
-  if (process.platform === "darwin") {
-    const open = trustedExecutable(["/usr/bin/open"]);
-    if (!open) return { ok: false, code: "desktop_required" };
-    if (format === "pkg") {
-      const ok = await spawnAndWait(open, [path]);
-      return ok ? { ok: true, restartRequired: true } : { ok: false, code: "install_failed" };
-    }
-    if (format === "dmg") {
-      const child = spawn(open, [path], { detached: true, stdio: "ignore" });
-      child.unref();
-      return { ok: true, restartRequired: true };
-    }
-  }
-  return { ok: false, code: "desktop_required" };
-}
-
-function initialState(id: string, channel: DesktopReleaseChannel, now: number, io: DesktopReleaseIo): DesktopUpdateState {
-  const target = desktopTarget(io.platform ?? hostPlatform, io.arch ?? hostArch);
-  return {
-    schemaVersion: 1,
-    id,
-    phase: "checking",
-    currentVersion: io.currentVersion?.() ?? defaultCurrentVersion(),
-    latestVersion: null,
-    channel,
-    platform: target.platform,
-    arch: target.arch,
-    targetKey: target.key,
-    artifactFormat: null,
-    artifactName: null,
-    artifactSha256: null,
-    totalBytes: null,
-    downloadedBytes: 0,
-    progress: null,
-    verification: "pending",
-    releaseNotes: "",
-    releaseNotesUrl: null,
-    manifestUrl: null,
-    startedAt: new Date(now).toISOString(),
-    updatedAt: new Date(now).toISOString(),
-    checkedAt: null,
-  };
-}
-
-function safeIsoTimestamp(value: unknown): string | null {
-  if (typeof value !== "string" || value.length > 64 || /[\0\r\n]/.test(value)) return null;
-  const parsed = Date.parse(value);
-  return Number.isFinite(parsed) ? new Date(parsed).toISOString() : null;
-}
-
-function readAutoUpdateSchedule(): DesktopAutoUpdateSchedule | null {
-  try {
-    const path = autoUpdateSchedulePath();
-    const stat = lstatSync(path);
-    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > MANIFEST_MAX_BYTES) return null;
-    const parsed = JSON.parse(readFileSync(path, "utf8")) as Partial<DesktopAutoUpdateSchedule>;
-    const lastAttemptAt = safeIsoTimestamp(parsed.lastAttemptAt);
-    if (parsed.schemaVersion !== 1 || !lastAttemptAt) return null;
-    const lastSuccessfulCheckAt = safeIsoTimestamp(parsed.lastSuccessfulCheckAt);
-    const lastNotifiedVersion = isVersion(parsed.lastNotifiedVersion)
-      ? parsed.lastNotifiedVersion
-      : undefined;
-    return {
-      schemaVersion: 1,
-      lastAttemptAt,
-      ...(lastSuccessfulCheckAt ? { lastSuccessfulCheckAt } : {}),
-      ...(lastNotifiedVersion ? { lastNotifiedVersion } : {}),
-    };
-  } catch {
-    return null;
-  }
-}
-
-function writeAutoUpdateSchedule(schedule: DesktopAutoUpdateSchedule): DesktopAutoUpdateSchedule {
-  const sanitized: DesktopAutoUpdateSchedule = {
-    schemaVersion: 1,
-    lastAttemptAt: safeIsoTimestamp(schedule.lastAttemptAt) ?? new Date().toISOString(),
-    ...(safeIsoTimestamp(schedule.lastSuccessfulCheckAt)
-      ? { lastSuccessfulCheckAt: safeIsoTimestamp(schedule.lastSuccessfulCheckAt)! }
-      : {}),
-    ...(isVersion(schedule.lastNotifiedVersion)
-      ? { lastNotifiedVersion: schedule.lastNotifiedVersion }
-      : {}),
-  };
-  atomicWriteFile(autoUpdateSchedulePath(), `${JSON.stringify(sanitized, null, 2)}\n`);
-  return sanitized;
-}
-
-function mostRecentAutomaticCheckAt(
-  schedule: DesktopAutoUpdateSchedule | null,
-  state: DesktopUpdateState | null,
-): number | null {
-  const candidates = [
-    schedule?.lastAttemptAt,
-    state?.checkedAt,
-  ]
-    .map(value => typeof value === "string" ? Date.parse(value) : Number.NaN)
-    .filter(value => Number.isFinite(value));
-  return candidates.length > 0 ? Math.max(...candidates) : null;
-}
-
-function automaticDesktopUpdateDue(
-  schedule: DesktopAutoUpdateSchedule | null,
-  state: DesktopUpdateState | null,
-  now: number,
-): boolean {
-  const last = mostRecentAutomaticCheckAt(schedule, state);
-  if (last === null) return true;
-  if (now <= last) return false;
-  return now - last >= DESKTOP_AUTO_UPDATE_INTERVAL_MS;
-}
-
-function desktopUpdateStateFingerprint(state: DesktopUpdateState | null): string {
-  return state ? `${state.id}\0${state.phase}\0${state.updatedAt}` : "";
-}
-
-function automaticStateFromCheck(
-  check: DesktopUpdateCheckResult,
-  now: number,
-): DesktopUpdateState {
-  const available = check.updateAvailable && check.canDownload && check.artifact !== null;
-  return {
-    schemaVersion: 1,
-    id: newJobId(),
-    phase: available ? "available" : "up-to-date",
-    currentVersion: check.currentVersion,
-    latestVersion: check.latestVersion,
-    channel: check.channel,
-    platform: check.platform,
-    arch: check.arch,
-    targetKey: check.targetKey,
-    artifactFormat: available ? check.artifact?.format ?? null : null,
-    artifactName: available ? check.artifact?.name ?? null : null,
-    artifactSha256: available ? check.artifact?.sha256 ?? null : null,
-    totalBytes: available ? check.artifact?.size ?? null : null,
-    downloadedBytes: 0,
-    progress: null,
-    verification: "pending",
-    releaseNotes: check.releaseNotes,
-    releaseNotesUrl: check.releaseNotesUrl,
-    manifestUrl: check.manifestUrl,
-    startedAt: check.checkedAt,
-    updatedAt: new Date(now).toISOString(),
-    checkedAt: check.checkedAt,
-  };
-}
-
-/**
- * Background desktop check used by the native shell.
- *
- * It never downloads or installs an artifact. A successful supported update is
- * persisted as `available`, allowing the existing tray/dashboard action to
- * download it only after the user clicks. Attempts are persisted before the
- * network request so restarting the application cannot turn startup checks
- * into an accidental polling loop.
- */
-export async function runAutomaticDesktopUpdateCheck(
-  channel: DesktopReleaseChannel = "latest",
-  io: DesktopReleaseIo = {},
-): Promise<AutomaticDesktopUpdateCheckResult> {
-  const now = io.now ?? Date.now;
-  const startedAt = now();
-  const previous = readDesktopUpdateState(startedAt);
-  if (activeState(previous, io) || previous?.phase === "ready") {
-    return {
-      checked: false,
-      updateAvailable: previous?.latestVersion !== null && previous?.phase === "ready",
-      latestVersion: previous?.latestVersion ?? null,
-      notify: false,
-      outcome: "busy",
-    };
-  }
-
-  const schedule = readAutoUpdateSchedule();
-  if (!automaticDesktopUpdateDue(schedule, previous, startedAt)) {
-    return {
-      checked: false,
-      updateAvailable: previous?.phase === "available",
-      latestVersion: previous?.latestVersion ?? null,
-      notify: false,
-      outcome: "not_due",
-    };
-  }
-
-  const attemptAt = new Date(startedAt).toISOString();
-  writeAutoUpdateSchedule({
-    schemaVersion: 1,
-    lastAttemptAt: attemptAt,
-    ...(schedule?.lastSuccessfulCheckAt
-      ? { lastSuccessfulCheckAt: schedule.lastSuccessfulCheckAt }
-      : {}),
-    ...(schedule?.lastNotifiedVersion
-      ? { lastNotifiedVersion: schedule.lastNotifiedVersion }
-      : {}),
-  });
-
-  const baseline = desktopUpdateStateFingerprint(previous);
-  const check = await checkDesktopReleaseUpdate(channel, {
-    ...io,
-    desktopShell: () => false,
-  });
-  const supportedUpdate = check.updateAvailable && check.canDownload && check.artifact !== null;
-  const successful = check.reason === "already_latest" || supportedUpdate;
-  if (!successful) {
-    return {
-      checked: true,
-      updateAvailable: false,
-      latestVersion: check.latestVersion,
-      notify: false,
-      outcome: "failed",
-      ...(check.reason ? { reason: check.reason } : {}),
-    };
-  }
-
-  const current = readDesktopUpdateState(now());
-  if (desktopUpdateStateFingerprint(current) !== baseline) {
-    writeAutoUpdateSchedule({
-      schemaVersion: 1,
-      lastAttemptAt: attemptAt,
-      lastSuccessfulCheckAt: check.checkedAt,
-      ...(schedule?.lastNotifiedVersion
-        ? { lastNotifiedVersion: schedule.lastNotifiedVersion }
-        : {}),
-    });
-    return {
-      checked: true,
-      updateAvailable: supportedUpdate,
-      latestVersion: check.latestVersion,
-      notify: false,
-      outcome: "state_changed",
-    };
-  }
-
-  removeDesktopUpdateArtifacts(previous);
-  writeState(automaticStateFromCheck(check, now()));
-  const notify = supportedUpdate
-    && check.latestVersion !== null
-    && schedule?.lastNotifiedVersion !== check.latestVersion;
-  writeAutoUpdateSchedule({
-    schemaVersion: 1,
-    lastAttemptAt: attemptAt,
-    lastSuccessfulCheckAt: check.checkedAt,
-    ...(notify && check.latestVersion
-      ? { lastNotifiedVersion: check.latestVersion }
-      : schedule?.lastNotifiedVersion
-        ? { lastNotifiedVersion: schedule.lastNotifiedVersion }
-        : {}),
-  });
-  return {
-    checked: true,
-    updateAvailable: supportedUpdate,
-    latestVersion: check.latestVersion,
-    notify,
-    outcome: "checked",
-  };
-}
-
-function activeState(state: DesktopUpdateState | null, io: DesktopReleaseIo): boolean {
-  if (!state || !["checking", "downloading", "verifying", "installing"].includes(state.phase)) return false;
-  if (typeof state.pid !== "number") {
-    const updatedAt = Date.parse(state.updatedAt);
-    const now = (io.now ?? Date.now)();
-    return Number.isFinite(updatedAt)
-      && now >= updatedAt
-      && now - updatedAt < ACTIVE_JOB_STALE_MS;
-  }
-  return (io.isAlive ?? isProcessAlive)(state.pid);
-}
-
-export function spawnDesktopUpdateWorker(id: string, install: boolean): { pid?: number; unref(): void } {
-  const entry = process.argv[1];
-  if (!entry) throw new DesktopUpdateError("The desktop update worker could not start.", 500, "download_failed");
-  const child = spawn(process.execPath, [entry, "__desktop-update-worker", id, install ? "install" : "download"], {
-    detached: true,
-    stdio: "ignore",
-    windowsHide: true,
-    env: { ...process.env, OCX_DESKTOP_UPDATE: "1" },
-  });
-  return child;
-}
-
-export function startDesktopUpdateJob(
-  channel: DesktopReleaseChannel = "latest",
-  options: StartDesktopUpdateOptions = {},
-  io: DesktopReleaseIo = {},
-): DesktopUpdateState {
-  const install = options.install === true;
-  const now = io.now ?? Date.now;
-  const desktopShell = io.desktopShell?.() ?? defaultDesktopShell();
-  if (install && !desktopShell) {
-    throw new DesktopUpdateError("The desktop application is required to install this release.", 409, "desktop_required");
-  }
-  const previous = readDesktopUpdateState(now());
-  if (activeState(previous, io)) {
-    throw new DesktopUpdateError("A desktop update is already in progress.", 409, "download_failed");
-  }
-  if (install && options.expectedReady) {
-    const expected = options.expectedReady;
-    if (
-      channel !== expected.channel
-      || !/^desktop-\d+-[a-z0-9]{1,32}$/.test(expected.id)
-      || previous?.phase !== "ready"
-      || previous.id !== expected.id
-      || previous.channel !== expected.channel
-    ) {
-      throw new DesktopUpdateError(
-        "The selected desktop update is no longer ready. Check for updates again.",
-        409,
-        "download_failed",
-      );
-    }
-  }
-  if (previous?.phase === "ready") {
-    // A download-only request follows a fresh manifest check in the dashboard
-    // and management API. Never reuse a ready artifact for that path: the
-    // manifest may have advanced while the persisted artifact is still ready.
-    // The tray's second click uses `install: true`, so it continues to install
-    // the exact verified record instead of downloading it again.
-    if (
-      install
-      && (
-        !previous.artifactFormat
-        || !previous.artifactSha256
-        || !previous.totalBytes
-      )
-    ) {
-      throw new DesktopUpdateError("The verified desktop update is incomplete. Download it again.", 409, "download_failed");
-    }
-    if (install) {
-      const installing = patchState(previous.id, {
-        phase: "installing",
-        progress: 100,
-        verification: "sha256",
-        errorCode: undefined,
-        pid: process.pid,
-      }, now()) ?? previous;
-      try {
-        const worker = (io.spawnWorker ?? spawnDesktopUpdateWorker)(previous.id, true);
-        if (typeof worker.pid === "number" && worker.pid > 0) patchState(previous.id, { pid: worker.pid }, now());
-        worker.unref();
-      } catch {
-        patchState(previous.id, { phase: "failed", errorCode: "install_failed" }, now());
-        throw new DesktopUpdateError("The desktop update worker could not start.", 500, "install_failed");
-      }
-      return readDesktopUpdateState(now()) ?? installing;
-    }
-  }
-  if (install) {
-    throw new DesktopUpdateError("Download and verify the desktop update before installing it.", 409, "download_failed");
-  }
-  const startedAt = now();
-  const id = newJobId();
-  const job = writeState(initialState(id, channel, startedAt, io));
-  removeDesktopUpdateArtifacts(previous);
-  try {
-    const worker = (io.spawnWorker ?? spawnDesktopUpdateWorker)(id, false);
-    if (typeof worker.pid === "number" && worker.pid > 0) patchState(id, { pid: worker.pid }, now());
-    worker.unref();
-  } catch {
-    patchState(id, { phase: "failed", errorCode: "download_failed" }, now());
-    throw new DesktopUpdateError("The desktop update worker could not start.", 500, "download_failed");
-  }
-  return readDesktopUpdateState(now()) ?? job;
-}
-
-export async function runDesktopUpdateWorker(
-  id: string,
-  install: boolean,
-  io: DesktopReleaseIo = {},
-): Promise<void> {
-  let state = readDesktopUpdateState();
-  if (!state || state.id !== id) return;
-  try {
-    if (install) {
-      if (
-        state.phase !== "installing"
-        || !state.artifactFormat
-        || !state.artifactSha256
-        || !state.totalBytes
-      ) {
-        patchState(id, { phase: "failed", errorCode: "install_failed" });
-        return;
-      }
-      const destination = artifactPath(id, state.artifactFormat);
-      if (!await verifyDownloadedArtifact(destination, state.totalBytes, state.artifactSha256)) {
-        removeFileSafely(destination);
-        patchState(id, {
-          phase: "failed",
-          verification: "failed",
-          errorCode: "checksum_mismatch",
-        });
-        return;
-      }
-      const result = await (io.installer ?? defaultInstaller)(state.artifactFormat, destination);
-      if (!result.ok) {
-        patchState(id, {
-          phase: "failed",
-          verification: "failed",
-          errorCode: result.code ?? "install_failed",
-        });
-        return;
-      }
-      patchState(id, {
-        phase: "succeeded",
-        verification: "sha256",
-        restartRequired: result.restartRequired !== false,
-        errorCode: undefined,
-      });
-      return;
-    }
-
-    const fetched = await fetchManifest(state.channel, io.fetchFn ?? fetch);
-    const check = desktopReleaseCheckFromManifest(state.channel, fetched.manifest, fetched.url, io);
-    state = patchState(id, {
-      currentVersion: check.currentVersion,
-      latestVersion: check.latestVersion,
-      platform: check.platform,
-      arch: check.arch,
-      targetKey: check.targetKey,
-      artifactFormat: check.artifact?.format ?? null,
-      artifactName: check.artifact?.name ?? null,
-      artifactSha256: check.artifact?.sha256 ?? null,
-      totalBytes: check.artifact?.size ?? null,
-      releaseNotes: check.releaseNotes,
-      releaseNotesUrl: check.releaseNotesUrl,
-      manifestUrl: check.manifestUrl,
-      checkedAt: check.checkedAt,
-      phase: check.reason === "already_latest" ? "up-to-date" : check.updateAvailable ? "downloading" : "failed",
-      errorCode: check.reason && check.reason !== "already_latest" ? check.reason : undefined,
-    }) ?? state;
-    if (!check.updateAvailable || !check.artifact || !check.canDownload) {
-      if (check.reason === "already_latest") patchState(id, { phase: "up-to-date", errorCode: undefined });
-      else patchState(id, { phase: "failed", errorCode: check.reason ?? "latest_unavailable" });
-      return;
-    }
-    const manifestArtifact = fetched.manifest.artifacts[check.targetKey ?? ""];
-    if (!manifestArtifact) {
-      patchState(id, { phase: "failed", errorCode: "unsupported_platform" });
-      return;
-    }
-    const destination = await downloadArtifact(
-      id,
-      manifestArtifact,
-      downloaded => {
-        const total = manifestArtifact.size;
-        patchState(id, {
-          phase: "downloading",
-          downloadedBytes: downloaded,
-          progress: total > 0 ? Math.min(100, (downloaded / total) * 100) : null,
-        });
-      },
-      () => {
-        patchState(id, {
-          phase: "verifying",
-          downloadedBytes: manifestArtifact.size,
-          progress: 100,
-          verification: "pending",
-        });
-      },
-      io.fetchFn ?? fetch,
-    );
-    if (manifestArtifact.signature?.required === true) {
-      removeFileSafely(destination);
-      patchState(id, { phase: "failed", verification: "failed", errorCode: "signature_unsupported" });
-      return;
-    }
-    if (!install) {
-      patchState(id, { phase: "ready", verification: "sha256", errorCode: undefined });
-      return;
-    }
-  } catch (error) {
-    const code = error instanceof DesktopUpdateError ? error.code : "download_failed";
-    patchState(id, {
-      phase: "failed",
-      verification: code === "checksum_mismatch" || code === "signature_unsupported" ? "failed" : state.verification,
-      errorCode: code,
-    });
-  }
-}
-
-/**
- * Decide what a tray click should do.  The first click checks/downloads; a
- * second click after verification hands the artifact to the platform installer.
- */
-export function desktopUpdateInstallAction(state: DesktopUpdateState | null): boolean {
-  return state?.phase === "ready";
-}