Skip to content

The agent that grows with you

30.3 KB
Raw Blame
import {
  execFile,
  type ExecFileOptions,
  execFileSync,
  spawn,
  type SpawnOptions,
  spawnSync,
  type SpawnSyncOptions,
  type SpawnSyncReturns
} from 'node:child_process'
import { existsSync, realpathSync, statSync } from 'node:fs'
import os from 'node:os'
import path from 'node:path'

/** Historical layouts still matter when uninstalling or migrating a source install. */
export function resolveVenvDir(updateRoot: string): string {
  for (const name of ['venv', '.venv']) {
    const candidate: string = path.join(updateRoot, name)

    try {
      if (statSync(candidate).isDirectory()) {
        return candidate
      }
    } catch {
      // Try the other supported layout, then retain the legacy diagnostic path.
    }
  }

  return path.join(updateRoot, 'venv')
}

import { platformDefaultHermesHome } from './data-paths'
import { hiddenWindowsChildOptions } from './windows-child-options'

/** Exact installation identity; PATH may refer to another checkout. */
export function resolveInstallationLauncher(
  updateRoot: string,
  isWindows: boolean = process.platform === 'win32',
  hermesHome: string = process.env.HERMES_HOME ?? ''
): string | null {
  const staged: string | null = stagedInstallationLauncher(updateRoot, isWindows)

  if (staged) {
    return staged
  }

  for (const candidate of historicalLauncherCandidates(updateRoot, isWindows, hermesHome)) {
    if (launcherTargetsInstallation(candidate, updateRoot)) {
      return candidate
    }
  }

  return legacyInstallationLauncher(updateRoot, isWindows)
}

/**
 * resolveInstallationLauncher for callers on Electron's main thread that run
 * repeatedly (the About/version refresh): the historical user-bin rung proves
 * identity with the launcher's own `--version`, which may take seconds, so it
 * runs asynchronously here and never stalls the event loop.
 */
export async function resolveInstallationLauncherAsync(
  updateRoot: string,
  isWindows: boolean = process.platform === 'win32',
  hermesHome: string = process.env.HERMES_HOME ?? ''
): Promise<string | null> {
  const staged: string | null = stagedInstallationLauncher(updateRoot, isWindows)

  if (staged) {
    return staged
  }

  const realRoot: string | null = realpathOrNull(updateRoot)

  for (const candidate of realRoot ? historicalLauncherCandidates(updateRoot, isWindows, hermesHome) : []) {
    if ((await launcherInstallDirectoryAsync(candidate, updateRoot)) === realRoot) {
      return candidate
    }
  }

  return legacyInstallationLauncher(updateRoot, isWindows)
}

function stagedInstallationLauncher(updateRoot: string, isWindows: boolean): string | null {
  const names: string[] = isWindows ? ['hermes.exe', 'hermes.cmd'] : ['hermes']

  return names.map(name => path.join(updateRoot, '.hermes', 'bin', name)).find(stagedFileExists) ?? null
}

// Earlier PM installers published only to user-bin. Trust that historical
// launcher only after its existing version surface proves exact source identity.
function historicalLauncherCandidates(updateRoot: string, isWindows: boolean, hermesHome: string): string[] {
  if (!stagedFileExists(path.join(updateRoot, 'hermes_cli', '_launchers.py'))) {
    return []
  }

  return userBinLaunchers(isWindows, hermesHome, isWindows ? [path.join(path.dirname(updateRoot), 'bin')] : [])
}

// An old shim is a migration rung, never a damaged PM install fallback.
function legacyInstallationLauncher(updateRoot: string, isWindows: boolean): string | null {
  if (existsSync(path.join(updateRoot, 'pm'))) {
    return null
  }

  const legacy: string = path.join(updateRoot, 'venv', isWindows ? 'Scripts' : 'bin', isWindows ? 'hermes.exe' : 'hermes')

  return stagedFileExists(legacy) ? legacy : null
}

function realpathOrNull(target: string): string | null {
  try {
    return realpathSync(target)
  } catch {
    return null
  }
}

// cmd.exe re-parses its command line, so a launcher path carrying any of
// these would change the command instead of naming a file.
const CMD_UNSAFE_PATH: RegExp = /["%&|<>^\r\n]/

/** Published user-bin launchers, at fixed locations: a GUI launch's PATH may omit them. */
function userBinLaunchers(isWindows: boolean, hermesHome: string, extraDirs: string[] = []): string[] {
  const names: string[] = isWindows ? ['hermes.exe', 'hermes.cmd'] : ['hermes']
  const defaultHome: string = platformDefaultHermesHome(os.homedir(), process.env, isWindows ? 'win32' : 'linux')

  const dirs: string[] = isWindows
    ? [path.join(hermesHome || defaultHome, 'bin'), path.join(defaultHome, 'bin'), ...extraDirs]
    : [path.join(os.homedir(), '.local', 'bin'), path.join(hermesHome || defaultHome, 'bin'), ...extraDirs]

  return [...new Set(dirs)]
    .flatMap((dir: string): string[] => names.map((name: string): string => path.join(dir, name)))
    .filter(stagedFileExists)
}

/**
 * A source install outside the canonical root (install.sh --dir, a
 * setup-hermes.sh clone) is reachable only through the user-bin launcher it
 * published. Return the install directory that launcher reports, when it is a
 * Hermes source tree; the caller still resolves and probes it by root.
 */
export function userLauncherInstallRoot(
  isWindows: boolean = process.platform === 'win32',
  hermesHome: string = process.env.HERMES_HOME ?? ''
): { launcher: string; root: string } | null {
  for (const launcher of userBinLaunchers(isWindows, hermesHome)) {
    const root: string | null = launcherInstallDirectory(launcher)

    if (root && existsSync(path.join(root, 'hermes_cli', 'main.py'))) {
      return { launcher, root }
    }
  }

  return null
}

export function launcherTargetsInstallation(launcher: string, root: string): boolean {
  try {
    const reported: string | null = launcherInstallDirectory(launcher, root)

    return reported !== null && reported === realpathSync(root)
  } catch {
    return false
  }
}

// A launcher's install directory cannot move while this process lives, and the
// backend resolver runs once per surface (startup, TUI resume, pool backends, and
// every tick of reensureDuringRestart), so the HERMES_DESKTOP_HERMES rung memoizes
// each launcher's root. The probe is async: `--version` may take seconds (it also
// runs the passive update check) and must never stall Electron's main thread.
// Concurrent resolves share one in-flight probe. A miss (no `Install directory:`
// line, a timeout, a launcher mid-replacement) is cached only briefly, so it is
// neither permanent nor re-spawned on every resolve.
export const LAUNCHER_ROOT_MISS_TTL_MS = 60_000
const launcherInstallRoots = new Map<string, Promise<string | undefined>>()
const launcherRootMisses = new Map<string, number>()

/** The root a launcher reports, memoized: ticketRuntimeFor() mints gateway
 *  tickets from a command backend only when it names its installation root. */
export function launcherInstallRoot(launcher: string): Promise<string | undefined> {
  const missedAt = launcherRootMisses.get(launcher)

  if (missedAt !== undefined && Date.now() - missedAt < LAUNCHER_ROOT_MISS_TTL_MS) {
    return Promise.resolve(undefined)
  }

  const cached = launcherInstallRoots.get(launcher)

  if (cached) {return cached}
  const flight = launcherInstallDirectoryAsync(launcher).then(root => {
    if (root === null) {
      launcherInstallRoots.delete(launcher)
      launcherRootMisses.set(launcher, Date.now())

      return undefined
    }

    launcherRootMisses.delete(launcher)

    return root
  })

  launcherInstallRoots.set(launcher, flight)

  return flight
}

interface LauncherVersionProbe { command: string; args: string[]; options: SpawnSyncOptions }

// Node refuses to exec a .cmd directly (CVE-2024-27980), and `shell:true`
// would hand an interpolated path to cmd.exe wholesale. Invoke cmd.exe
// explicitly instead: a fixed argv, the path quoted verbatim and screened
// for cmd metacharacters, and nothing else for the shell to interpret.
function launcherVersionProbe(launcher: string, root?: string): LauncherVersionProbe | null {
  const viaCmd: boolean = process.platform === 'win32' && /\.cmd$/i.test(launcher)

  if (viaCmd && CMD_UNSAFE_PATH.test(launcher)) {
    return null
  }

  return {
    command: viaCmd ? (process.env.ComSpec ?? 'cmd.exe') : launcher,
    args: viaCmd ? ['/d', '/s', '/c', `""${launcher}" --version"`] : ['--version'],
    options: {
      cwd: root,
      timeout: 15000,
      windowsHide: true,
      windowsVerbatimArguments: viaCmd,
      env: root ? { ...process.env, HERMES_INSTALL_ROOT: root } : process.env
    }
  }
}

function reportedInstallDirectory(stdout: string): string | null {
  const reported: string | undefined = /^Install directory: (.+)$/m.exec(stdout)?.[1]?.trim()

  return reported ? realpathSync(reported) : null
}

/** The real install directory a launcher's `--version` reports, or null. */
export function launcherInstallDirectory(launcher: string, root?: string): string | null {
  try {
    const probe: LauncherVersionProbe | null = launcherVersionProbe(launcher, root)

    if (!probe) {return null}
    const result: SpawnSyncReturns<string> = spawnSync(probe.command, probe.args, { ...probe.options, encoding: 'utf8' })

    return result.error || result.status !== 0 ? null : reportedInstallDirectory(result.stdout)
  } catch {
    return null
  }
}

/** launcherInstallDirectory without blocking the caller's event loop. */
function launcherInstallDirectoryAsync(launcher: string, root?: string): Promise<string | null> {
  const probe: LauncherVersionProbe | null = launcherVersionProbe(launcher, root)

  if (!probe) {return Promise.resolve(null)}

  return new Promise(resolve => {
    try {
      execFile(probe.command, probe.args, { ...probe.options, encoding: 'utf8' } as ExecFileOptions, (error, stdout) => {
        try {
          resolve(error ? null : reportedInstallDirectory(String(stdout)))
        } catch {
          resolve(null)
        }
      })
    } catch {
      resolve(null)
    }
  })
}

/** File prerequisites only: dependency recovery remains reachable through update. */
export function windowsUpdatePrerequisiteError(updateRoot: string, hermesHome?: string): string | null {
  if (!resolveInstallationLauncher(updateRoot, true, hermesHome)) {
    return `Update aborted: the installation launcher under ${updateRoot} is missing. Repair this installation before retrying.`
  }

  const maintainedDir: string = path.join(updateRoot, 'scripts', 'desktop-update')

  if (existsSync(maintainedDir)) {
    for (const name of ['windows.ps1']) {
      const candidate: string = path.join(maintainedDir, name)

      if (!stagedFileExists(candidate)) {
        return `Update aborted: ${candidate} is missing or unreadable. Repair the installation and review antivirus quarantine before retrying.`
      }
    }
  }

  return null
}

export interface UpdaterChild {
  pid?: number
  unref: () => void
}

export interface ResolveUpdateScriptHandoffDeps {
  isWindows?: boolean
  fileExists?: (candidate: string) => boolean
}

export interface UpdateScriptHandoff {
  command: string
  args: string[]
  scriptPath: string
}

/**
 * Repo-owned Windows update hand-off (frozen-binary escape hatch).
 *
 * The staged Tauri `hermes-setup.exe` has no self-update path, so every
 * updater-side fix only reaches users when a new binary is built, signed and
 * published — which historically lags main by months and strands users on
 * long-fixed bugs (cache resolver #67369, marker self-adopt #74782; the
 * 2026-08-09 incident chain). `scripts/desktop-update/windows.ps1` lives in the repo
 * checkout instead: every `hermes update` refreshes the code that drives the
 * NEXT update, and only PowerShell itself is frozen.
 *
 * Returns the spawn recipe when the script exists in the checkout, or null
 * (caller falls back to the staged binary — old checkouts that predate the
 * script keep working unchanged). Windows-only by the same policy as
 * resolveStagedUpdaterBinary: POSIX updates in place via
 * applyUpdatesPosixInApp and needs no hand-off at all.
 */
export function resolveUpdateScriptHandoff(
  updateRoot: string,
  deps: ResolveUpdateScriptHandoffDeps = {}
): UpdateScriptHandoff | null {
  const isWindows = deps.isWindows ?? process.platform === 'win32'

  if (!isWindows) {
    return null
  }

  const exists = deps.fileExists ?? stagedFileExists

  // Current layout first, then the pre-reorg flat path — an updated asar can
  // meet a checkout from either side of the move (the checkout also ships a
  // forwarder at the legacy path for the inverse skew).
  for (const candidate of [
    path.join(updateRoot, 'scripts', 'desktop-update', 'windows.ps1'),
    path.join(updateRoot, 'scripts', 'desktop-update.ps1')
  ]) {
    if (exists(candidate)) {
      return {
        command: 'powershell',
        args: ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-File', candidate],
        scriptPath: candidate
      }
    }
  }

  return null
}

/**
 * Repo-owned POSIX update hand-off (the mac/linux twin of the above).
 *
 * Replaces the in-app posix updater: the Desktop spawns the script detached
 * and QUITS, the script waits it out, runs `hermes update`, swaps/relaunches
 * the app, and writes .hermes-update-result.json. With the app gone before
 * the update starts, the HERMES_DESKTOP_CHILD_PID reaper-exclusion dance is
 * unnecessary — there are no live desktop backends to spare.
 *
 * Null when the checkout predates the script (caller surfaces the manual
 * `hermes update` card — old checkouts pull the script on their next update).
 */
export function resolvePosixScriptHandoff(
  updateRoot: string,
  deps: ResolveUpdateScriptHandoffDeps = {}
): UpdateScriptHandoff | null {
  const isWindows = deps.isWindows ?? process.platform === 'win32'

  if (isWindows) {
    return null
  }

  const scriptPath = path.join(updateRoot, 'scripts', 'desktop-update', 'posix.sh')
  const exists = deps.fileExists ?? stagedFileExists

  if (!exists(scriptPath)) {
    return null
  }

  return {
    command: '/bin/bash',
    args: [scriptPath],
    scriptPath
  }
}

/**
 * Wrap a PowerShell hand-off invocation so it survives a hidden spawn from
 * Electron without ever showing a console window (#116161).
 *
 * Verified empirically (2026-08-09, Windows 11): `spawn('powershell', [...,
 * '-File', script], { detached: true, stdio: 'ignore', windowsHide: true })`
 * exits 0 WITHOUT executing a single line of the script. powershell.exe is a
 * console-subsystem binary; libuv maps `detached: true` to DETACHED_PROCESS,
 * which gives the child NO console (and makes the OS ignore CREATE_NO_WINDOW),
 * and Windows PowerShell 5.1 dies during console init before -File processing
 * (the same class of failure as #54220's conhost work, on the launch side).
 *
 * The parent-console model that follows from that (and that every other
 * hidden spawn in this app relies on): a console child inherits its parent's
 * console; only a console-LESS parent forces the OS to allocate a new,
 * visible one. So the wrapper cmd.exe is spawned NON-detached — libuv then
 * honours `windowsHide` (CREATE_NO_WINDOW) and cmd.exe owns one hidden
 * console — and `start "" /b powershell ...` runs the script inside that
 * hidden console (`/min` would tell `start` to allocate a NEW console for the
 * child, which is what flashed a minimized PowerShell window on every
 * hand-off; `/b` shares the wrapper's). The console outlives cmd.exe for as
 * long as powershell is attached to it.
 *
 * Survival past our own exit does not need `detached`: libuv's per-process
 * job object has JOB_OBJECT_LIMIT_SILENT_BREAKAWAY_OK, so grandchildren
 * (`start`'s powershell) are never members and Windows does not tie a
 * process's lifetime to its parent. By default `start` returns immediately, so the
 * spawned pid is the WRAPPER's — callers must not use it as a marker owner
 * (the script claims the marker itself with its own $PID). Set waitForExit for
 * callers that cancel the process tree or read the script's exit code: cmd then
 * runs the command directly in the same hidden console, stays alive until it
 * exits and returns its exit code (`start /wait` always returns 0).
 */
export function wrapHandoffForDetachedConsole(
  handoff: UpdateScriptHandoff,
  extraArgs: string[],
  waitForExit = false
): {
  command: string
  args: string[]
  /** Spawn NON-detached so the wrapper gets a hidden console the script inherits. */
  detached: false
} {
  return {
    command: 'cmd.exe',
    args: [
      '/d',
      '/s',
      '/c',
      ...(waitForExit ? [] : ['start', '', '/b']),
      handoff.command,
      ...handoff.args,
      ...extraArgs
    ],
    detached: false
  }
}

/**
 * Electron/Chromium internal switches that must NOT be replayed on re-exec:
 * runtime artifacts of THIS launch, not user intent (ported from the deleted
 * update-relaunch.ts; #45205). `--no-sandbox` is deliberately kept — it is
 * the user's sandbox opt-out and the signal that makes a relaunch safe when
 * chrome-sandbox isn't setuid.
 */
export const INTERNAL_ARG_PREFIXES = [
  '--type=',
  '--user-data-dir=',
  '--enable-features=',
  '--disable-features=',
  '--field-trial-handle=',
  '--enable-logging',
  '--log-file=',
  '--disable-gpu-sandbox',
  '--lang=',
  '--inspect',
  '--remote-debugging-port='
]

/** Filter Electron internals from process.argv.slice(1) so the relaunched
 * app replays only user/launcher intent (deep links, app flags). */
export function collectRelaunchArgs(argv: unknown): string[] {
  if (!Array.isArray(argv)) {
    return []
  }

  return argv.filter((arg): arg is string => {
    if (typeof arg !== 'string' || arg.length === 0) {
      return false
    }

    return !INTERNAL_ARG_PREFIXES.some(prefix =>
      prefix.endsWith('=') ? arg.startsWith(prefix) : arg === prefix || arg.startsWith(prefix + '=')
    )
  })
}

/** True when the user has opted out of the SUID sandbox — the relaunch is
 * safe even if chrome-sandbox fails preflight (ported from update-relaunch.ts). */
export function sandboxFallbackFromEnv(env: Record<string, string | undefined>, launchArgs: string[]): boolean {
  const disable = String(env?.ELECTRON_DISABLE_SANDBOX || '').trim()

  if (disable === '1' || disable.toLowerCase() === 'true') {
    return true
  }

  return Array.isArray(launchArgs) && launchArgs.includes('--no-sandbox')
}

export interface ResolveStagedUpdaterBinaryDeps {
  isWindows?: boolean
  fileExists?: (candidate: string) => boolean
  stagedMtimeMs?: (candidate: string) => number | null
}

/**
 * Staged installers older than this have no self-PID exclusion in
 * `UpdateMarkerGuard::acquire` and will refuse an update whose marker was
 * pre-written on their behalf.
 *
 * The self-adopt fix landed in #74782 / 160586ff8 (2026-07-30 17:57 +0700).
 * We compare against the start of 2026-07-31 UTC so the boundary is
 * unambiguous for binaries staged that same day.
 */
export const MARKER_SELF_ADOPT_EPOCH_MS = Date.UTC(2026, 6, 31)

function stagedFileExists(candidate: string): boolean {
  try {
    return statSync(candidate).isFile()
  } catch {
    return false
  }
}

function stagedFileMtimeMs(candidate: string): number | null {
  try {
    return statSync(candidate).mtimeMs
  } catch {
    return null
  }
}

/**
 * Decide which staged installer binary — if any — may be handed an update.
 *
 * The Tauri installer self-copies into HERMES_HOME on *every* platform
 * (`hermes-setup.exe` on Windows, `hermes-setup` elsewhere — see
 * apps/bootstrap-installer `paths::installer_dest` and
 * `bootstrap::copy_self_to_hermes_home`), so finding that binary on macOS or
 * Linux is expected, not leftover junk.
 *
 * Handing an update to it is nonetheless a Windows-only policy. Windows needs
 * the quit -> hand-off -> rebuild dance because a venv shim file lock keeps the
 * running desktop from rewriting its own bits; macOS and Linux have no such
 * lock and update in place through applyUpdatesPosixInApp(). Off Windows the
 * hand-off therefore buys nothing and costs a great deal: a staged binary older
 * than the hand-off protocol holds the update marker, spawns `hermes update`,
 * and that child refuses its own parent — wedging the in-app Update button for
 * good, with no route (update, re-download, reinstall) to a newer binary
 * (#74836). Returning null off Windows is what routes those platforms to the
 * in-app updater.
 *
 * Null on Windows too when nothing is staged (a dev/source run, or a CLI
 * install that never went through the installer); callers degrade gracefully.
 */
export function resolveStagedUpdaterBinary(
  hermesHome: string,
  deps: ResolveStagedUpdaterBinaryDeps = {}
): string | null {
  const isWindows = deps.isWindows ?? process.platform === 'win32'

  if (!isWindows) {
    return null
  }

  const fileExists = deps.fileExists ?? stagedFileExists
  const candidate = path.join(hermesHome, 'hermes-setup.exe')

  return fileExists(candidate) ? candidate : null
}

/**
 * True when the staged installer is new enough to survive a pre-written marker.
 *
 * `copy_self_to_hermes_home` deliberately no-ops during `--update`
 * (apps/bootstrap-installer/src-tauri/src/paths.rs), so the binary staged by a
 * user's ORIGINAL install orchestrates every later update — forever. Installers
 * predating #74782 have no self-PID exclusion in `UpdateMarkerGuard::acquire`,
 * so when the desktop pre-writes the marker naming that very updater, the
 * updater reads its own claim as a foreign live owner and aborts with
 * "Another Hermes update is already running (PID <itself>, started 1s ago)" —
 * the observed infinite "Install didn't finish" loop. Skipping the pre-write
 * for those binaries lets them acquire cleanly and run `hermes update`, which
 * pulls the permanent fixes. See shouldPrewriteUpdateMarker.
 *
 * We cannot ask the binary its version without executing it, so use its mtime:
 * the installer is written to HERMES_HOME at install/repair time, making mtime
 * a faithful stamp of which installer generation produced it.
 *
 * Unreadable mtime counts as UNSUPPORTED — the pre-write is a best-effort
 * hardening, while a wedged updater is unrecoverable, so we bias toward the
 * path that can always make progress.
 */
export function stagedUpdaterSupportsPrewrittenMarker(
  candidate: string,
  deps: ResolveStagedUpdaterBinaryDeps = {}
): boolean {
  const mtimeMs = (deps.stagedMtimeMs ?? stagedFileMtimeMs)(candidate)

  return typeof mtimeMs === 'number' && Number.isFinite(mtimeMs) && mtimeMs >= MARKER_SELF_ADOPT_EPOCH_MS
}

/**
 * Clear the staged macOS updater helper's quarantine and, when its signature
 * does not verify, ad-hoc sign it so Gatekeeper lets it run. Best effort.
 */
export function repairMacUpdaterHelper(
  updater: string | null,
  deps: { isMac: boolean; log: (line: string) => void }
): void {
  if (!deps.isMac || !updater) {
    return
  }

  try {
    execFileSync('/usr/bin/xattr', ['-cr', updater], { stdio: 'ignore' })
  } catch (err) {
    deps.log(`[updates] macOS updater helper quarantine repair skipped: ${(err as Error).message}`)
  }

  try {
    execFileSync('/usr/bin/codesign', ['--verify', updater], { stdio: 'ignore' })

    return
  } catch {
    // Unsigned or invalid helper. Apply a local ad-hoc signature so Gatekeeper
    // does not block the staged updater before it can run.
  }

  try {
    execFileSync('/usr/bin/codesign', ['--force', '--sign', '-', updater], { stdio: 'ignore' })
    deps.log('[updates] repaired macOS updater helper signature')
  } catch (err) {
    deps.log(`[updates] macOS updater helper signature repair skipped: ${(err as Error).message}`)
  }
}

export interface SpawnUpdaterProcessDeps {
  isWindows?: boolean
  spawnProcess?: (command: string, args: string[], options: SpawnOptions) => UpdaterChild
}

/**
 * Spawn the detached installer used for update and bootstrap-recovery handoffs.
 * The helper owns both hidden-console selection and unref semantics so every
 * updater handoff follows the same behavior and can be tested without Electron.
 */
export function spawnUpdaterProcess(
  updater: string,
  updaterArgs: string[],
  options: SpawnOptions,
  deps: SpawnUpdaterProcessDeps = {}
): UpdaterChild {
  const isWindows = deps.isWindows ?? process.platform === 'win32'
  const spawnOptions = hiddenWindowsChildOptions(options, isWindows) as SpawnOptions

  const child = deps.spawnProcess
    ? deps.spawnProcess(updater, updaterArgs, spawnOptions)
    : spawn(updater, updaterArgs, spawnOptions)

  child.unref()

  return child
}

/**
 * Stop a hand-off the Desktop has given up on (C2 timeout), so a script that
 * starts late cannot run an update the UI already reported as "did not start".
 * POSIX: the detached launcher leads its own process group — kill the group.
 * Windows: the `cmd start /b` wrapper exits at once and PowerShell outlives it,
 * so stop the wrapper's recorded children that carry this Desktop's
 * `-DesktopPid` (a reused pid never matches both), then the wrapper's tree if
 * it is still running. Best effort; the script is adopt-only besides (A4).
 */
export function killHandoffTree(
  child: UpdaterChild & { exitCode?: number | null; signalCode?: string | null },
  {
    isWindows = process.platform === 'win32',
    desktopPid = process.pid,
    kill = process.kill.bind(process),
    spawnProcess = spawn
  }: {
    isWindows?: boolean
    desktopPid?: number
    kill?: typeof process.kill
    spawnProcess?: typeof spawn
  } = {}
): void {
  const pid = child.pid

  if (!Number.isInteger(pid) || !pid || pid <= 0) {
    return
  }

  if (!isWindows) {
    try {
      kill(-pid, 'SIGKILL')
    } catch {
      try {
        kill(pid, 'SIGKILL')
      } catch {
        // Already gone.
      }
    }

    return
  }

  const wrapperRunning = child.exitCode == null && child.signalCode == null

  const command =
    `Get-CimInstance Win32_Process -Filter 'ParentProcessId=${pid}' | ` +
    `Where-Object { $_.CommandLine -match '-DesktopPid\\s+${desktopPid}(\\s|$)' } | ` +
    `ForEach-Object { taskkill.exe /PID $_.ProcessId /T /F | Out-Null }` +
    (wrapperRunning ? `; taskkill.exe /PID ${pid} /T /F | Out-Null` : '')

  try {
    spawnProcess('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', command], {
      stdio: 'ignore',
      windowsHide: true
    }).on('error', () => {})
  } catch {
    // Best effort.
  }
}

export interface UpdaterHandoffOutcome {
  ok: boolean
  /** Set when ok is false. */
  reason?: 'spawn-error' | 'early-exit'
  /** Human-readable detail for logs (never contains argv secrets). */
  message?: string
  /** Exit code when the child exited inside the settle window. */
  code?: number | null
  /** Signal when the child was killed inside the settle window. */
  signal?: string | null
}

export interface ObserveUpdaterHandoffDeps {
  setTimeoutFn?: (callback: () => void, ms: number) => unknown
  clearTimeoutFn?: (timer: unknown) => void
}

/**
 * User-facing copy for a hand-off that did not take (spawn error or early exit).
 * The lead sentence is plain: nothing changed and Hermes keeps running. The raw
 * outcome message (exit code / signal / spawn error) stays on a trailing
 * "Details:" line for logs and support.
 */
export function describeUpdaterHandoffFailure(outcome: Pick<UpdaterHandoffOutcome, 'message'>): string {
  const lead =
    "The updater couldn't start, so nothing was changed and Hermes keeps running as before. " +
    'Try again; if it keeps failing, open the logs and send them to support.'

  return outcome.message ? `${lead}\n\nDetails: ${outcome.message}` : lead
}

/**
 * Watch a just-spawned detached updater for the duration of the quit dwell
 * and report whether the hand-off actually became viable (#66753).
 *
 * Before this, the Desktop called `unref()` and quit after a fixed dwell
 * without ever observing the child's async `error` event (ENOENT/EACCES —
 * Node reports exec failures asynchronously) or an early `exit`. A failed
 * spawn therefore looked identical to a successful one: the app vanished, no
 * updater appeared, and nothing relaunched. Worse, an unhandled `'error'`
 * event on the detached child would crash the Electron main process outright.
 *
 * Success is: no `error` event AND either the child survives the settle
 * window or it exits 0 inside it (the Windows `cmd start` wrapper exits 0
 * immediately by design — see wrapHandoffForDetachedConsole). Failure is a
 * spawn `error`, a non-zero exit, or a signal death inside the window.
 *
 * Children that expose no event interface (bare test doubles) settle as ok
 * after the window — the observation is a best-effort hardening, never a new
 * way to wedge an update.
 */
export function observeUpdaterHandoff(
  child: UpdaterChild,
  settleMs: number,
  deps: ObserveUpdaterHandoffDeps = {}
): Promise<UpdaterHandoffOutcome> {
  const setTimeoutFn = deps.setTimeoutFn ?? setTimeout

  const clearTimeoutFn =
    deps.clearTimeoutFn ?? ((timer: unknown) => clearTimeout(timer as ReturnType<typeof setTimeout>))

  const observable = child as UpdaterChild & {
    once?: (event: string, listener: (...args: unknown[]) => void) => unknown
    removeListener?: (event: string, listener: (...args: unknown[]) => void) => unknown
  }

  if (typeof observable.once !== 'function') {
    return new Promise(resolve => {
      setTimeoutFn(() => resolve({ ok: true }), settleMs)
    })
  }

  return new Promise(resolve => {
    let settled = false

    const finish = (outcome: UpdaterHandoffOutcome) => {
      if (settled) {
        return
      }

      settled = true
      clearTimeoutFn(timer)
      observable.removeListener?.('error', onError)
      observable.removeListener?.('exit', onExit)
      resolve(outcome)
    }

    const onError = (...args: unknown[]) => {
      const error = args[0] as (Error & { code?: string }) | undefined

      finish({
        ok: false,
        reason: 'spawn-error',
        message: `updater spawn failed: ${error?.code || error?.message || 'unknown error'}`
      })
    }

    const onExit = (...args: unknown[]) => {
      const code = args[0] as number | null
      const signal = args[1] as string | null

      if (signal || (typeof code === 'number' && code !== 0)) {
        finish({
          ok: false,
          reason: 'early-exit',
          message: signal
            ? `updater died from signal ${signal} before the settle window elapsed`
            : `updater exited ${code} before the settle window elapsed`,
          code: code ?? null,
          signal: signal ?? null
        })

        return
      }

      // Clean exit 0 inside the window is expected for wrapper shapes
      // (cmd.exe `start` on Windows exits immediately after launching the
      // real script in its own console).
      finish({ ok: true, code: code ?? 0, signal: null })
    }

    const timer = setTimeoutFn(() => finish({ ok: true }), settleMs)

    observable.once('error', onError)
    observable.once('exit', onExit)
  })
}