/**
 * Dashboard-driven Codex app-server restart (#1046 follow-up).
 *
 * The defect: Codex builds a static model manager from the catalog once at
 * app-server startup and never rereads the file, so an app-server that outlives a
 * catalog write serves a roster that no longer exists on disk. Detection already
 * existed and already fired — but it warns on stderr, and the thing keeping an SSH
 * workspace's app-server alive is the Codex app, not a human at a terminal.
 *
 * This module is the consent boundary the startup path deliberately refuses to
 * cross (see `warnIfStaleCodexAppServersAfterStartupWrite`): a login is not consent
 * to interrupt an in-flight turn, but a dashboard click is.
 *
 * The route is a thin adapter over these two functions. Decisions live here so a
 * test can drive every branch through {@link CodexRestartServiceIo} instead of
 * mocking modules — a route test that could not stub this would really terminate
 * the developer's own Codex.
 *
 * Plan and audit history: `devlog/_fin/260815_gui_codex_restart/010_phase1_backend_endpoint.md`.
 */
import {
  collectCodexAppServerCatalogState,
  collectCodexAppServerCatalogStateWithin,
  DASHBOARD_CATALOG_STATE_DEADLINE_MS,
  listCodexAppServerProcesses,
  readProcessStartMsBatch,
  resetCodexAppServerCatalogStateCache,
  restartCodexAppServers,
} from "./app-server-processes";
import type { CodexAppServerProcessIo } from "./app-server-processes";
import type {
  CodexAppServerStateResponse,
  CodexDesktopRestartSummary,
  CodexRestartResponse,
} from "../lib/codex-restart-contract";
import { getServerListenPort } from "../server/lifecycle";
import type { DesktopPickerState } from "./desktop-app/picker-freshness";

async function defaultRestartDesktopApp(): Promise<CodexDesktopRestartSummary> {
  const { restartCodexDesktopAppAsync } = await import("./desktop-app-restart");
  const outcome = await restartCodexDesktopAppAsync({ allowHandoff: false });
  return {
    attempted: outcome.attempted,
    stopped: outcome.stopped,
    surviving: outcome.surviving,
    relaunch: outcome.relaunch,
    ...(outcome.reason === undefined ? {} : { reason: outcome.reason }),
  };
}

async function defaultDesktopPickerState(): Promise<DesktopPickerState> {
  const { readCodexDesktopPickerState } = await import("./desktop-app/picker-freshness");
  return readCodexDesktopPickerState();
}

async function defaultCatalogBinding(): Promise<string | null> {
  const { readCodexCatalogBinding } = await import("./desktop-app/picker-freshness");
  return readCodexCatalogBinding();
}

async function readBinding(io: CodexRestartServiceIo): Promise<string | null | undefined> {
  try {
    return await (io.catalogBinding ?? defaultCatalogBinding)();
  } catch {
    // Distinct from null ("binds no catalog"): an unreadable binding cannot prove sameness.
    return undefined;
  }
}

async function readPickerState(io: CodexRestartServiceIo): Promise<DesktopPickerState> {
  try {
    return await (io.desktopPickerState ?? defaultDesktopPickerState)();
  } catch {
    return "unknown";
  }
}

export interface CodexRestartServiceIo {
  /** Desktop-restart seam, so a route test cannot terminate the developer's own Codex. */
  restartDesktopApp?: () => Promise<CodexDesktopRestartSummary>;
  /** Whether the desktop picker predates the catalog; decides if the shell must restart. */
  desktopPickerState?: () => Promise<DesktopPickerState>;
  /** The catalog config.toml binds, read before and after the sync to catch a rebinding. */
  catalogBinding?: () => Promise<string | null>;
  /** Process-layer seam, forwarded to every app-server-processes call. */
  processIo?: CodexAppServerProcessIo;
  /** Catalog refresh seam. Resolves to whether a catalog or cache write happened. */
  syncCatalog?: (port?: number) => Promise<boolean>;
  /**
   * Live listen port. `config.port` names the PREFERRED port; after a fallback
   * start the bound port differs, and syncing the preferred one would point Codex
   * at a dead listener (same reason the CLI startup path passes the live port).
   */
  listenPort?: () => number | undefined;
  collectState?: typeof collectCodexAppServerCatalogState;
  /** Deadline for the default dashboard state read (ms). */
  stateDeadlineMs?: number;
  listProcesses?: typeof listCodexAppServerProcesses;
  restart?: typeof restartCodexAppServers;
  resetStateCache?: () => void;
  /** Start-time reader used to re-confirm process identity before signalling. */
  readStartMs?: (pids: readonly number[]) => Map<number, number | null>;
}

/**
 * Thrown by the final identity gate when a pid no longer belongs to the process
 * that was classified. restartCodexAppServers turns a kill throw into a `failed`
 * entry, which is the honest outcome: nothing was signalled and the caller is told.
 */
class CodexAppServerIdentityChanged extends Error {
  constructor(pid: number) {
    super(`codex app-server identity changed before signal (pid ${pid})`);
    this.name = "CodexAppServerIdentityChanged";
  }
}


/**
 * Single-flight latch. Two dashboard surfaces can each hold their own controller,
 * so a user can press restart twice while the first request is still syncing the
 * catalog. Without this, the second call re-signals processes the first already
 * terminated and both report success — and it widens the window in which a pid can
 * be recycled between classification and signalling.
 */
let inFlight: Promise<CodexRestartResponse> | null = null;

/**
 * Read-only state for the dashboard route. The default classifier is the bounded
 * request-path read: on Windows the synchronous one runs PowerShell CIM enumeration
 * inline, which measured 4-7s per call and stalled every listener, proxy traffic
 * included, each time the Models page opened. A probe slower than the deadline answers
 * `unknown` and keeps refreshing the cache. The restart path below keeps the
 * synchronous reading because it acts on it.
 */
export async function readCodexAppServerState(
  io: CodexRestartServiceIo = {},
): Promise<CodexAppServerStateResponse> {
  const status = io.collectState
    ? io.collectState(io.processIo ?? {})
    : await collectCodexAppServerCatalogStateWithin(
      io.stateDeadlineMs ?? DASHBOARD_CATALOG_STATE_DEADLINE_MS,
      io.processIo ?? {},
    );
  return { state: status.state, runningCount: status.processes.length };
}

export function performCodexRestart(
  io: CodexRestartServiceIo = {},
): Promise<CodexRestartResponse> {
  if (inFlight) return inFlight;
  const run = runCodexRestart(io).finally(() => {
    inFlight = null;
  });
  inFlight = run;
  return run;
}

/** Test hook: drop the single-flight latch between cases. */
export function resetCodexRestartInFlightForTests(): void {
  inFlight = null;
}

async function runCodexRestart(io: CodexRestartServiceIo): Promise<CodexRestartResponse> {
  // Refresh the catalog FIRST. A user pressing "restart Codex" wants the new
  // roster; stopping app-servers before the write would hand the replacement the
  // same stale file it just lost.
  let synced = false;
  const bindingBefore = await readBinding(io);
  try {
    const port = (io.listenPort ?? getServerListenPort)();
    synced = await (io.syncCatalog ?? defaultSyncCatalog)(port);
  } catch {
    // A sync failure must not block the restart: an operator whose picker is stale
    // still benefits from the app-server exiting and rereading whatever is on disk.
  }

  // The classifier memoizes for 5s when every io field is defaulted, so a reading
  // taken before the write above would otherwise be replayed after it.
  (io.resetStateCache ?? resetCodexAppServerCatalogStateCache)();
  const before = (io.collectState ?? collectCodexAppServerCatalogState)(io.processIo ?? {});

  // Decided here, before the early returns, because the model picker lives in the DESKTOP
  // app: "no app-server is running" is not a reason to leave a stale roster on screen.
  //
  // The shell gets a restart attempt whenever its picker cannot be proven current: at
  // or before the catalog mtime it is stale, and newer is unknown because an earlier
  // sync may have rebound an already-existing catalog file (#4761). Quitting it
  // discards composer drafts, unsent picker selections and pending approvals. The
  // attempt is explicit, not a guarantee: the restart helper can refuse or partially
  // fail, and desktopApp reports that outcome.
  //
  // allowHandoff is false and that is deliberate. The handoff waits for the CALLING
  // process to exit, and this runs inside a long-lived proxy that does not, so every
  // handoff started here would sit out its window and fail after the operator had
  // already been told it was handed off. An honest refusal beats that.
  //
  // A sync that rebinds model_catalog_json without rewriting the catalog bytes leaves the
  // catalog mtime older than the shell, yet the shell loaded the previous binding. Seen
  // across this request's own sync, that is proof of staleness, so it skips the probe.
  const bindingAfter = await readBinding(io);
  const rebound = bindingBefore === undefined || bindingAfter === undefined || bindingBefore !== bindingAfter;
  const picker: DesktopPickerState = rebound ? "stale" : await readPickerState(io);
  const desktop: CodexDesktopRestartSummary = picker === "current" || picker === "not_running"
    ? {
      attempted: false, stopped: [], surviving: [], relaunch: "skipped",
      reason: picker === "current" ? "picker_current" : "no_targets",
      pickerState: picker,
    }
    : { ...await (io.restartDesktopApp ?? defaultRestartDesktopApp)(), pickerState: picker };

  const nothingToDo = (): CodexRestartResponse => ({
    desktopApp: desktop,
    success: true,
    stateBefore: before.state,
    synced,
    requested: [],
    stopped: [],
    surviving: [],
    failed: [],
    // Enumeration failure reads as `unknown`, never `not_running` (#857): a failed
    // enumeration must not be reported as "nothing was running".
    code: before.state === "unknown" ? "enumeration_unavailable" : "nothing_running",
  });

  // `unknown` is not only the empty enumeration-failure case: the classifier also
  // returns it WITH processes when the catalog mtime or a start time is unreadable.
  // In that state it has not established that any server predates the catalog, so
  // signalling would kill a possibly-current app-server on a guess.
  if (before.state === "unknown" || before.processes.length === 0) return nothingToDo();

  // The classifier carries { pid, startedAtMs } and no command line, but
  // restartCodexAppServers needs the full identity so it can refuse to signal a
  // recycled pid. Re-list and intersect on pid rather than reconstructing an
  // identity we never verified.
  const classifiedStarts = new Map(
    before.processes.map(entry => [entry.pid, entry.startedAtMs] as const),
  );
  const live = (io.listProcesses ?? listCodexAppServerProcesses)(io.processIo ?? {});
  const candidates = live.filter(process => classifiedStarts.has(process.pid));

  // A pid plus a command line is not an identity: a replacement app-server launched
  // by the same Codex install has both. Re-read start times and drop any candidate
  // whose process started after the reading we classified, so a recycled pid can
  // never receive a signal meant for the process that held it.
  const platform = io.processIo?.platform ?? process.platform;
  const startsNow = candidates.length > 0
    ? (io.readStartMs ?? (pids => readProcessStartMsBatch(pids, platform)))(
      candidates.map(process => process.pid),
    )
    : new Map<number, number | null>();
  const targets = candidates.filter(process => {
    const classified = classifiedStarts.get(process.pid) ?? null;
    const current = startsNow.get(process.pid) ?? null;
    // An unreadable start time on either side means we cannot prove sameness.
    if (classified === null || current === null) return false;
    return classified === current;
  });

  if (targets.length === 0) {
    // Every classified process exited, or the pid now belongs to a different
    // process. Reporting "stopped" would claim credit for work this request did
    // not do.
    return {
      success: true,
      stateBefore: before.state,
      synced,
      requested: [],
      stopped: [],
      surviving: [],
      failed: [],
      code: "nothing_running",
      desktopApp: desktop,
    };
  }

  // Final identity gate, applied at the moment of signalling rather than before it.
  //
  // restartCodexAppServers re-lists and compares pid+command-line immediately
  // before SIGTERM, but a replacement app-server launched by the same Codex
  // install has BOTH of those. The start time is the field that distinguishes
  // them, and it is not part of that comparison, so the check above (done before
  // the call) still leaves a window: the original can exit and a replacement can
  // claim its pid in between.
  //
  // Wrapping `kill` closes the window: this runs inside restartCodexAppServers'
  // own signalling loop, so the start time is re-read at the last possible moment.
  // An unreadable start time refuses the signal — on a recycled pid, guessing
  // costs the user the turn that is running right now.
  const guardedProcessIo: CodexAppServerProcessIo = {
    ...(io.processIo ?? {}),
    kill: (pid, signal) => {
      const classified = classifiedStarts.get(pid) ?? null;
      const current = (io.readStartMs ?? (pids => readProcessStartMsBatch(pids, platform)))([pid])
        .get(pid) ?? null;
      if (classified === null || current === null || classified !== current) {
        throw new CodexAppServerIdentityChanged(pid);
      }
      const send = io.processIo?.kill ?? ((target: number, sig: NodeJS.Signals) => {
        process.kill(target, sig);
      });
      send(pid, signal);
    },
  };

  const result = (io.restart ?? restartCodexAppServers)(targets, guardedProcessIo);

  const clean = result.surviving.length === 0 && result.failed.length === 0;
  return {
    desktopApp: desktop,
    success: clean,
    stateBefore: before.state,
    synced,
    requested: result.requested,
    stopped: result.stopped,
    surviving: result.surviving,
    // Project { pid, error } down to pids: an OS error message can embed a path
    // or the account name.
    failed: result.failed.map(entry => entry.pid),
    code: clean ? "stopped" : "partially_stopped",
  };
}

async function defaultSyncCatalog(port?: number): Promise<boolean> {
  const { syncModelsToCodex } = await import("./sync");
  // `undefined` config takes syncModelsToCodex's own loadConfig() default; `null`
  // log keeps this request path silent.
  const result = await syncModelsToCodex(port, undefined, null);
  return result.catalogWritten || result.cacheSynced;
}

