@hienlh/ppm 0.23.6 → 0.23.8

package/src/services/system-metrics/system-metrics-tick.ts

@@ -5,12 +5,16 @@
  * can then never leave a half-advanced baseline behind.
  */
 import type {
-  MetricsPlatform, MetricsSnapshot, MetricsTier, MemoryMetrics, ProcessColumnAvailability, SystemMetrics,
+  MetricsPlatform, MetricsSnapshot, MetricsTier, MemoryMetrics, ProcessColumnAvailability, ProcessSignal, SystemMetrics,
 } from "../../types/system-metrics.ts";
 import { METRICS_INTERVAL_MS, METRICS_LIGHT_INTERVAL_MS } from "../../types/system-metrics.ts";
-import { computeCpuFromSamples, type CpuTimesSample } from "./cpu-memory-collector.ts";
+import { computeCpuFromSamples, hostUptimeSec, type CpuTimesSample } from "./cpu-memory-collector.ts";
 import { toRate, UNAVAILABLE_RATE, type CounterSample } from "./rate-delta.ts";
 import type { DiskNetCounters } from "./disk-net-collector-linux.ts";
+import type { AppInfo } from "../../types/system-metrics.ts";
+import type { AppCollector } from "../system-services/apps-linux.ts";
+import type { DeviceCollector, DeviceSampleState } from "./device-collector-types.ts";
+import { EMPTY_DEVICE_STATE } from "./device-collector-types.ts";
 import type { GpuCollector } from "./gpu-collector-nvidia.ts";
 import type { ProcessCollection, ProcessCollector } from "./process-collector-types.ts";
 import { NO_PROCESS_COLUMNS } from "./process-collector-types.ts";
@@ -26,9 +30,13 @@ export interface TickDeltaState {
   net: CounterSample | null;
   procCpu: CpuDeltaState | null;
   procIo: ProcIoDeltaState | null;
+  /** Per-device counters, keyed by device id — one baseline each. */
+  devices: DeviceSampleState;
 }
 
-export const EMPTY_DELTA_STATE: TickDeltaState = { cpu: null, disk: null, net: null, procCpu: null, procIo: null };
+export const EMPTY_DELTA_STATE: TickDeltaState = {
+  cpu: null, disk: null, net: null, procCpu: null, procIo: null, devices: EMPTY_DEVICE_STATE,
+};
 
 export interface TickDeps {
   platform: MetricsPlatform;
@@ -37,6 +45,14 @@ export interface TickDeps {
   /** Null on win32 — the counters ride along in the process round trip. */
   diskNet: (() => Promise<DiskNetCounters>) | null;
   gpus: GpuCollector;
+  /** Null where this host lists no drives or interfaces of its own. */
+  devices: DeviceCollector | null;
+  /** Signals this host can actually deliver, published so the client builds its
+   *  Send-Signal menu from the host instead of guessing from the platform name.
+   *  Omitted → published as absent, which an older client already tolerates. */
+  signals?: readonly ProcessSignal[];
+  /** Desktop applications. Omitted or null on a host that lists none. */
+  apps?: AppCollector | null;
   resolveProtected: BuildRowsInput["resolveProtected"];
   now: () => number;
   sampleCpu: (now: number) => CpuTimesSample;
@@ -65,6 +81,9 @@ export async function assembleTick(
   const now = deps.now();
   const cpuSample = deps.sampleCpu(now);
   const cpu = computeCpuFromSamples(state.cpu, cpuSample);
+  // Set before `collectDevices`, which merges Linux's own `/proc/uptime` over it.
+  const uptimeSec = hostUptimeSec();
+  if (uptimeSec !== undefined) cpu.uptimeSec = uptimeSec;
   const mem = deps.memory();
   const warnings: string[] = [];
 
@@ -75,6 +94,9 @@ export async function assembleTick(
   let groups: MetricsSnapshot["groups"] = [];
   let processes: MetricsSnapshot["processes"] = [];
   let processColumns: ProcessColumnAvailability = NO_PROCESS_COLUMNS;
+  // Undefined means "this server does not list apps"; an empty array means "it
+  // does, and none are running". The UI hides the page only for the first.
+  let apps: AppInfo[] | undefined;
   let guardCtx: KillGuardContext | null = null;
 
   if (tier === "full") {
@@ -89,6 +111,7 @@ export async function assembleTick(
       nextState.net = counters.net;
     }
     system.gpus = await deps.gpus.collect();
+    collectDevices(system, nextState, deps, warnings);
 
     if (collection) {
       const built = buildProcessRows({
@@ -113,6 +136,14 @@ export async function assembleTick(
       // Re-published rows keep the columns they were measured with.
       processColumns = previousFull.processColumns;
     }
+    if (collection && deps.apps) {
+      try {
+        apps = deps.apps(collection.rows);
+      } catch (e) {
+        // One unreadable cgroup must cost the app list, never the snapshot.
+        warnings.push(`App list unavailable this tick: ${(e as Error)?.message ?? String(e)}`);
+      }
+    }
     system.processCount = processes.length;
   }
 
@@ -127,6 +158,10 @@ export async function assembleTick(
     processColumns,
     total: { cpu: cpu.total, ramMB: mem.usedMB, processCount: system.processCount },
     warnings,
+    // Only in the tier that has process rows to act on, and only when this host
+    // can deliver something — an empty menu is the same information as no menu.
+    signals: tier === "full" && deps.signals?.length ? [...deps.signals] : undefined,
+    apps,
   };
   return { snapshot, nextState, guardCtx };
 }
@@ -136,14 +171,48 @@ export function projectLight(full: MetricsSnapshot): MetricsSnapshot {
   return {
     ...full,
     tier: "light",
-    system: { ...full.system, disk: UNAVAILABLE_RATE, net: UNAVAILABLE_RATE, gpus: [], processCount: 0 },
+    system: {
+      ...full.system,
+      disk: UNAVAILABLE_RATE, net: UNAVAILABLE_RATE, gpus: [], processCount: 0,
+      disks: undefined, nics: undefined, fans: undefined,
+    },
     groups: [],
     processes: [],
     processColumns: NO_PROCESS_COLUMNS,
+    // Everything that only means something beside a process row goes with them.
+    signals: undefined,
+    apps: undefined,
     total: { ...full.total, processCount: 0 },
   };
 }
 
+/** Per-device figures are best-effort: a `/sys` read failing must cost the drive
+ *  and interface lists, never the whole snapshot. The baseline is only advanced
+ *  when the call returned, so a failed tick re-measures from the last good one. */
+function collectDevices(
+  system: SystemMetrics,
+  nextState: TickDeltaState,
+  deps: TickDeps,
+  warnings: string[],
+): void {
+  if (!deps.devices) return;
+  try {
+    const collected = deps.devices(nextState.devices);
+    system.disks = collected.disks;
+    system.nics = collected.nics;
+    if (collected.fans.length > 0) system.fans = collected.fans;
+    // Appended, not replaced: nvidia-smi covers the one driver sysfs cannot, and
+    // `collectLinuxGpus` deliberately skips those cards so neither is listed twice.
+    if (collected.gpus.length > 0) system.gpus = [...system.gpus, ...collected.gpus];
+    // Merged, never assigned: `cpu` already holds the cross-platform busy figures
+    // computed from the os.cpus() delta, which this collector does not measure.
+    Object.assign(system.cpu, collected.cpu);
+    nextState.devices = collected.next;
+  } catch (e) {
+    warnings.push(`Per-device figures unavailable this tick: ${(e as Error)?.message ?? String(e)}`);
+  }
+}
+
 /** Null means the collection FAILED (as opposed to a legitimately empty table). */
 async function collectProcessesSafely(collector: ProcessCollector, warnings: string[]): Promise<ProcessCollection | null> {
   try {

package/src/services/system-metrics/system-metrics.service.ts

@@ -9,16 +9,23 @@
  * queries run only while ≥1 full subscriber exists, and the child is torn down
  * 60 s after the last one leaves (a window reopen then skips the bootstrap).
  */
-import type { KillProcessResult, MetricsSnapshot, MetricsTier } from "../../types/system-metrics.ts";
+import type {
+  KillProcessResult, MetricsPlatform, MetricsSnapshot, MetricsTier, ProcessDetails, ProcessSignal, SignalProcessResult,
+} from "../../types/system-metrics.ts";
 import { METRICS_INTERVAL_MS, METRICS_LEASE_TIMEOUT_MS, METRICS_LIGHT_INTERVAL_MS } from "../../types/system-metrics.ts";
 import { collectMemory, sampleCpuTimes } from "./cpu-memory-collector.ts";
 import { assembleTick, EMPTY_DELTA_STATE, projectLight, type TickDeltaState, type TickDeps } from "./system-metrics-tick.ts";
+import { EMPTY_DEVICE_STATE } from "./device-collector-types.ts";
 import { createPlatformCollectors, type PlatformCollectors } from "./system-metrics-platform.ts";
 import { resolveProtectedPidsLive } from "./ppm-protected-pids.ts";
 import { SubscriberRegistry, type MetricsSubscriber } from "./metrics-subscriber-registry.ts";
 import { PollScheduler, installProcessExitHooks } from "./metrics-poll-scheduler.ts";
 import { handleKillRequest, type KillOutcome } from "./kill-request-handler.ts";
 import { executeKill } from "./kill-executor.ts";
+import { handleSignalRequest, type SignalOutcome } from "./signal-request-handler.ts";
+import { executeSignal, supportedSignals } from "./signal-executor.ts";
+import { readProcessDetails } from "./process-details-linux.ts";
+import { readProcessDetailsDarwin } from "./process-details-darwin.ts";
 import { CollectorLock } from "./metrics-collector-lock.ts";
 
 /** Over a proxy a closed window's lease lives until the reap; 8 leaves room for
@@ -35,11 +42,27 @@ export interface SystemMetricsServiceOptions {
   now?: () => number;
   resolveProtected?: TickDeps["resolveProtected"];
   execute?: (pid: number, tree: boolean) => Promise<KillProcessResult>;
+  executeSignal?: (pid: number, signal: ProcessSignal, tree: boolean) => Promise<SignalProcessResult>;
+  /** Injected in tests so a unit test never reads the real /proc. Explicit
+   *  `null` models a host with no reader for this at all. */
+  details?: DetailsReader | null;
   log?: (line: string) => void;
   /** Register process exit/signal teardown of children (off in unit tests). */
   exitHooks?: boolean;
 }
 
+/** A reader may answer synchronously (Linux reads files) or not (macOS shells
+ *  out), so the service awaits whatever it gets. */
+export type DetailsReader = (pid: number) => ProcessDetails | null | Promise<ProcessDetails | null>;
+
+/** Null where PPM has no reader yet — currently win32, whose Details dialog says
+ *  so rather than reporting every process as exited. */
+function detailsReaderFor(platform: MetricsPlatform): DetailsReader | null {
+  if (platform === "linux") return (pid) => readProcessDetails(pid);
+  if (platform === "darwin") return (pid) => readProcessDetailsDarwin(pid);
+  return null;
+}
+
 export type SubscribeInit = Pick<MetricsSubscriber, "tier" | "deliver" | "close">;
 export interface SubscribeResult { sid: string; tier: MetricsTier; intervalMs: number }
 
@@ -52,6 +75,8 @@ export class SystemMetricsService {
   private readonly now: () => number;
   private readonly tickDeps: TickDeps;
   private readonly execute: NonNullable<SystemMetricsServiceOptions["execute"]>;
+  private readonly signalExecutor: NonNullable<SystemMetricsServiceOptions["executeSignal"]>;
+  private readonly details: DetailsReader | null;
   private readonly log: (line: string) => void;
   private readonly exitHooks: boolean;
 
@@ -66,6 +91,8 @@ export class SystemMetricsService {
     this.leaseTimeoutMs = opts.leaseTimeoutMs ?? METRICS_LEASE_TIMEOUT_MS;
     this.now = opts.now ?? Date.now;
     this.execute = opts.execute ?? executeKill;
+    this.signalExecutor = opts.executeSignal ?? executeSignal;
+    this.details = opts.details !== undefined ? opts.details : detailsReaderFor(this.collectors.platform);
     this.log = opts.log ?? ((line) => console.log(line));
     this.exitHooks = opts.exitHooks ?? true;
     this.tickDeps = {
@@ -74,6 +101,9 @@ export class SystemMetricsService {
       processes: this.collectors.processes,
       diskNet: this.collectors.diskNet,
       gpus: this.collectors.gpus,
+      devices: this.collectors.devices,
+      signals: this.signalMenu(),
+      apps: this.collectors.apps,
       resolveProtected: opts.resolveProtected ?? resolveProtectedPidsLive,
       now: this.now,
       sampleCpu: sampleCpuTimes,
@@ -152,6 +182,59 @@ export class SystemMetricsService {
     }
   }
 
+  /**
+   * Delivers one signal, through exactly the chain a kill uses — including the
+   * collector lock, because it re-collects the process table to authorise
+   * against a FRESH name and the PowerShell session takes one request at a time.
+   */
+  async signal(body: unknown): Promise<SignalOutcome> {
+    this.ensureExitHooks();
+    try {
+      return await this.collectorLock.runExclusive(() => handleSignalRequest(body, {
+        platform: this.collectors.platform,
+        collector: this.collectors.processes,
+        resolveProtected: this.tickDeps.resolveProtected,
+        execute: this.signalExecutor,
+        supported: this.signalMenu(),
+        log: this.log,
+      }));
+    } finally {
+      // The re-query may have started the PowerShell child with no window open.
+      if (this.registry.count("full") === 0) this.scheduler.armIdle();
+    }
+  }
+
+  /**
+   * Facts for the Details dialog. Deliberately NOT behind the collector lock: it
+   * is a handful of /proc reads sharing nothing with a tick or a kill, and
+   * queueing it there would make the dialog wait out a 174 ms Windows tick for
+   * data that tick does not even produce.
+   */
+  async processDetails(pid: number): Promise<ProcessDetails | null> {
+    return this.details ? await this.details(pid) : null;
+  }
+
+  /**
+   * Whether this host has any reader for that dialog at all.
+   *
+   * The caller needs it because `null` from `processDetails` would otherwise
+   * carry two unrelated meanings: "that pid has exited" and "PPM cannot read
+   * process details here". Collapsing them is what made the dialog tell a macOS
+   * user that a process consuming 4% of the CPU was no longer running.
+   */
+  supportsProcessDetails(): boolean {
+    return this.details !== null;
+  }
+
+  /** What this host can deliver. Read through a plain string because the platform
+   *  union says which COLLECTOR runs, not whether signals exist. */
+  private signalMenu(): ProcessSignal[] {
+    const p: string = this.collectors.platform;
+    if (p === "linux" || p === "darwin") return supportedSignals("linux");
+    if (p === "win32") return supportedSignals("win32");
+    return [];
+  }
+
   /** One poll: assemble for the active tier, commit the baseline, publish. */
   async runTick(): Promise<void> {
     // A Windows tick is ~174 ms and can slip, and a kill re-collects through the
@@ -196,7 +279,9 @@ export class SystemMetricsService {
     const changed = this.scheduler.reconcile(this.registry.count("full"), this.registry.count("light"));
     // Leaving the full tier: its baselines would be stale by the time it resumes.
     if (changed && this.scheduler.activeTier() !== "full") {
-      this.state = { ...this.state, procCpu: null, procIo: null, disk: null, net: null };
+      this.state = {
+        ...this.state, procCpu: null, procIo: null, disk: null, net: null, devices: EMPTY_DEVICE_STATE,
+      };
     }
   }
 

package/src/services/system-metrics/udev-db.ts

@@ -0,0 +1,40 @@
+/**
+ * systemd-udevd's device database, `/run/udev/data/<device>`: one `E:KEY=VALUE`
+ * line per property, world-readable. It already holds what `lspci`, `lsblk` and
+ * `dmidecode` would be spawned for — adapter names from the PCI/USB hwdb, drive
+ * models and serials, and DIMM facts from the SMBIOS table, whose raw file
+ * (/sys/firmware/dmi/tables/DMI) is root-only. Reading it costs one small file
+ * read and needs neither root nor a subprocess.
+ *
+ * Device file names: `+pci:<address>`, `b<major>:<minor>` for a block device,
+ * `n<ifindex>` for a network interface, `+dmi:id` for the SMBIOS table.
+ */
+import type { FileReader } from "./linux-fs.ts";
+
+export const UDEV_DATA_DIR = "/run/udev/data";
+
+/** `E:` lines only; values are taken verbatim (udev already decoded `\x20`-style
+ *  escapes into the plain keys, the `_ENC` variants keep them). */
+export function parseUdevProperties(text: string): Map<string, string> {
+  const props = new Map<string, string>();
+  for (const line of text.split("\n")) {
+    if (!line.startsWith("E:")) continue;
+    const eq = line.indexOf("=", 2);
+    if (eq < 0) continue;
+    props.set(line.slice(2, eq), line.slice(eq + 1));
+  }
+  return props;
+}
+
+/** Properties of one device, or an empty map when udev has no record of it (no
+ *  udevd in a container, a device that appeared before udev started). */
+export function readUdevProperties(device: string, read: FileReader): Map<string, string> {
+  const text = read(`${UDEV_DATA_DIR}/${device}`);
+  return text ? parseUdevProperties(text) : new Map();
+}
+
+/** A non-empty trimmed value, or undefined — hwdb fields are sometimes padded. */
+export function udevValue(props: ReadonlyMap<string, string>, key: string): string | undefined {
+  const v = props.get(key)?.trim();
+  return v ? v : undefined;
+}

package/src/services/system-services/app-cgroup-linux.ts

@@ -0,0 +1,115 @@
+/**
+ * Which desktop app a pid belongs to, read from its systemd app cgroup.
+ *
+ * This is why PPM's Apps page needs no heuristics: a graphical session started by
+ * systemd puts every app in its own app scope or app service, and the unit name
+ * states the desktop-entry id rather than leaving it to be inferred from an
+ * executable path. Measured on a 560-process desktop, reading every
+ * `/proc/<pid>/cgroup` costs 2.8 ms, which the 2 s tick can afford.
+ *
+ * Pure. The caller supplies the file text.
+ */
+
+/** systemd escapes a character it cannot put in a unit name as a hex escape. */
+export function unescapeSystemd(value: string): string {
+  return value.replace(/\\x([0-9a-fA-F]{2})/g, (_match, hex: string) =>
+    String.fromCharCode(Number.parseInt(hex, 16)));
+}
+
+/**
+ * The desktop-entry id owning this pid, or null when it is not in an app scope -
+ * a daemon, a kernel thread, anything started before the session.
+ *
+ * Four shapes appear on a real KDE/systemd desktop and all are handled here: a
+ * scope with the launching pid appended, a scope whose id contains dots, a
+ * service with a launch hash after an at-sign, and an autostart service whose id
+ * was hex-escaped.
+ *
+ * The OUTERMOST app unit wins: an app service can contain further scopes, and the
+ * wrapper is the one naming the app.
+ */
+export function appIdFromCgroup(cgroup: string): string | null {
+  const match = /(?:^|\/)app-([^/]+?)\.(?:scope|service)(?:\/|$)/m.exec(cgroup);
+  const raw = match?.[1];
+  if (!raw) return null;
+  const at = raw.indexOf("@");
+  // The at-sign introduces systemd's instance part (a launch hash, or the word
+  // autostart); without one the launcher appends the pid instead. Never both.
+  const trimmed = at >= 0 ? raw.slice(0, at) : raw.replace(/-\d+$/, "");
+  const id = unescapeSystemd(trimmed).trim();
+  return id || null;
+}
+
+/**
+ * Unit suffixes that can own processes. `.slice` is deliberately absent: a slice
+ * is a grouping, and attributing a pid to `user.slice` would roll every user
+ * process into one row that names nothing anybody can act on.
+ */
+const UNIT_SUFFIXES = [".service", ".scope", ".socket", ".mount", ".swap"] as const;
+
+/**
+ * The systemd unit owning this pid, suffix included, or null when it is in no
+ * unit at all (the root slice, a kernel thread).
+ *
+ * The INNERMOST unit wins, which is `systemd-cgls`'s own answer: a user service
+ * nests under `user@1000.service`, and reporting the wrapper would put every
+ * desktop process on one row.
+ *
+ * The name is taken verbatim, escapes included — `systemctl list-units` reports
+ * `dev-disk-by\x2duuid-….swap` the same way, and a name unescaped here would
+ * match no row on the Services page.
+ */
+export function unitFromCgroup(cgroup: string): string | null {
+  const path = systemdHierarchy(cgroup);
+  if (!path) return null;
+  const segments = path.split("/").filter(Boolean);
+  for (let i = segments.length - 1; i >= 0; i--) {
+    const segment = segments[i]!;
+    if (UNIT_SUFFIXES.some((suffix) => segment.endsWith(suffix))) return segment;
+  }
+  return null;
+}
+
+/**
+ * The cgroup path systemd tracks units in. Under v2 that is the single `0::`
+ * line; under v1 it is whichever controller line is `name=systemd`, and reading
+ * any other one (`cpu`, `memory`) gives a hierarchy that need not agree.
+ */
+export function systemdHierarchy(cgroup: string): string | null {
+  for (const line of cgroup.split("\n")) {
+    const first = line.indexOf(":");
+    if (first < 0) continue;
+    const second = line.indexOf(":", first + 1);
+    if (second < 0) continue;
+    const controllers = line.slice(first + 1, second);
+    if (controllers === "" || controllers === "name=systemd") return line.slice(second + 1).trim() || null;
+  }
+  return null;
+}
+
+/**
+ * `"<scope>:<unit>"` — the key the Services page rows are identified by, or null
+ * when this pid belongs to no row it can show.
+ *
+ * The scope is not decoration. `dbus-broker.service` exists in BOTH scopes on
+ * this dev host, so a roll-up keyed by the unit name alone would add a user
+ * session's processes to the system unit's row and show one figure for two
+ * different units.
+ *
+ * A user unit belonging to somebody ELSE returns null rather than that user's
+ * unit name: PPM reads `systemctl --user` as its own user, so another uid's
+ * units are not on the page at all, and attributing their processes to the
+ * same-named row of ours would be a wrong reading rather than a missing one.
+ *
+ * Being under `/user.slice/` is NOT what makes a unit a user one — `session-2.scope`
+ * and `user@1000.service` itself both live there and both belong to the SYSTEM
+ * manager, which is where `systemctl list-units` reports them. Only a path
+ * passing THROUGH `user@<uid>.service` is inside that user's own manager.
+ */
+export function serviceKeyFromCgroup(cgroup: string, selfUid: number): string | null {
+  const unit = unitFromCgroup(cgroup);
+  if (!unit) return null;
+  const owner = /\/user@(\d+)\.service\//.exec(systemdHierarchy(cgroup) ?? "");
+  if (!owner) return `system:${unit}`;
+  return Number(owner[1]) === selfUid ? `user:${unit}` : null;
+}

package/src/services/system-services/app-icon-service.ts

@@ -0,0 +1,31 @@
+/**
+ * App id to an icon file on disk, for the icon route.
+ *
+ * The security property lives here rather than in the route: the caller supplies
+ * an APP ID, this looks up that id's desktop entry, and only the path that
+ * entry's own Icon resolved to is ever returned. There is no request shape that
+ * names a file, so the route cannot become an arbitrary file read.
+ *
+ * Both caches are lazy and built once, so a host where nobody opens the Apps page
+ * pays nothing: the entry scan measured 9 ms and the icon index 100 ms here.
+ */
+import { realLinuxFs, type LinuxFs } from "../system-metrics/linux-fs.ts";
+import { createLinuxAppCollector } from "./apps-linux.ts";
+import { createIconResolver } from "./app-icons-linux.ts";
+
+export interface AppIconService {
+  /** Absolute path to the icon file, or null when the app or its icon is unknown. */
+  path(appId: string): string | null;
+}
+
+export function createAppIconService(fs: LinuxFs = realLinuxFs): AppIconService {
+  const apps = createLinuxAppCollector(fs);
+  const icons = createIconResolver(fs);
+  return {
+    path(appId: string): string | null {
+      if (!appId || appId.includes("/") || appId.includes("..")) return null;
+      const entry = apps.entries().get(appId);
+      return entry ? icons.resolve(entry.icon) : null;
+    },
+  };
+}

package/src/services/system-services/app-icons-linux.ts

@@ -0,0 +1,124 @@
+/**
+ * Resolving a desktop entry's Icon to a file PPM can serve.
+ *
+ * An Icon is either an absolute path or a theme icon NAME, and the name is the
+ * common case: on this host `code.desktop` says `Icon=vscode`, which exists only
+ * under /usr/share/pixmaps, while `org.kde.dolphin` is an SVG under hicolor and
+ * `claude-desktop` is a PNG under hicolor's sized directories. A resolver that
+ * searches only the current theme finds none of the three.
+ *
+ * So the whole search path is indexed once, name to path: measured here, 22022
+ * names in 29 ms. That is far cheaper than walking per lookup and it is built
+ * lazily, on the first icon anyone actually asks for.
+ *
+ * The index is also the security boundary. The HTTP route never takes a path - it
+ * takes an app id, looks the entry up, and serves only what this module resolved,
+ * so there is no request shape that can name an arbitrary file.
+ */
+import type { LinuxFs } from "../system-metrics/linux-fs.ts";
+import { realLinuxFs } from "../system-metrics/linux-fs.ts";
+
+/** Preference order: a vector icon scales to any row height the UI uses. */
+export const ICON_EXTENSIONS: readonly string[] = [".svg", ".png", ".xpm"];
+
+/** How deep a theme nests: theme / context / size / name, plus a little slack. */
+const MAX_DEPTH = 5;
+
+export const ICON_MIME: Record<string, string> = {
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".xpm": "image/x-xpixmap",
+};
+
+export function iconRoots(env: Record<string, string | undefined>, home: string): string[] {
+  const dataHome = env.XDG_DATA_HOME || `${home}/.local/share`;
+  const dataDirs = (env.XDG_DATA_DIRS || "/usr/local/share:/usr/share").split(":").filter(Boolean);
+  const roots: string[] = [`${home}/.icons`, `${dataHome}/icons`];
+  for (const base of dataDirs) roots.push(`${base}/icons`);
+  // pixmaps is not a theme and is easy to forget; it is also the ONLY place some
+  // very common icons exist, so leaving it out loses them entirely.
+  for (const base of dataDirs) roots.push(`${base}/pixmaps`);
+  return [...new Set(roots)];
+}
+
+/**
+ * name to path. An earlier root wins over a later one, and within a root a better
+ * extension replaces a worse one - so a theme's SVG beats the same theme's PNG
+ * without needing the walk to be ordered by size.
+ */
+export function buildIconIndex(roots: readonly string[], fs: LinuxFs): Map<string, string> {
+  const index = new Map<string, string>();
+  const rank = new Map<string, number>();
+  const walk = (dir: string, depth: number, rootOrder: number): void => {
+    if (depth > MAX_DEPTH) return;
+    const entries = fs.list(dir);
+    if (!entries) return;
+    for (const name of entries) {
+      const path = `${dir}/${name}`;
+      const dot = name.lastIndexOf(".");
+      const ext = dot > 0 ? name.slice(dot) : "";
+      const extRank = ICON_EXTENSIONS.indexOf(ext);
+      if (extRank < 0) {
+        // No known extension: treat it as a directory and descend. A plain file
+        // simply lists as nothing and costs one failed readdir.
+        walk(path, depth + 1, rootOrder);
+        continue;
+      }
+      const base = name.slice(0, dot);
+      const score = rootOrder * 10 + extRank;
+      const previous = rank.get(base);
+      if (previous === undefined || score < previous) {
+        rank.set(base, score);
+        index.set(base, path);
+      }
+    }
+  };
+  roots.forEach((root, order) => walk(root, 0, order));
+  return index;
+}
+
+/**
+ * The file for one Icon value, or null when nothing resolves.
+ *
+ * An absolute path is taken from the entry itself, which is host-owned content -
+ * but it is still required to be an image extension, so a malformed entry cannot
+ * turn the icon route into a reader of arbitrary files.
+ */
+export function resolveIconPath(
+  icon: string | null,
+  index: Map<string, string>,
+  fs: LinuxFs,
+): string | null {
+  if (!icon) return null;
+  if (icon.startsWith("/")) {
+    return hasImageExtension(icon) && fs.exists(icon) ? icon : null;
+  }
+  // Some entries write the file name rather than the icon name ("foo.png").
+  const dot = icon.lastIndexOf(".");
+  const stem = dot > 0 && ICON_EXTENSIONS.includes(icon.slice(dot)) ? icon.slice(0, dot) : icon;
+  return index.get(stem) ?? index.get(icon) ?? null;
+}
+
+export function hasImageExtension(path: string): boolean {
+  const dot = path.lastIndexOf(".");
+  return dot > 0 && ICON_EXTENSIONS.includes(path.slice(dot).toLowerCase());
+}
+
+export function iconMimeType(path: string): string {
+  const dot = path.lastIndexOf(".");
+  return ICON_MIME[dot > 0 ? path.slice(dot).toLowerCase() : ""] ?? "application/octet-stream";
+}
+
+/** Production wiring: one lazily-built index for the process's lifetime. */
+export function createIconResolver(fs: LinuxFs = realLinuxFs) {
+  const roots = iconRoots(process.env, process.env.HOME ?? "/root");
+  let index: Map<string, string> | null = null;
+  return {
+    resolve(icon: string | null): string | null {
+      index ??= buildIconIndex(roots, fs);
+      return resolveIconPath(icon, index, fs);
+    },
+  };
+}
+
+export type IconResolver = ReturnType<typeof createIconResolver>;