import { execFile } from "node:child_process";
import { promisify } from "node:util";

import {
  errorMessage,
  systemProcessOwnershipHost as systemHost,
} from "./ProcessOwnershipObservation.js";
import { launcherIdentityFailure } from "./ProcessOwnershipIdentity.js";
import { descendantsOf, liveProcesses } from "./ProcessOwnershipProcessTree.js";
import { readProcessRunTokens } from "./ProcessRunTokenObservations.js";

const execFileAsync = promisify(execFile);

/** Identity proof required before REA may signal an owned process group. */
export interface OwnedProcessGroup {
  readonly runId: string;
  readonly leaderPid: number;
  readonly processGroupId: number;
  /** Expected launcher identity, checked only while the leader exists. */
  readonly expectedCommand?: string;
  /** Expected launcher parent, checked only while the leader exists. */
  readonly expectedParentPid?: number;
  /** Scan all live processes for this run token during cleanup. */
  readonly sweepTokenOwnedProcesses?: boolean;
  /** Prelaunch process identities for this capture; absent on generic callers. */
  readonly captureBaseline?: ProcessOwnershipBaseline;
  /**
   * Groups observed in capture samples. Observation adds cleanup candidates but
   * does not authorize signaling; every live member still needs token proof.
   */
  readonly sampledProcessGroupIds?: readonly number[];
}

/** Capture-local baseline; null means the PID identity could not be established. */
export type ProcessOwnershipBaseline = readonly {
  readonly pid: number;
  readonly identity: string | null;
}[];

/** One entry from an operating-system process-table snapshot. */
export interface ProcessTableEntry {
  readonly pid: number;
  readonly parentPid: number;
  readonly processGroupId: number;
  /** Effective owner when the process table reports it. */
  readonly uid?: number;
  readonly state: string;
  readonly command: string;
}

/** Native process start identity; unavailable identities must never be skipped. */
export type ProcessIdentityObservation =
  | { readonly state: "readable"; readonly identity: string }
  | { readonly state: "unavailable"; readonly reason: string };

/** Token-verified process lineage retained for one owned provider run. */
export interface OwnedProcessLineage {
  readonly runId: string;
  readonly launcherPid: number;
  readonly launcherParentPid: number;
  readonly processGroupId: number;
  readonly descendants: readonly {
    readonly pid: number;
    readonly parentPid: number;
    readonly processGroupId: number;
  }[];
}

/** Result of observing owned lineage without signaling any process. */
export type ProcessLineageObservation =
  | {
      readonly status: "verified";
      readonly observedAt: string;
      readonly lineage: OwnedProcessLineage;
    }
  | {
      readonly status: "unavailable";
      readonly observedAt: string;
      readonly runId: string;
      readonly launcherPid: number;
      readonly processGroupId: number;
      readonly reason: string;
    };

/** Narrow operating-system seam used to inspect processes and signal groups. */
export interface ProcessOwnershipHost {
  readonly platform?: NodeJS.Platform;
  /** Prepare required native identity inspection before launching a child. */
  prepare?(signal?: AbortSignal): Promise<void>;
  /** Release owned native inspection helpers and their temporary files. */
  close?(): Promise<void>;
  /** List current processes; startup inspection may be cancelled by the caller. */
  listProcesses(signal?: AbortSignal): Promise<readonly ProcessTableEntry[]>;
  environment(
    pid: number,
    signal?: AbortSignal,
  ): Promise<Readonly<Record<string, string>>>;
  /** Read only run-token values in one host operation when the OS supports it. */
  runTokens?(
    processes: readonly ProcessTableEntry[],
    signal?: AbortSignal,
  ): Promise<ReadonlyMap<number, ProcessRunTokenObservation>>;
  /** Read stable identities; omit the signal during cleanup so it can finish. */
  processIdentities?(
    processes: readonly ProcessTableEntry[],
    signal?: AbortSignal,
  ): Promise<ReadonlyMap<number, ProcessIdentityObservation>>;
  /** Snapshot identities before launch, honoring startup cancellation. */
  captureBaseline?(signal?: AbortSignal): Promise<ProcessOwnershipBaseline>;
  signalGroup(processGroupId: number, signal: NodeJS.Signals): void;
}

/** Whether one live process exposed its ownership token to the host. */
export type ProcessRunTokenObservation =
  | { readonly state: "readable"; readonly runId: string | undefined }
  | { readonly state: "unavailable"; readonly reason: string };

/** Narrow Windows P0 seam for bounded process-tree termination. */
export interface WindowsProcessTreeHost {
  terminateTree(rootPid: number): Promise<"terminated" | "missing">;
}

/** Per-member reason that token-verified cleanup failed closed. */
interface ProcessOwnershipValidationFailure {
  readonly pid: number;
  readonly reason:
    | "environment-unreadable"
    | "run-token-mismatch"
    | "process-identity-unavailable";
  readonly diagnostic?: string;
}

/**
 * One live process the ownership sweep could not attribute or exonerate.
 * Recorded as evidence instead of failing the capture: the process is not
 * related to the owned tree, so cleanup cannot act on it and the operating
 * system withheld or removed its token (for example, macOS strips the
 * environment of Apple platform binaries, and foreign-uid processes return
 * EINVAL for KERN_PROCARGS2).
 */
export interface OwnershipSweepUnverifiedProcess {
  readonly pid: number;
  readonly diagnostic: string;
}

/** Capture-owned process structures used to classify sweep candidates. */
export interface OwnershipSweepRelation {
  readonly leaderPid: number;
  readonly processGroupId: number;
  readonly sampledProcessGroupIds?: readonly number[];
}

/** Cleanup outcome with per-member diagnostics when ownership is uncertain. */
export type ProcessCleanupResult =
  | {
      readonly cleaned: true;
      readonly signaled: boolean;
      readonly unverified?: readonly OwnershipSweepUnverifiedProcess[];
    }
  | ProcessCleanupFailure;

/** Retained verification failures for one cleanup attempt, without additional signaling authority. */
export interface ProcessCleanupFailure {
  readonly cleaned: false;
  readonly reason: string;
  readonly failures?: readonly ProcessOwnershipValidationFailure[];
  readonly unverified?: readonly OwnershipSweepUnverifiedProcess[];
}

/** Token-verified liveness result used by post-root-exit settlement. */
export type ProcessGroupObservation =
  | { readonly state: "empty" }
  | { readonly state: "alive" }
  | { readonly state: "unverifiable"; readonly reason: string };

/**
 * Terminate one Windows process tree through the platform utility.
 *
 * This is a bounded P0 cleanup mechanism, not Job Object ownership proof. The
 * caller-visible Windows capability report remains unavailable until a native
 * authority verifies Job Object creation, membership, and cleanup semantics.
 */
export const cleanupWindowsProcessTree = async (
  rootPid: number,
  host: WindowsProcessTreeHost = systemWindowsProcessTreeHost,
): Promise<ProcessCleanupResult> => {
  if (!Number.isSafeInteger(rootPid) || rootPid <= 0)
    return { cleaned: false, reason: "Windows process-tree PID is invalid" };
  try {
    const result = await host.terminateTree(rootPid);
    return { cleaned: true, signaled: result === "terminated" };
  } catch (cause: unknown) {
    return {
      cleaned: false,
      reason: `Windows process-tree termination failed for PID ${String(rootPid)}: ${errorMessage(cause)}`,
    };
  }
};

const systemWindowsProcessTreeHost: WindowsProcessTreeHost = {
  async terminateTree(rootPid) {
    try {
      await execFileAsync(
        "taskkill.exe",
        ["/pid", String(rootPid), "/t", "/f"],
        { windowsHide: true, timeout: 5_000 },
      );
      return "terminated";
    } catch (cause: unknown) {
      if (
        cause instanceof Error &&
        "code" in cause &&
        (cause.code === 128 || cause.code === "ESRCH")
      )
        return "missing";
      throw cause;
    }
  },
};

/** Read the capture run token currently exposed by one live process. */
export const readProcessRunId = async (
  pid: number,
  host: ProcessOwnershipHost = systemHost,
): Promise<string | undefined> =>
  (await host.environment(pid)).REA_PROCESS_RUN_ID;

/** Token-validate every rooted POSIX process group before signaling any. */
export const cleanupOwnedProcessGroup = async (
  ownership: OwnedProcessGroup,
  host: ProcessOwnershipHost = systemHost,
): Promise<ProcessCleanupResult> => {
  const processTable = await readLiveProcessTable(host);
  if (!processTable.available)
    return {
      cleaned: false,
      reason: `process table could not be inspected: ${processTable.reason}`,
    };
  const plan = await createOwnedCleanupPlan(
    ownership,
    processTable.processes,
    host,
  );
  if ("cleaned" in plan) return plan;
  let signaled = false;
  for (const processGroupId of plan.signalOrder) {
    const revalidation = await revalidateOwnedProcessGroup(
      processGroupId,
      ownership,
      host,
      plan.tokenOwnedIdentities,
    );
    if ("cleaned" in revalidation) return revalidation;
    if (revalidation.empty) continue;
    try {
      host.signalGroup(processGroupId, "SIGKILL");
      signaled = true;
    } catch (cause: unknown) {
      const code =
        cause instanceof Error && "code" in cause ? cause.code : undefined;
      if (code !== "ESRCH")
        return {
          cleaned: false,
          reason: `owned process group signal failed: ${errorMessage(cause)}`,
        };
    }
  }
  if (plan.unresolved.length > 0)
    return cleanupValidationFailure(plan.unresolved, plan.unverified);
  return {
    cleaned: true,
    signaled,
    ...(plan.unverified.length === 0 ? {} : { unverified: plan.unverified }),
  };
};

/** Verify that no live process still carries an owned capture run token. */
export const verifyNoTokenOwnedProcesses = async (
  runId: string,
  host: ProcessOwnershipHost = systemHost,
  captureBaseline?: ProcessOwnershipBaseline,
  relation?: OwnershipSweepRelation,
): Promise<ProcessCleanupResult> => {
  const processTable = await readLiveProcessTable(host);
  if (!processTable.available)
    return {
      cleaned: false,
      reason: `process table could not be inspected: ${processTable.reason}`,
    };
  const scan = await scanTokenOwnedProcesses(
    processTable.processes,
    runId,
    host,
    captureBaseline,
    relation,
  );
  if (scan.failures.length > 0)
    return cleanupValidationFailure(scan.failures, scan.unverified);
  if (scan.owned.length > 0)
    return {
      cleaned: false,
      reason: "token-owned process remained after cleanup",
      ...(scan.unverified.length === 0 ? {} : { unverified: scan.unverified }),
    };
  return {
    cleaned: true,
    signaled: false,
    ...(scan.unverified.length === 0 ? {} : { unverified: scan.unverified }),
  };
};

const readLiveProcessTable = async (
  host: ProcessOwnershipHost,
): Promise<
  | {
      readonly available: true;
      readonly processes: readonly ProcessTableEntry[];
    }
  | { readonly available: false; readonly reason: string }
> => {
  try {
    return {
      available: true,
      processes: liveProcesses(await host.listProcesses()),
    };
  } catch (cause: unknown) {
    return { available: false, reason: errorMessage(cause) };
  }
};

interface OwnedCleanupPlan {
  readonly signalOrder: readonly number[];
  readonly tokenOwnedIdentities: ReadonlyMap<number, string | null>;
  readonly unresolved: readonly ProcessOwnershipValidationFailure[];
  readonly unverified: readonly OwnershipSweepUnverifiedProcess[];
}

// A process-table read can race exit and retain the old state with an altered
// command. Only a fresh table proving that PID is no longer live can settle
// that mismatch; surviving group members still require normal token checks.
const settleLauncherExit = async (
  ownership: OwnedProcessGroup,
  processes: readonly ProcessTableEntry[],
  host: ProcessOwnershipHost,
): Promise<
  | readonly ProcessTableEntry[]
  | Extract<ProcessCleanupResult, { readonly cleaned: false }>
> => {
  const launcher = processes.find(({ pid }) => pid === ownership.leaderPid);
  if (launcher === undefined) return processes;
  const reason = launcherIdentityFailure(launcher, ownership);
  if (reason === null) return processes;
  const refreshed = await readLiveProcessTable(host);
  if (
    refreshed.available &&
    !refreshed.processes.some(({ pid }) => pid === launcher.pid)
  ) {
    // Refreshing must not discard a surviving detached descendant's lineage,
    // including a child that changed groups while the launcher exited.
    const descendants = descendantsOf([launcher.pid], processes);
    const descendantPids = new Set(descendants.map(({ pid }) => pid));
    const descendantGroupIds = new Set(
      descendants.map(({ processGroupId }) => processGroupId),
    );
    const refreshedDescendantPids = new Set(
      descendantsOf(
        descendants.map(({ pid }) => pid),
        refreshed.processes,
      ).map(({ pid }) => pid),
    );
    if (
      refreshed.processes.some(
        (process) =>
          process.processGroupId !== ownership.processGroupId &&
          (refreshedDescendantPids.has(process.pid) ||
            descendantPids.has(process.pid) ||
            descendantGroupIds.has(process.processGroupId)),
      )
    )
      return { cleaned: false, reason };
    return refreshed.processes;
  }
  return { cleaned: false, reason };
};

const createOwnedCleanupPlan = async (
  ownership: OwnedProcessGroup,
  initialProcesses: readonly ProcessTableEntry[],
  host: ProcessOwnershipHost,
): Promise<OwnedCleanupPlan | ProcessCleanupResult> => {
  const processes = await settleLauncherExit(ownership, initialProcesses, host);
  if ("cleaned" in processes) return processes;
  const sampledProcessGroupIds = new Set(
    (ownership.sampledProcessGroupIds ?? []).filter(
      (processGroupId) =>
        Number.isSafeInteger(processGroupId) && processGroupId > 0,
    ),
  );
  const tokenOwned =
    ownership.sweepTokenOwnedProcesses === true
      ? await scanTokenOwnedProcesses(
          processes,
          ownership.runId,
          host,
          ownership.captureBaseline,
          {
            leaderPid: ownership.leaderPid,
            processGroupId: ownership.processGroupId,
            ...(sampledProcessGroupIds.size === 0
              ? {}
              : { sampledProcessGroupIds: [...sampledProcessGroupIds] }),
          },
        )
      : { owned: [], failures: [], unverified: [], identities: new Map() };
  const tokenOwnedGroupIds = new Set(
    tokenOwned.owned.map(({ processGroupId }) => processGroupId),
  );
  const launcher = processes.find(({ pid }) => pid === ownership.leaderPid);
  const rootMembers = processes.filter(
    ({ processGroupId }) => processGroupId === ownership.processGroupId,
  );
  if (
    launcher === undefined &&
    rootMembers.length === 0 &&
    tokenOwned.owned.length === 0 &&
    !processes.some(({ processGroupId }) =>
      sampledProcessGroupIds.has(processGroupId),
    )
  )
    return tokenOwned.failures.length > 0
      ? {
          signalOrder: [],
          tokenOwnedIdentities: tokenOwned.identities,
          unresolved: tokenOwned.failures,
          unverified: tokenOwned.unverified,
        }
      : {
          cleaned: true,
          signaled: false,
          ...(tokenOwned.unverified.length === 0
            ? {}
            : { unverified: tokenOwned.unverified }),
        };
  let descendants: readonly ProcessTableEntry[] = [];
  if (launcher !== undefined) {
    descendants = descendantsOf([launcher.pid], processes);
  }
  const descendantPids = new Set(descendants.map(({ pid }) => pid));
  const processGroupIds = new Set<number>([ownership.processGroupId]);
  for (const descendant of descendants)
    processGroupIds.add(descendant.processGroupId);
  for (const process of tokenOwned.owned)
    processGroupIds.add(process.processGroupId);
  for (const processGroupId of sampledProcessGroupIds)
    processGroupIds.add(processGroupId);
  const signalableGroups = new Set<number>();
  const unresolved = [...tokenOwned.failures];
  const unverifiableSampledGroups = new Set<number>();
  for (const processGroupId of processGroupIds) {
    if (processGroupId === ownership.processGroupId) continue;
    const groupLeader = processes.find(
      ({ pid, processGroupId: observedGroupId }) =>
        pid === processGroupId && observedGroupId === processGroupId,
    );
    if (
      (groupLeader === undefined || !descendantPids.has(groupLeader.pid)) &&
      !tokenOwnedGroupIds.has(processGroupId) &&
      !sampledProcessGroupIds.has(processGroupId)
    )
      return {
        cleaned: false,
        reason:
          "descendant process-group leader identity could not be verified",
      };
    if (
      (groupLeader === undefined || !descendantPids.has(groupLeader.pid)) &&
      !tokenOwnedGroupIds.has(processGroupId)
    )
      unverifiableSampledGroups.add(processGroupId);
  }
  const liveMembers = processes.filter(({ processGroupId }) =>
    processGroupIds.has(processGroupId),
  );
  for (const processGroupId of processGroupIds) {
    const members = liveMembers.filter(
      ({ processGroupId: observedGroupId }) =>
        observedGroupId === processGroupId,
    );
    if (members.length === 0) continue;
    const failures = await processOwnershipFailures(
      members,
      ownership.runId,
      host,
      tokenOwned.identities,
    );
    if (failures.length === 0 && unverifiableSampledGroups.has(processGroupId))
      unresolved.push(
        ...members.map(({ pid }) => ({
          pid,
          reason: "process-identity-unavailable" as const,
          diagnostic:
            "sampled process-group leader identity could not be verified",
        })),
      );
    const scanFailures = tokenOwned.failures.filter(({ pid }) =>
      members.some((member) => member.pid === pid),
    );
    if (failures.length > 0) unresolved.push(...failures);
    if (
      failures.length === 0 &&
      scanFailures.length === 0 &&
      !unverifiableSampledGroups.has(processGroupId)
    )
      signalableGroups.add(processGroupId);
  }
  if (ownership.sweepTokenOwnedProcesses !== true && unresolved.length > 0)
    return cleanupValidationFailure(unresolved, tokenOwned.unverified);
  return {
    signalOrder: [...signalableGroups]
      .filter((groupId) => processGroupIds.has(groupId))
      .sort((left, right) =>
        left === ownership.processGroupId
          ? -1
          : right === ownership.processGroupId
            ? 1
            : left - right,
      ),
    tokenOwnedIdentities: tokenOwned.identities,
    unresolved,
    unverified: tokenOwned.unverified,
  };
};

const revalidateOwnedProcessGroup = async (
  processGroupId: number,
  ownership: OwnedProcessGroup,
  host: ProcessOwnershipHost,
  expectedIdentities: ReadonlyMap<number, string | null>,
): Promise<{ readonly empty: boolean } | ProcessCleanupResult> => {
  let members: readonly ProcessTableEntry[];
  try {
    const processes = await settleLauncherExit(
      ownership,
      liveProcesses(await host.listProcesses()),
      host,
    );
    if ("cleaned" in processes) return processes;
    members = processes.filter(
      ({ processGroupId: observedGroupId }) =>
        observedGroupId === processGroupId,
    );
  } catch (cause: unknown) {
    return {
      cleaned: false,
      reason: `process ownership could not be revalidated: ${errorMessage(cause)}`,
    };
  }
  const failures = await processOwnershipFailures(
    members,
    ownership.runId,
    host,
    expectedIdentities,
  );
  if (failures.length > 0) return cleanupValidationFailure(failures);
  if (
    processGroupId !== ownership.processGroupId &&
    members.length > 0 &&
    !members.some(({ pid }) => pid === processGroupId) &&
    ownership.sweepTokenOwnedProcesses !== true
  )
    return {
      cleaned: false,
      reason:
        "descendant process-group leader identity could not be revalidated",
    };
  return { empty: members.length === 0 };
};

const cleanupValidationFailure = (
  failures: readonly ProcessOwnershipValidationFailure[],
  unverified: readonly OwnershipSweepUnverifiedProcess[] = [],
): ProcessCleanupResult => {
  const unverifiedEntry = unverified.length === 0 ? {} : { unverified };
  const unreadable = failures.filter(
    ({ reason }) => reason === "environment-unreadable",
  );
  if (failures.some(({ reason }) => reason === "run-token-mismatch"))
    return {
      cleaned: false,
      reason: `process ownership token mismatch for PID(s): ${[
        ...new Set(
          failures
            .filter(({ reason }) => reason === "run-token-mismatch")
            .map(({ pid }) => pid),
        ),
      ]
        .sort((left, right) => left - right)
        .join(", ")}`,
      failures,
      ...unverifiedEntry,
    };
  if (failures.some(({ reason }) => reason === "process-identity-unavailable"))
    return {
      cleaned: false,
      reason: "process identity could not be revalidated",
      failures,
      ...unverifiedEntry,
    };
  if (unreadable.length > 0) {
    const counts = new Map<string, number>();
    for (const { diagnostic } of unreadable) {
      const category = sanitizedTokenReadFailure(diagnostic);
      counts.set(category, (counts.get(category) ?? 0) + 1);
    }
    const breakdown = [...counts]
      .sort(([left], [right]) => left.localeCompare(right))
      .map(([category, count]) => `${category}=${String(count)}`)
      .join(", ");
    const candidates = unreadable
      .map(
        ({ pid, diagnostic }) =>
          `${String(pid)}=${sanitizedTokenReadFailure(diagnostic)}`,
      )
      .sort((left, right) => left.localeCompare(right));
    return {
      cleaned: false,
      reason: `process ownership token could not be read for ${String(unreadable.length)} live process(es): ${breakdown}; live candidates ${candidates.join(", ")}`,
      failures,
      ...unverifiedEntry,
    };
  }
  return {
    cleaned: false,
    reason: "process ownership could not be revalidated",
    failures,
    ...unverifiedEntry,
  };
};

const sanitizedTokenReadFailure = (diagnostic: string | undefined): string => {
  if (diagnostic === "environment_unavailable") return diagnostic;
  if (diagnostic === "platform_binary_environment_withheld") return diagnostic;
  const environmentErrno = /^(EACCES|EPERM|ENOENT|ESRCH):/u.exec(
    diagnostic ?? "",
  );
  if (environmentErrno?.[1] !== undefined)
    return `environment_errno_${environmentErrno[1]}`;
  if (diagnostic === "apple_vector_unavailable") return diagnostic;
  if (diagnostic === "ambiguous_environment_boundary") return diagnostic;
  if (diagnostic === "malformed_procargs") return diagnostic;
  if (diagnostic === "process_identity_changed_during_token_read")
    return diagnostic;
  if (diagnostic === "process_not_in_snapshot") return diagnostic;
  const processTableFailure = /^process_table_failed_(\d+)$/u.exec(
    diagnostic ?? "",
  );
  if (processTableFailure?.[1] !== undefined)
    return `process_table_errno_${processTableFailure[1]}`;
  const sysctlFailure = /^sysctl_failed_(\d+)$/u.exec(diagnostic ?? "");
  if (sysctlFailure?.[1] !== undefined)
    return `sysctl_errno_${sysctlFailure[1]}`;
  if (diagnostic === "reader_failure") return diagnostic;
  if (diagnostic === "duplicate_run_token") return diagnostic;
  if (diagnostic === "invalid_run_token_encoding") return diagnostic;
  return "other_unavailable";
};

const processOwnershipFailures = async (
  members: readonly ProcessTableEntry[],
  runId: string,
  host: ProcessOwnershipHost,
  expectedIdentities: ReadonlyMap<number, string | null> = new Map(),
): Promise<readonly ProcessOwnershipValidationFailure[]> => {
  const failures: ProcessOwnershipValidationFailure[] = [];
  if (expectedIdentities.size > 0 && host.processIdentities !== undefined) {
    const expectedMembers = members.filter(({ pid }) =>
      expectedIdentities.has(pid),
    );
    const observed = await host.processIdentities(expectedMembers);
    const identityFailures: ProcessOwnershipValidationFailure[] = [];
    for (const member of expectedMembers) {
      const expected = expectedIdentities.get(member.pid);
      const current = observed.get(member.pid);
      if (
        expected === null ||
        current?.state !== "readable" ||
        current.identity !== expected
      ) {
        identityFailures.push({
          pid: member.pid,
          reason: "process-identity-unavailable",
          diagnostic:
            "process identity changed or became unavailable before signal",
        });
      }
    }
    failures.push(...(await recheckOwnershipFailures(identityFailures, host)));
  }
  failures.push(...(await processRunTokenFailures(members, runId, host)));
  if (
    failures.length === 0 &&
    expectedIdentities.size > 0 &&
    host.processIdentities !== undefined
  ) {
    const expectedMembers = members.filter(({ pid }) =>
      expectedIdentities.has(pid),
    );
    const observed = await host.processIdentities(expectedMembers);
    const identityFailures: ProcessOwnershipValidationFailure[] = [];
    for (const member of expectedMembers) {
      const expected = expectedIdentities.get(member.pid);
      const current = observed.get(member.pid);
      if (
        expected !== null &&
        current?.state === "readable" &&
        current.identity === expected
      )
        continue;
      identityFailures.push({
        pid: member.pid,
        reason: "process-identity-unavailable",
        diagnostic:
          "process identity changed or became unavailable during token validation",
      });
    }
    failures.push(...(await recheckOwnershipFailures(identityFailures, host)));
  }
  return failures;
};

const processRunTokenFailures = async (
  members: readonly ProcessTableEntry[],
  runId: string,
  host: ProcessOwnershipHost,
): Promise<readonly ProcessOwnershipValidationFailure[]> => {
  const failures: ProcessOwnershipValidationFailure[] = [];
  for await (const { process: member, observation } of readProcessRunTokens(
    host,
    members,
  )) {
    if (observation.state === "readable") {
      if (observation.runId !== runId)
        failures.push({ pid: member.pid, reason: "run-token-mismatch" });
      continue;
    }
    failures.push({
      pid: member.pid,
      reason: "environment-unreadable",
      diagnostic: observation.reason,
    });
  }
  return recheckOwnershipFailures(failures, host);
};

/**
 * Take a fresh liveness snapshot after each ownership-read phase. Only an
 * absent PID resolves an unreadable observation; a readable token mismatch
 * remains a failure. Never reuse this snapshot across identity/token reads.
 */
const recheckOwnershipFailures = async (
  failures: readonly ProcessOwnershipValidationFailure[],
  host: ProcessOwnershipHost,
): Promise<readonly ProcessOwnershipValidationFailure[]> => {
  if (!failures.some(({ reason }) => reason !== "run-token-mismatch"))
    return failures;
  try {
    const live = new Set(
      liveProcesses(await host.listProcesses()).map(({ pid }) => pid),
    );
    return failures.filter(
      ({ pid, reason }) => reason === "run-token-mismatch" || live.has(pid),
    );
  } catch (cause: unknown) {
    return failures.map((failure) =>
      failure.reason === "run-token-mismatch"
        ? failure
        : {
            ...failure,
            diagnostic: `${failure.diagnostic}; process liveness recheck failed: ${errorMessage(cause)}`,
          },
    );
  }
};

interface TokenOwnedProcessScan {
  readonly owned: readonly ProcessTableEntry[];
  readonly failures: readonly ProcessOwnershipValidationFailure[];
  readonly unverified: readonly OwnershipSweepUnverifiedProcess[];
  readonly identities: ReadonlyMap<number, string | null>;
}

/** One sweep candidate whose run token could not be read. */
interface UnreadableTokenCandidate {
  readonly process: ProcessTableEntry;
  readonly diagnostic: string;
}

const TOKEN_READ_RETRY_ATTEMPTS = 3;
const TOKEN_READ_RETRY_DELAY_MS = 40;

/** Darwin reports this when the kernel withholds a platform binary's environment. */
const PLATFORM_BINARY_ENVIRONMENT_WITHHELD =
  "platform_binary_environment_withheld";

const currentProcessUid = (): number | undefined =>
  typeof process.getuid === "function" ? process.getuid() : undefined;

/**
 * Whether the operating system provably withheld this candidate's run token:
 * current macOS omits the environment of Apple platform binaries from
 * KERN_PROCARGS2 and fails with EINVAL for processes owned by another
 * account, and neither class can be token-verified by any caller. Such a
 * candidate is recorded as unverified instead of failing an otherwise clean
 * capture; every other unreadable candidate stays fail-closed.
 */
const environmentWithheldFromInspection = (
  entry: ProcessTableEntry,
  diagnostic: string,
): boolean => {
  const uid = currentProcessUid();
  if (uid !== undefined && entry.uid !== undefined && entry.uid !== uid)
    return true;
  return diagnostic === PLATFORM_BINARY_ENVIRONMENT_WITHHELD;
};

const scanTokenOwnedProcesses = async (
  processes: readonly ProcessTableEntry[],
  runId: string,
  host: ProcessOwnershipHost,
  captureBaseline?: ProcessOwnershipBaseline,
  relation?: OwnershipSweepRelation,
): Promise<TokenOwnedProcessScan> => {
  let candidates = processes;
  let candidateIdentities: ReadonlyMap<number, ProcessIdentityObservation> =
    new Map();
  if (host.processIdentities !== undefined) {
    const current = await host.processIdentities(processes);
    candidateIdentities = current;
    if (captureBaseline !== undefined) {
      const baseline = new Map(
        captureBaseline.map(({ pid, identity }) => [pid, identity]),
      );
      candidates = processes.filter((process) => {
        const before = baseline.get(process.pid);
        const now = current.get(process.pid);
        return !(
          before !== undefined &&
          before !== null &&
          now?.state === "readable" &&
          now.identity === before
        );
      });
    }
  }
  const failures: ProcessOwnershipValidationFailure[] = [];
  if (captureBaseline !== undefined && host.processIdentities !== undefined) {
    const stableCandidates: ProcessTableEntry[] = [];
    const identityFailures: ProcessOwnershipValidationFailure[] = [];
    for (const process of candidates) {
      if (candidateIdentities.get(process.pid)?.state === "readable") {
        stableCandidates.push(process);
        continue;
      }
      identityFailures.push({
        pid: process.pid,
        reason: "process-identity-unavailable",
        diagnostic: "process identity was unavailable during token scan",
      });
    }
    failures.push(...(await recheckOwnershipFailures(identityFailures, host)));
    candidates = stableCandidates;
  }
  const owned: ProcessTableEntry[] = [];
  const ownedIdentities = new Map<number, string | null>();
  const recordOwned = (process: ProcessTableEntry): void => {
    owned.push(process);
    const identity = candidateIdentities.get(process.pid);
    ownedIdentities.set(
      process.pid,
      identity?.state === "readable" ? identity.identity : null,
    );
  };
  const unreadable: UnreadableTokenCandidate[] = [];
  for await (const { process, observation } of readProcessRunTokens(
    host,
    candidates,
  )) {
    if (observation.state === "readable") {
      if (observation.runId === runId) recordOwned(process);
    } else unreadable.push({ process, diagnostic: observation.reason });
  }
  const remaining = await settleUnreadableTokenCandidates(
    unreadable,
    runId,
    host,
    recordOwned,
  );
  const relatedPids = new Set<number>();
  const relatedGroupIds = new Set<number>();
  if (relation !== undefined) {
    relatedPids.add(relation.leaderPid);
    for (const descendant of descendantsOf([relation.leaderPid], processes))
      relatedPids.add(descendant.pid);
    relatedGroupIds.add(relation.processGroupId);
    for (const processGroupId of relation.sampledProcessGroupIds ?? [])
      if (Number.isSafeInteger(processGroupId) && processGroupId > 0)
        relatedGroupIds.add(processGroupId);
    for (const process of owned) relatedGroupIds.add(process.processGroupId);
  }
  const unverified: OwnershipSweepUnverifiedProcess[] = [];
  const strict: UnreadableTokenCandidate[] = [];
  const withheld: UnreadableTokenCandidate[] = [];
  for (const candidate of remaining) {
    const isRelated =
      relation === undefined ||
      relatedPids.has(candidate.process.pid) ||
      relatedGroupIds.has(candidate.process.processGroupId);
    if (
      !isRelated &&
      environmentWithheldFromInspection(candidate.process, candidate.diagnostic)
    ) {
      withheld.push(candidate);
      continue;
    }
    strict.push(candidate);
  }
  let finalLive: ReadonlySet<number> | undefined;
  try {
    finalLive = new Set(
      liveProcesses(await host.listProcesses()).map(({ pid }) => pid),
    );
  } catch (cause: unknown) {
    void cause;
    finalLive = undefined;
  }
  for (const candidate of strict) {
    if (finalLive !== undefined && !finalLive.has(candidate.process.pid))
      continue;
    failures.push({
      pid: candidate.process.pid,
      reason: "environment-unreadable",
      diagnostic: candidate.diagnostic,
    });
  }
  for (const candidate of withheld) {
    if (finalLive !== undefined && !finalLive.has(candidate.process.pid))
      continue;
    unverified.push({
      pid: candidate.process.pid,
      diagnostic: candidate.diagnostic,
    });
  }
  if (candidates.length > 0 && host.processIdentities !== undefined) {
    const afterRead = await host.processIdentities(candidates);
    const stillOwned: ProcessTableEntry[] = [];
    const identityFailures: ProcessOwnershipValidationFailure[] = [];
    const ownedPids = new Set(owned.map(({ pid }) => pid));
    for (const process of candidates) {
      const before = candidateIdentities.get(process.pid);
      const current = afterRead.get(process.pid);
      if (
        before?.state === "readable" &&
        current?.state === "readable" &&
        current.identity === before.identity
      ) {
        if (ownedPids.has(process.pid)) stillOwned.push(process);
        continue;
      }
      identityFailures.push({
        pid: process.pid,
        reason: "process-identity-unavailable",
        diagnostic:
          "process identity changed or became unavailable during token validation",
      });
    }
    failures.push(...(await recheckOwnershipFailures(identityFailures, host)));
    return {
      owned: stillOwned,
      failures,
      unverified,
      identities: ownedIdentities,
    };
  }
  return { owned, failures, unverified, identities: ownedIdentities };
};

/**
 * Re-read run tokens for unresolved sweep candidates so transient exec and
 * exit states settle before classification. Each attempt revalidates
 * liveness, refreshes the diagnostic, and is bounded by a fixed attempt
 * budget; a still-unreadable candidate keeps its latest diagnostic.
 */
const settleUnreadableTokenCandidates = async (
  pending: readonly UnreadableTokenCandidate[],
  runId: string,
  host: ProcessOwnershipHost,
  recordOwned: (process: ProcessTableEntry) => void,
): Promise<readonly UnreadableTokenCandidate[]> => {
  let remaining = pending;
  for (
    let attempt = 0;
    attempt < TOKEN_READ_RETRY_ATTEMPTS && remaining.length > 0;
    attempt += 1
  ) {
    await new Promise<void>((resolve) =>
      setTimeout(resolve, TOKEN_READ_RETRY_DELAY_MS),
    );
    let live: ReadonlySet<number> | undefined;
    try {
      live = new Set(
        liveProcesses(await host.listProcesses()).map(({ pid }) => pid),
      );
    } catch (cause: unknown) {
      void cause;
      live = undefined;
    }
    const stillUnreadable: UnreadableTokenCandidate[] = [];
    const candidates = remaining
      .map(({ process }) => process)
      .filter(({ pid }) => live === undefined || live.has(pid));
    for await (const { process, observation } of readProcessRunTokens(
      host,
      candidates,
    )) {
      if (observation.state === "readable") {
        if (observation.runId === runId) recordOwned(process);
        continue;
      }
      stillUnreadable.push({
        process,
        diagnostic: observation.reason,
      });
    }
    remaining = stillUnreadable;
  }
  return remaining;
};