/**
 * Full restart of the Codex desktop app (the Electron shell) on macOS, Linux and
 * Windows.
 *
 * WHY THIS EXISTS AT ALL. `--restart-codex` used to signal only `codex app-server` /
 * `codex-code-mode-host` processes, and on every platform that turns out not to
 * refresh the model picker. The app-server it signals is a CHILD of the desktop app
 * (measured: pid 16733 under pid 15901 on macOS, 3285204 under 3284901 on Linux), so
 * the app simply respawns it while the renderer keeps the roster it built at launch.
 * The matcher was never the problem; the only thing that reliably refreshes the
 * picker is restarting the shell that owns it.
 *
 * WHY THE CONSENT CHANGED. This capability was deliberately kept behind a separate
 * Windows-only `--restart-desktop-app` flag, because quitting the app ends live
 * conversations and that is a larger consent than restarting a background helper.
 * That reasoning was sound and has been superseded by an explicit maintainer
 * decision: `--restart-codex` now means the app is fully stopped and started again.
 * The narrow behaviour did not disappear, it moved to `--restart-app-server-only`.
 *
 * WHAT IS SHARED AND WHAT IS NOT. The ladder below — discover, enumerate, find
 * shells, check self-ancestry, graceful, wait, re-verify identity, force, wait,
 * refuse-or-relaunch — is identical on all three platforms. Only identity,
 * discovery, membership, the two stop primitives and relaunch differ, and those live
 * behind DesktopAppAdapter. Re-deriving the PID-reuse and fail-closed reasoning once
 * per operating system is how two of the three end up subtly wrong.
 *
 * EVERYTHING FAILS CLOSED. A failed discovery, a failed enumeration, an unreadable
 * process identity or an unreadable ancestry chain never authorises a kill and is
 * never reported as "nothing to do". A stale picker is a much smaller problem than a
 * wrongly killed process.
 *
 * Design and audit history: devlog/_fin/260913_cross_platform_desktop_app_restart/.
 */
import {
  acquireDesktopRestartLock,
  releaseDesktopRestartLock,
  type DesktopRestartLockIo,
} from "./desktop-app/lock";
import { rootShells, type DesktopAppAdapter, type DesktopExec, type DesktopProcess } from "./desktop-app/types";
import { darwinDesktopAppAdapter, darwinDefaultExec } from "./desktop-app/darwin";
import { linuxDesktopAppAdapter, linuxDefaultExec } from "./desktop-app/linux";
import { windowsDesktopAppAdapter, windowsDefaultExec } from "./desktop-app/windows";
import { isTestHomeGuardArmed } from "../lib/test-home-guard";
import { beginCodexCliSelectionParentWrite, withCodexCliSelectionParentWriteAsync, CodexCliSelectionMutationBusyError } from "./cli-update-selection-gate";

export type { DesktopAppExecOptions } from "./desktop-app/types";

/** How long a graceful close is given before the forced pass. */
const GRACEFUL_EXIT_TIMEOUT_MS = 15_000;
/** How long a forced kill is given before the target counts as surviving. */
const FORCED_EXIT_TIMEOUT_MS = 5_000;

export interface DesktopAppRestartHandoff {
  helperPid: number;
  logPath: string;
}

export interface DesktopAppRestartIo {
  platform?: NodeJS.Platform;
  /** Overrides the adapter chosen from `platform`. Tests drive every branch through this. */
  adapter?: DesktopAppAdapter;
  execFile?: DesktopExec;
  /** Process ancestry of the current process, innermost first. Used for the self-kill guard. */
  ancestryPids?: () => number[];
  isAlive?: (pid: number) => boolean;
  sleep?: (ms: number) => void;
  now?: () => number;
  lock?: DesktopRestartLockIo;
  /**
   * Hand the restart to a detached helper when this process is inside the tree.
   * Supplied by wp5; absent here means the ladder refuses instead, which is the
   * behaviour that shipped before the handoff existed.
   */
  startHandoff?: () => DesktopAppRestartHandoff | null;
  /**
   * False forbids a handoff. The helper passes it so recursion is structurally
   * impossible, and the management service passes it because it runs inside a proxy
   * that never exits — a handoff waiting for the caller to exit would always time out
   * after telling the operator it had been handed off.
   */
  allowHandoff?: boolean;
}

export type DesktopAppRestartReason =
  | "unsupported_platform"
  | "test_environment"
  | "package_discovery_failed"
  | "process_probe_failed"
  | "no_targets"
  | "self_ancestry"
  | "restart_in_flight"
  | "handoff_started"
  | "relaunch_context_failed"
  | "selection_mutation_busy"
  | "targets_survived"
  | "relaunch_failed";

export interface DesktopAppRestartResult {
  attempted: boolean;
  stopped: number[];
  surviving: number[];
  relaunch: "started" | "skipped";
  reason?: DesktopAppRestartReason;
  handoff?: DesktopAppRestartHandoff;
}

const ADAPTERS: Partial<Record<NodeJS.Platform, { adapter: DesktopAppAdapter; exec: DesktopExec }>> = {
  darwin: { adapter: darwinDesktopAppAdapter, exec: darwinDefaultExec },
  linux: { adapter: linuxDesktopAppAdapter, exec: linuxDefaultExec },
  win32: { adapter: windowsDesktopAppAdapter, exec: windowsDefaultExec },
};

function defaultIsAlive(pid: number): boolean {
  try {
    process.kill(pid, 0);
    return true;
  } catch {
    return false;
  }
}

function defaultSleep(ms: number): void {
  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
}

/**
 * True when the pid still names the process we verified.
 *
 * Between listing and signalling there is a graceful-close window long enough for the
 * OS to recycle a pid, and the next step is a hard kill. A pid alone is not an
 * identity across that window; the start-time token is what distinguishes a process
 * from its replacement.
 */
type IdentityCheck = "same" | "gone" | "unknown";

function checkIdentity(
  adapter: DesktopAppAdapter,
  exec: DesktopExec,
  install: Parameters<DesktopAppAdapter["listProcesses"]>[1],
  target: DesktopProcess,
): IdentityCheck {
  const processes = adapter.listProcesses(exec, install);
  // THREE outcomes, not two. Collapsing them into a boolean is what made this ladder
  // claim a restart it never performed: a re-probe that could not RUN looked identical
  // to a process that had exited, and the caller recorded the pid as stopped, skipped
  // the forced pass, and relaunched into an app that was still running - reporting
  // success the whole way. Measured on a real Windows host, where the app kept its
  // original pid and start time through a restart that said it had stopped it.
  if (processes === null) return "unknown";
  const current = processes.find(entry => entry.pid === target.pid);
  if (current === undefined) return "gone";
  // Same pid, different start time: the pid was recycled and now belongs to somebody
  // else. Treated as gone, because the process we meant to stop no longer exists and
  // signalling this pid would hit an unrelated process.
  return current.createdAt === target.createdAt ? "same" : "gone";
}

/**
 * Pids of the running desktop-app tree, or null when discovery or the probe failed.
 *
 * Read-only. Used by the CLI to exclude app-servers the desktop restart is about to
 * take anyway, so an operator\u2019s in-flight turn is not interrupted twice in one command.
 */
/**
 * Poll the platform's own process list until it stops listing this process.
 *
 * A single post-kill enumeration is not enough. Measured on Windows: `taskkill /T /F`
 * succeeds, the process is genuinely dead a moment later, and yet the very next
 * `Win32_Process` query still lists it. Checking once turned that lag into a reported
 * survivor, which blocked the relaunch and left the machine with no app at all - the
 * failure mode is the mirror of claiming a stop that never happened, and just as bad.
 *
 * Liveness is polled first because it is cheap; the enumeration is what decides. A probe
 * that cannot run keeps the loop going rather than deciding either way, and if the
 * deadline passes without a clean "gone" the caller treats it as a survivor.
 */
function waitUntilGone(
  adapter: DesktopAppAdapter,
  exec: DesktopExec,
  install: Parameters<DesktopAppAdapter["listProcesses"]>[1],
  target: DesktopProcess,
  timeoutMs: number,
  isAlive: (pid: number) => boolean,
  sleep: (ms: number) => void,
  now: () => number,
): boolean {
  const deadline = now() + timeoutMs;
  for (;;) {
    if (!isAlive(target.pid) && checkIdentity(adapter, exec, install, target) === "gone") return true;
    if (now() >= deadline) break;
    sleep(250);
  }
  // One last look after the deadline, so a process that exited during the final sleep is
  // not reported as surviving purely because of poll timing.
  return checkIdentity(adapter, exec, install, target) === "gone";
}

export function listCodexDesktopAppPids(io: DesktopAppRestartIo = {}): number[] | null {
  const platform = io.platform ?? process.platform;
  const selected = ADAPTERS[platform];
  const adapter = io.adapter ?? selected?.adapter;
  if (!adapter) return null;
  const exec = io.execFile ?? selected?.exec;
  if (!exec) return null;
  const install = adapter.discover(exec);
  if (!install) return null;
  const processes = adapter.listProcesses(exec, install);
  return processes === null ? null : processes.map(entry => entry.pid);
}

/**
 * Pids of the running desktop-app ROOT shells, or null when discovery or the probe failed.
 *
 * Read-only. The shell is the process whose renderer built the model picker, so its start
 * time is what tells `performCodexRestart` whether the picker predates the catalog (#4761).
 * `[]` means the probe ran and the app is not running.
 */
export function listCodexDesktopShellPids(io: DesktopAppRestartIo = {}): number[] | null {
  const platform = io.platform ?? process.platform;
  const selected = ADAPTERS[platform];
  const adapter = io.adapter ?? selected?.adapter;
  if (!adapter) return null;
  const exec = io.execFile ?? selected?.exec;
  if (!exec) return null;
  const install = adapter.discover(exec);
  if (!install) return null;
  const processes = adapter.listProcesses(exec, install);
  if (processes === null) return null;
  return rootShells(processes, install, adapter).map(entry => entry.pid);
}

export function restartCodexDesktopApp(io: DesktopAppRestartIo = {}): DesktopAppRestartResult {
  const skipped = (reason: DesktopAppRestartReason): DesktopAppRestartResult => ({
    attempted: false, stopped: [], surviving: [], relaunch: "skipped", reason,
  });

  const platform = io.platform ?? process.platform;
  const selected = ADAPTERS[platform];
  const adapter = io.adapter ?? selected?.adapter;
  const exec = io.execFile ?? selected?.exec;
  if (!adapter || !exec) return skipped("unsupported_platform");
  // In an armed test process a call without an injected exec would reach the real OS (an injected
  // adapter still execs through the platform default): on a developer Mac, `performCodexRestart`
  // tests quit the user's ChatGPT (Codex) app and relaunched it through `/usr/bin/open` with the
  // runner's sandbox HOME, logged out. Armed means the test preload's flag, not NODE_ENV, for the
  // reason test-home-guard gives: a real `NODE_ENV=test ocx ...` must still restart the app.
  if (!io.execFile && isTestHomeGuardArmed()) return skipped("test_environment");

  // Step 0. Two restarts at once are destructive rather than merely wasteful: the
  // first quits and relaunches, the second sees the freshly started shell as a target
  // and kills it. Own-pid reentrancy means the wp5 helper runs this same step and
  // finds the lock its caller made out to it.
  // A cli-update worker holds this gate from its final process scan through
  // installer termination and readback, so no new shell may appear inside. The
  // admission check runs BEFORE the restart lock and every mutation this
  // function performs: a busy refusal must leave the app, the lock and any
  // handoff all untouched. Held through relaunch or a failed attempt's
  // cleanup; a handoff helper's own delayed descendants stay the documented
  // pre-existing residual.
  const selectionWrite = beginCodexCliSelectionParentWrite();
  if (!selectionWrite.entered) return skipped("selection_mutation_busy");

  let handedOff = false;
  // The lock attempt sits inside the protected scope too: a throw from the
  // lock's own mkdir/write before the try would otherwise leak this
  // process-wide gate for the rest of the process. lockHeld distinguishes
  // "acquisition threw/refused" from "lock taken" so a failed attempt never
  // releases a lock this call does not hold.
  let lockHeld = false;
  try {
    const acquisition = acquireDesktopRestartLock(io.lock);
    if (!acquisition.acquired) return skipped("restart_in_flight");
    lockHeld = true;
    const install = adapter.discover(exec);
    if (!install) return skipped("package_discovery_failed");

    const processes = adapter.listProcesses(exec, install);
    // A probe that could not run is not evidence of absence. Reporting it as no_targets
    // told users the app was not running and silently skipped the restart they asked
    // for (#2557).
    if (processes === null) return skipped("process_probe_failed");

    const shells = rootShells(processes, install, adapter);
    if (shells.length === 0) return skipped("no_targets");

    const ancestryPids = io.ancestryPids ? io.ancestryPids() : adapter.ancestryPids(exec);
    // An empty chain means "could not establish that we are outside the tree", which
    // covers both an unreadable hop and a walk that hit its bound.
    const insideTree = ancestryPids.length === 0
      || processes.some(entry => ancestryPids.includes(entry.pid));
    if (insideTree) {
      if (io.allowHandoff === false || !io.startHandoff) return skipped("self_ancestry");
      const handoff = io.startHandoff();
      if (!handoff) return skipped("self_ancestry");
      handedOff = true;
      return {
        attempted: false, stopped: [], surviving: [],
        relaunch: "skipped", reason: "handoff_started", handoff,
      };
    }

    // Captured while the tree is still ALIVE. On Linux the relaunch needs the
    // graphical session variables, and after termination there is nothing to read them
    // from. Ordering this wrongly works on macOS and Windows and produces a Linux app
    // that cannot reach the compositor.
    let context: Record<string, string>;
    try { context = adapter.captureRelaunchContext(exec, install, processes); }
    catch { return skipped("relaunch_context_failed"); }

    const isAlive = io.isAlive ?? defaultIsAlive;
    const sleep = io.sleep ?? defaultSleep;
    const now = io.now ?? (() => Date.now());
    const stopped: number[] = [];
    const surviving: number[] = [];

    for (const shell of shells) {
      const pid = shell.pid;
      // The listing is already one probe old.
      const before = checkIdentity(adapter, exec, install, shell);
      if (before === "gone") {
        stopped.push(pid);
        continue;
      }
      if (before === "unknown") {
        // We could not look, so we cannot claim this exited and we must not signal a
        // process we failed to re-verify. Reporting it as surviving is the honest answer:
        // it blocks the relaunch, which is exactly right when the tree state is unknown.
        surviving.push(pid);
        continue;
      }
      try {
        adapter.requestQuit(exec, install, shell);
      } catch {
        /* a refused graceful close still gets the forced pass below */
      }
      // Liveness AND enumeration have to agree before a stop is claimed. A pid-based
      // liveness probe is a weaker instrument than the platform's own process list, and
      // on a packaged app the two disagree in BOTH directions.
      if (waitUntilGone(adapter, exec, install, shell, GRACEFUL_EXIT_TIMEOUT_MS, isAlive, sleep, now)) {
        stopped.push(pid);
        continue;
      }
      // The wait window is long enough for a pid to be recycled, and the next step is a
      // hard kill. Confirm it is still the process we verified, or leave it alone.
      const afterGraceful = checkIdentity(adapter, exec, install, shell);
      if (afterGraceful === "gone") {
        stopped.push(pid);
        continue;
      }
      if (afterGraceful === "unknown") {
        surviving.push(pid);
        continue;
      }
      try {
        adapter.forceStop(exec, shell);
      } catch {
        /* the process state decides, not the exit code */
      }
      // Same rule after the forced pass: only an enumeration that no longer contains this
      // process proves it stopped. Everything else is a survivor, and a survivor blocks
      // the relaunch rather than producing a second shell beside a live one.
      if (waitUntilGone(adapter, exec, install, shell, FORCED_EXIT_TIMEOUT_MS, isAlive, sleep, now)) {
        stopped.push(pid);
      } else {
        surviving.push(pid);
      }
    }

    if (surviving.length > 0) {
      // Launching a second shell beside a stuck one is worse than leaving the operator
      // to restart it.
      return { attempted: true, stopped, surviving, relaunch: "skipped", reason: "targets_survived" };
    }

    try {
      adapter.relaunch(exec, install, context);
    } catch {
      // Distinct from targets_survived on purpose. Everything DID die and the relaunch
      // is what failed; the old code reported the two as one and sent operators looking
      // for processes that were not there.
      return { attempted: true, stopped, surviving, relaunch: "skipped", reason: "relaunch_failed" };
    }
    return { attempted: true, stopped, surviving: [], relaunch: "started" };
  } finally {
    // On the handoff path ownership was transferred to the helper, so releasing here
    // would drop a lock that is still protecting a restart about to happen.
    selectionWrite.exit();
    if (lockHeld && !handedOff) releaseDesktopRestartLock(io.lock);
  }
}

export async function restartCodexDesktopAppAsync(io: DesktopAppRestartIo = {}): Promise<DesktopAppRestartResult> {
  try { return await withCodexCliSelectionParentWriteAsync(() => restartCodexDesktopApp(io)); }
  catch (error) {
    if (error instanceof CodexCliSelectionMutationBusyError) return {
      attempted: false, stopped: [], surviving: [], relaunch: "skipped", reason: "selection_mutation_busy",
    };
    throw error;
  }
}
