@hienlh/ppm 0.23.6 → 0.23.7

package/src/types/chat.ts

@@ -282,4 +282,31 @@ export interface ChatMessage {
   sdkUuid?: string;
   /** Token split for the turn that produced this message; drives the cost warning. */
   usage?: import("../shared/turn-usage").TurnUsage;
+  /**
+   * Set only on the compact-summary message that opens a post-compaction segment,
+   * so the divider above it can say what the compaction cost and saved.
+   */
+  compaction?: CompactionInfo;
+}
+
+/**
+ * What one compaction did, read back from the `compact_boundary` record Claude Code
+ * writes into the transcript.
+ *
+ * Taken from the file rather than from the live `compact_boundary` event because the
+ * figure has to survive a reload: the turn that compacts ends by refetching history,
+ * so a notice that existed only in WebSocket state would vanish seconds after it
+ * appeared. The event carries the same numbers and is deliberately not plumbed.
+ */
+export interface CompactionInfo {
+  /** `auto` when the context window forced it, `manual` when the user ran /compact. */
+  trigger: "manual" | "auto";
+  /** Transcript size going in. */
+  preTokens: number;
+  /** Size of the summary that replaced it. */
+  postTokens: number;
+  /** `preTokens - postTokens` — this compaction alone, not the session's running total. */
+  savedTokens: number;
+  /** How long the compaction took, when the record says. */
+  durationMs?: number;
 }

package/src/types/config.ts

@@ -44,6 +44,14 @@ export interface PpmConfig {
  * `zoneID`/`accountID` are pinned at setup and re-checked on every reuse.
  */
 export interface TunnelConfig {
+  /**
+   * Master switch for the public tunnel. `false` means the supervisor spawns no
+   * cloudflared at all, whatever `mode` says — a machine reached over a LAN, a
+   * VPN or Tailscale gains nothing from a public URL and pays for it in
+   * exposure. Absent in rows written before this switch existed, so every
+   * reader must default it to `true`: the tunnel used to be unconditional.
+   */
+  enabled: boolean;
   mode: "quick" | "named";
   namedTunnelName?: string;
   namedTunnelHostname?: string;
@@ -176,6 +184,7 @@ export const DEFAULT_CONFIG: PpmConfig = {
     debounce_ms: 2000,
   },
   tunnel: {
+    enabled: true,
     mode: "quick",
   },
 };
@@ -348,6 +357,11 @@ export function sanitizeConfig(config: PpmConfig): boolean {
       (config.tunnel.mode !== "quick" && config.tunnel.mode !== "named")) {
     config.tunnel = structuredClone(DEFAULT_CONFIG.tunnel);
     dirty = true;
+  } else if (typeof config.tunnel.enabled !== "boolean") {
+    // Written before the master switch existed, when the tunnel was
+    // unconditional — so an absent flag must read as on, never off.
+    config.tunnel.enabled = true;
+    dirty = true;
   }
 
   return dirty;

package/src/types/git.ts

@@ -21,6 +21,47 @@ export interface GitBranch {
   remotes: string[];
 }
 
+/**
+ * One checkout target for the branch picker: a local branch, a remote-tracking
+ * branch or a tag, together with the commit it points at.
+ *
+ * Separate from `GitBranch` because that shape is what the graph draws and it
+ * carries no commit metadata — the picker needs an author, a subject and a date
+ * per row, and it needs tags, which `branches()` never returns.
+ */
+export interface GitRef {
+  /** Full ref name: `refs/heads/main`, `refs/remotes/origin/main`, `refs/tags/v1`. */
+  refName: string;
+  /** Short name, as a user reads it and as git checks it out by: `main`, `origin/main`, `v1`. */
+  name: string;
+  type: "branch" | "remote" | "tag";
+  /** True for the one local branch HEAD is on. */
+  current: boolean;
+  /** The commit this ref resolves to — dereferenced, so an annotated tag names its commit. */
+  hash: string;
+  shortHash: string;
+  subject: string;
+  author: string;
+  /** ISO 8601 commit date. */
+  date: string;
+  /** Upstream ref short name (`origin/main`), or null. Local branches only. */
+  upstream: string | null;
+  /** Commits ahead of / behind `upstream`; both 0 when there is none. */
+  ahead: number;
+  behind: number;
+  /** An upstream is configured but no longer exists on the remote. */
+  gone: boolean;
+}
+
+/**
+ * How `git checkout` is asked to move HEAD.
+ *
+ * `track` exists because a remote-tracking ref is not a branch: plain
+ * `git checkout origin/foo` lands on a detached HEAD, and `-t` is what creates
+ * the local `foo` that follows it.
+ */
+export type CheckoutMode = "checkout" | "detach" | "track";
+
 export interface GitStatus {
   current: string | null;
   /** Commits ahead of the upstream branch. */

package/src/types/system-hardware.ts

@@ -0,0 +1,137 @@
+/** Static hardware facts for the Performance page — everything that does not change
+ *  tick to tick, served once by GET /api/system/hardware instead of riding every 2 s
+ *  snapshot over a tunnel. The client refetches when a snapshot names a device id it
+ *  does not know (a USB disk plugged in, an interface created). Types + constants
+ *  only. Import RELATIVELY — the "@" alias points at src/web. */
+import type { GpuInfo, MetricsPlatform } from "./system-metrics.ts";
+
+export type DiskKind = "hdd" | "ssd" | "nvme" | "emmc" | "sd" | "optical" | "thumb" | "unknown";
+
+/** One place a partition is mounted. A partition can have several: a btrfs
+ *  subvolume layout mounts the same device at `/`, `/home` and `/var/log`. */
+export interface PartitionMount {
+  mountPoint: string;
+  filesystem: string;
+  /** From `statfs` on the mount, not from the partition's size — metadata,
+   *  root-reserved blocks and a shared subvolume pool all make the two differ.
+   *  Both absent when statfs refused; a filesystem we could not read is not an
+   *  empty one. */
+  usedBytes?: number;
+  totalBytes?: number;
+}
+
+export interface PartitionInfo {
+  /** Kernel name, e.g. "sda1". */
+  id: string;
+  devicePath: string;
+  /** What the partition table says, which is the number that never changes. */
+  sizeBytes: number;
+  /** udev's `ID_FS_TYPE`, so it is known even for a partition nothing mounted. */
+  filesystem?: string;
+  /** Empty for a partition that is not mounted anywhere. */
+  mounts: PartitionMount[];
+}
+
+export interface DiskInfo {
+  /** /sys/block name — the key `DiskMetrics.id` uses. */
+  id: string;
+  /** Vendor + model as the drive reports them; absent when it reports neither. */
+  model?: string;
+  kind: DiskKind;
+  capacityBytes: number;
+  /** Holds the root filesystem (through partitions, LUKS or LVM). */
+  systemDisk: boolean;
+  removable: boolean;
+  serial?: string;
+  wwn?: string;
+  rotationRpm?: number;
+  /** Absent on a platform with no partition support yet; empty on a disk with no
+   *  partition table (a whole-device filesystem, an unformatted drive). */
+  partitions?: PartitionInfo[];
+}
+
+/** Mission Center's interface kinds. It classifies by name prefix because its
+ *  NetworkManager type read always fails; PPM uses sysfs first and the same
+ *  prefixes only as the fallback. */
+export type NicKind =
+  | "wired" | "wireless" | "bluetooth" | "bridge" | "docker" | "infiniband"
+  | "multipass" | "virtual" | "vpn" | "other";
+
+export interface NicInfo {
+  /** Interface name — the key `NicMetrics.id` uses. */
+  id: string;
+  kind: NicKind;
+  /** Adapter name from the PCI/USB database ("RTL8125 2.5GbE Controller"). */
+  deviceName?: string;
+  driver?: string;
+  /** Hardware address, absent for interfaces without one (tun, wireguard). */
+  mac?: string;
+  ipv4: string[];
+  ipv6: string[];
+}
+
+/** Static CPU facts — Mission Center's CPU page header and its bottom grid. */
+export interface CpuInfo {
+  /** Marketing name, e.g. "12th Gen Intel(R) Core(TM) i9-12900K". */
+  name: string;
+  /** Populated sockets. */
+  sockets: number;
+  /** Physical cores across all sockets, and hardware threads. On a hybrid part
+   *  (Intel P+E) the physical count is what the kernel reports per socket. */
+  physicalCores: number;
+  logicalCores: number;
+  /** Nominal clock and the highest the driver will ask for, MHz. */
+  baseMHz?: number;
+  maxMHz?: number;
+  /** "Intel VT-x" / "AMD-V", absent when the flag is missing (or hidden in a VM). */
+  virtualization?: string;
+  /** True when this kernel is itself running virtualised. */
+  isVirtualMachine: boolean;
+  /** Summed over DISTINCT caches, bytes. L1 combines data and instruction, as
+   *  Mission Center does. Absent when sysfs exposes no cache topology. */
+  l1CacheBytes?: number;
+  l2CacheBytes?: number;
+  l3CacheBytes?: number;
+  /** cpufreq's driver, governor and energy-performance preference. */
+  freqDriver?: string;
+  freqGovernor?: string;
+  powerPreference?: string;
+}
+
+/** One populated memory slot, from the SMBIOS table udev already decoded. */
+export interface MemoryDeviceInfo {
+  /** Slot name as the board labels it, e.g. "DDR4-A1". */
+  locator: string;
+  bankLocator?: string;
+  sizeBytes: number;
+  /** "DIMM", "SODIMM", … */
+  formFactor?: string;
+  /** "DDR4", "DDR5", … */
+  ramType?: string;
+  /** Configured transfer rate, MT/s. */
+  speedMts?: number;
+  manufacturer?: string;
+  rank?: number;
+}
+
+export interface MemoryInfo {
+  /** Populated slots. Empty when the firmware table is unreadable — the UI then
+   *  shows the totals only, as Mission Center does inside a VM. */
+  devices: MemoryDeviceInfo[];
+  /** Slots the board has in total, when the firmware says. */
+  slotsTotal?: number;
+  /** Largest configuration the board accepts, bytes. */
+  maxCapacityBytes?: number;
+}
+
+export interface HardwareInventory {
+  platform: MetricsPlatform;
+  /** Epoch ms the inventory was read. */
+  ts: number;
+  disks: DiskInfo[];
+  nics: NicInfo[];
+  gpus: GpuInfo[];
+  /** Absent where the host exposes no CPU topology (never on Linux). */
+  cpu?: CpuInfo;
+  memory?: MemoryInfo;
+}

package/src/types/system-metrics.ts

@@ -14,6 +14,24 @@ export interface CpuMetrics {
   /** Index matches `os.cpus()` order. Core count is `cores.length`. */
   cores: number[];
   model: string;
+  /** Everything below is Mission Center's CPU page and is absent where this host
+   *  cannot measure it — the UI hides the row rather than showing a 0.
+   *
+   *  Kernel-mode share, drawn as a second line under the total. */
+  kernelPercent?: number;
+  coreKernel?: number[];
+  /** Mean current clock across the online cores, MHz. */
+  currentMHz?: number;
+  /** Package sensor, °C. */
+  tempC?: number;
+  /** Package draw over the tick, watts (RAPL energy delta / elapsed). */
+  powerW?: number;
+  /** Kernel-wide totals for the page's rows. Handles is open file descriptors,
+   *  which is the closest Linux analogue of the Windows figure. */
+  threadCount?: number;
+  handleCount?: number;
+  /** Seconds since boot. */
+  uptimeSec?: number;
 }
 
 export interface MemoryMetrics {
@@ -22,6 +40,41 @@ export interface MemoryMetrics {
   availableMB: number;
   /** usedMB / totalMB × 100. */
   percent: number;
+  /** Mission Center's composition bar, in BYTES. The four add up to the total, so
+   *  the bar needs no normalisation. Absent on a host with no /proc/meminfo. */
+  inUseBytes?: number;
+  /** Written-to pages not yet on disk (Dirty + Writeback). */
+  modifiedBytes?: number;
+  /** Reclaimable: page cache, buffers and reclaimable slab. */
+  standbyBytes?: number;
+  freeBytes?: number;
+  cachedMB?: number;
+  /** Address space promised to processes, and the kernel's ceiling for it. */
+  committedMB?: number;
+  commitLimitMB?: number;
+  swapTotalMB?: number;
+  swapUsedMB?: number;
+  /** zram, summed across every device. `compressedMB` is what the compressed
+   *  pages occupy; `savingsMB` is what they would have occupied uncompressed
+   *  minus that, i.e. the RAM the compression bought back. Both absent on a host
+   *  with no zram — which is not the same as a host whose zram is empty. */
+  zramCompressedMB?: number;
+  zramSavingsMB?: number;
+}
+
+/** One fan, plus the temperature its chip reports beside it — Mission Center's
+ *  Fan page. Small and few, so the labels ride the tick rather than the inventory. */
+export interface FanMetrics {
+  /** Stable across ticks: "<hwmon name>/fan<N>", e.g. "it8689/fan1". */
+  id: string;
+  /** The chip's own label when it has one, else "Fan N". */
+  label: string;
+  rpm: number;
+  /** Duty cycle, 0-100, from the matching `pwmN` (raw 0-255). */
+  pwmPercent?: number;
+  /** The chip's temperature sensor with the same index, °C. */
+  tempC?: number;
+  tempName?: string;
 }
 
 /** Whole-machine throughput, bytes/second over the last tick. */
@@ -39,8 +92,52 @@ export interface GpuMetrics {
   name: string;
   /** 0-100. */
   utilPercent: number;
+  /** Dedicated memory. `vramTotalMB` 0 = the device has none to report (an
+   *  integrated GPU), so the UI shows no memory figure rather than "0 B / 0 B". */
   vramUsedMB: number;
   vramTotalMB: number;
+  /** Everything below is Mission Center's GPU page. Each field is absent when this
+   *  driver/host cannot measure it, and the UI hides that row or graph mode.
+   *
+   *  Stable device id matching `GpuInfo.id`: the PCI address ("0000:00:02.0"), or
+   *  "<driver>-<n>" for a GPU with none. */
+  id?: string;
+  /** GTT / shared system memory (amdgpu), MB. */
+  sharedUsedMB?: number;
+  sharedTotalMB?: number;
+  /** Video engines, 0-100. When `GpuInfo.encodeDecodeShared`, the one combined
+   *  counter is reported as `encodePercent` and `decodePercent` is absent. */
+  encodePercent?: number;
+  decodePercent?: number;
+  clockMHz?: number;
+  clockMaxMHz?: number;
+  memClockMHz?: number;
+  memClockMaxMHz?: number;
+  powerW?: number;
+  powerMaxW?: number;
+  tempC?: number;
+}
+
+/** Static facts about one GPU — served by the hardware inventory, never per tick. */
+export interface GpuInfo {
+  /** Same id as `GpuMetrics.id`. */
+  id: string;
+  name: string;
+  vendor?: string;
+  /** Kernel driver: "i915", "xe", "amdgpu", "nvidia". */
+  driver?: string;
+  driverVersion?: string;
+  /** Highest context the driver offers: "4.6", or "ES 3.2". Absent = unknown. */
+  openglVersion?: string;
+  /** Vulkan API version, "1.4.354". Absent = unsupported or unknown. */
+  vulkanVersion?: string;
+  pcieGen?: number;
+  pcieLanes?: number;
+  /** Only when different from the current link (Mission Center hides an equal one). */
+  pcieMaxGen?: number;
+  pcieMaxLanes?: number;
+  /** One combined video engine (Intel VCS): the UI shows "Video encode/decode". */
+  encodeDecodeShared?: boolean;
 }
 
 export interface SystemMetrics {
@@ -50,10 +147,63 @@ export interface SystemMetrics {
   disk: RateMetrics;
   /** light tier: available:false. */
   net: RateMetrics;
-  /** light tier: []. Empty also when no NVIDIA GPU — the UI hides the card. */
+  /** light tier: []. Empty also when no GPU is readable — the UI hides the card. */
   gpus: GpuMetrics[];
   /** light tier: 0. Processes the collector could see this tick. */
   processCount: number;
+  /** Per-device figures for the Performance page's drive and network entries (full
+   *  tier). Absent = not collected on this host; static facts about each device are
+   *  in the hardware inventory (`src/types/system-hardware.ts`), keyed by `id`. */
+  disks?: DiskMetrics[];
+  nics?: NicMetrics[];
+  /** Absent where the host exposes no fan tachometer (most laptops, every VM). */
+  fans?: FanMetrics[];
+}
+
+/** One whole disk (a /sys/block entry), for Mission Center's per-drive page. */
+export interface DiskMetrics {
+  /** Kernel name, the key into the inventory: "nvme0n1", "sda". */
+  id: string;
+  /** False on this device's first sample: the rates below need two of them, so the
+   *  UI says "measuring…" rather than a confident 0. The two totals are absolutes
+   *  and are always real. */
+  available: boolean;
+  /** "Active time": share of the tick with I/O in flight (iostat %util), 0-100. */
+  busyPercent: number;
+  /** "Avg. response time": ms per completed request (read + write + discard +
+   *  flush) over the tick; 0 when none completed. */
+  responseMs: number;
+  readBps: number;
+  writeBps: number;
+  /** Bytes since boot ("Total Read" / "Total Written"). */
+  readTotal: number;
+  writeTotal: number;
+  /** Drive sensor, °C (NVMe composite, SATA via drivetemp); absent when none. */
+  tempC?: number;
+}
+
+export type NicState = "connected" | "connecting" | "disconnected" | "unavailable" | "unknown";
+
+/** One network interface, for Mission Center's per-interface page. */
+export interface NicMetrics {
+  /** Interface name, the key into the inventory: "enp3s0". */
+  id: string;
+  /** False on this interface's first sample (the rates need two). The totals are
+   *  absolutes and are always real. */
+  available: boolean;
+  rxBps: number;
+  txBps: number;
+  /** Bytes since the interface came up ("Total Received" / "Total Sent"). */
+  rxTotal: number;
+  txTotal: number;
+  state: NicState;
+  /** Negotiated link speed, Mbit/s — Mission Center's "Maximum Bitrate", and the
+   *  throughput axis ceiling when dynamic scaling is off. Absent when unknown. */
+  linkMbps?: number;
+  /** Wireless only. */
+  ssid?: string;
+  signalPercent?: number;
+  frequencyMHz?: number;
 }
 
 export interface ProcessInfo {
@@ -70,6 +220,16 @@ export interface ProcessInfo {
    *  Always 0 on a process's first observed tick. */
   cpu: number;
   ramMB: number;
+  /** Anonymous memory the kernel has pushed out to swap, MB — Mission Center's
+   *  Swap column. `undefined` = this OS does not report it per process; a kernel
+   *  thread, which has no address space at all, reports 0. */
+  swapMB?: number;
+  /** `"<scope>:<unit>"` — the Services row this pid belongs to, read from its
+   *  cgroup ("system:sshd.service"). The scope is part of the key because
+   *  `dbus-broker.service` exists in BOTH on an ordinary desktop. Absent on a
+   *  host with no systemd, for a pid in no unit, and for another user's units.
+   *  The Services page's live figures are summed over it. */
+  unitKey?: string;
   /** Epoch ms UTC; 0 when unknown. Identity guard for CPU deltas, grouping and kill. */
   startedAt: number;
   /** PPM server, supervisor, edge forwarder, their descendants, PPM-managed
@@ -114,6 +274,7 @@ export interface ProcessGroup {
   /** Roll-ups of the optional per-process columns, with the same optionality:
    *  the sum over the members that HAVE a value, and `undefined` when no member
    *  has one — so "nothing measurable" never renders as a hard 0. */
+  swapMB?: number;
   diskReadBps?: number;
   diskWriteBps?: number;
   /** Summed engine busy across members, clamped 0-100. */
@@ -129,6 +290,8 @@ export interface ProcessColumnAvailability {
   disk: boolean;
   gpu: boolean;
   net: boolean;
+  /** Linux only so far: `VmSwap` in `/proc/<pid>/status`. */
+  swap: boolean;
 }
 
 /** CLIENT-SIDE history element: aggregates only. There is no server ring. */
@@ -160,6 +323,10 @@ export interface MetricsSnapshot {
   total: { cpu: number; ramMB: number; processCount: number };
   /** Non-fatal collector failures, human readable. Rendered in the UI. */
   warnings: string[];
+  /** Linux desktop apps (full tier). Absent on other hosts and from older servers. */
+  apps?: AppInfo[];
+  /** Signals this host can deliver. Absent = an older server (kill route only). */
+  signals?: ProcessSignal[];
 }
 
 export interface KillProcessRequest {
@@ -182,9 +349,71 @@ export interface KillProcessResult {
   killed: number[];
 }
 
+/** Mission Center's process menu: "Stop" is TERM, "Force Stop" is KILL, and the
+ *  "Send Signal" submenu offers all eight. Names without the `SIG` prefix. */
+export type ProcessSignal = "TERM" | "KILL" | "STOP" | "CONT" | "HUP" | "INT" | "USR1" | "USR2";
+
+export const PROCESS_SIGNALS: readonly ProcessSignal[] = ["TERM", "KILL", "STOP", "CONT", "HUP", "INT", "USR1", "USR2"];
+
+export interface SignalProcessRequest {
+  pid: number;
+  /** Identity guard, exactly as for a kill: 409 when the live process started at
+   *  another time, so a recycled pid is never signalled against a stale name. */
+  startedAt: number;
+  signal: ProcessSignal;
+  /** Deliver to the whole collected tree as well. Suspending an app means
+   *  suspending its helpers, which signalling the root alone does not do. */
+  tree?: boolean;
+}
+
+export interface SignalProcessResult {
+  pid: number;
+  signal: ProcessSignal;
+  tree: boolean;
+  method: "taskkill" | "signal";
+  /** Pids actually signalled (win32 + tree: `[pid]`, as for a kill). */
+  signalled: number[];
+}
+
+/** On-demand facts for the Details dialog — fetched when it opens, never per tick.
+ *  Live figures (CPU, memory, …) come from the snapshot row, not from here. Every
+ *  field is null when this OS or this pid's permissions do not expose it. */
+export interface ProcessDetails {
+  pid: number;
+  ppid: number;
+  name: string;
+  startedAt: number;
+  /** Full command line, secrets redacted but NOT truncated to the row's 160 chars. */
+  command: string | null;
+  exe: string | null;
+  cwd: string | null;
+  user: string | null;
+  /** Kernel state, e.g. "S (sleeping)", "T (stopped)". */
+  state: string | null;
+  threads: number | null;
+  nice: number | null;
+  /** Linux cgroup path — which systemd unit or app scope the process runs in. */
+  cgroup: string | null;
+}
+
+/** A running desktop application — Mission Center's "Apps" section. Linux only:
+ *  identified from the user's app cgroups and `.desktop` Exec matching. */
+export interface AppInfo {
+  /** Desktop file id without `.desktop`: "org.kde.konsole". Stable across ticks. */
+  id: string;
+  /** The entry's unlocalised `Name=`. */
+  name: string;
+  /** The entry's `Icon=`: a theme icon name or an absolute path; resolved to an
+   *  image by `/api/system/app-icon`. Null when the entry has none. */
+  icon: string | null;
+  /** Primary pids: app pids whose parent is not also one of this app's pids. Each
+   *  stands for its whole subtree, which is what an app row's figures sum over. */
+  pids: number[];
+}
+
 /** Sort columns offered by the process table. `disk` sorts by read + write,
  *  `net` by in + out; rows without a value sort last. */
-export type SortKey = "cpu" | "ram" | "disk" | "gpu" | "gpuMem" | "net" | "name" | null;
+export type SortKey = "cpu" | "ram" | "swap" | "disk" | "gpu" | "gpuMem" | "net" | "name" | null;
 export type SortDir = "asc" | "desc";
 
 /** Full-tier poll cadence. A Windows tick (one CIM round trip) costs ~175-200 ms,

package/src/types/system-services.ts

@@ -0,0 +1,73 @@
+/** Service-manager contract shared by the systemd collector, the routes and the web
+ *  client — Mission Center's Services page. Types + constants only, no imports, so
+ *  both bundles can take it. Import RELATIVELY — the "@" alias points at src/web. */
+
+export type ServiceScope = "system" | "user";
+
+/** Start/Stop/Restart are Mission Center's menu; Enable/Disable its details switch. */
+export type ServiceAction = "start" | "stop" | "restart" | "enable" | "disable";
+
+export const SERVICE_ACTIONS: readonly ServiceAction[] = ["start", "stop", "restart", "enable", "disable"];
+
+/** One unit. Mission Center lists `.service`, `.socket` and `.mount` units and drops
+ *  the ones systemd reports as `not-found`; masked units stay in the list. */
+export interface ServiceInfo {
+  /** Full unit name, suffix included: "sshd.service", "docker.socket", "home.mount". */
+  unit: string;
+  scope: ServiceScope;
+  description: string;
+  /** systemd ActiveState verbatim: "active", "inactive", "failed", "activating", … */
+  activeState: string;
+  /** systemd SubState verbatim: "running", "exited", "dead", "listening", … */
+  subState: string;
+  /** Unit-file state verbatim ("enabled", "disabled", "static", "masked", "indirect", …);
+   *  null for a unit with no unit file (transient, generated without one). */
+  unitFileState: string | null;
+  /** Mission Center's three booleans, derived exactly as it does: ActiveState "active",
+   *  ActiveState "failed", and unit-file state exactly "enabled" (static/indirect/alias
+   *  count as not enabled). `activating`/`reloading` are neither running nor failed. */
+  running: boolean;
+  failed: boolean;
+  enabled: boolean;
+  /** Main process, null when the unit has none (stopped, socket, mount, oneshot done). */
+  mainPid: number | null;
+  /** Actions the guard refuses for this unit, each with the reason shown to the user.
+   *  Produced by the same function the action route enforces, so a disabled button
+   *  and a 403 cannot disagree. Absent when every action is allowed. */
+  refused?: Partial<Record<ServiceAction, string>>;
+}
+
+export interface ServicesSnapshot {
+  /** False when the host has no supported service manager (no systemd). The UI hides
+   *  the Services page, as Mission Center does when both lists stay empty. */
+  supported: boolean;
+  services: ServiceInfo[];
+  /** Non-fatal failures, human readable (e.g. the user manager is unreachable). */
+  warnings: string[];
+}
+
+export interface ServiceLogLine {
+  /** Epoch ms UTC. */
+  ts: number;
+  message: string;
+}
+
+export interface ServiceDetails extends ServiceInfo {
+  /** Configured `User=` / `Group=`; null when unset (runs as the manager's user). */
+  user: string | null;
+  group: string | null;
+  /** Unit file location (`FragmentPath`), null when unknown. */
+  fragmentPath: string | null;
+  /** This boot's journal for the unit, oldest first, bounded. */
+  logs: ServiceLogLine[];
+}
+
+export interface ServiceActionResult {
+  unit: string;
+  scope: ServiceScope;
+  action: ServiceAction;
+}
+
+/** Client poll cadence while the Services page is visible. The list costs a handful of
+ *  `systemctl` spawns, so it is fetched on demand rather than riding the metrics tick. */
+export const SERVICES_POLL_INTERVAL_MS = 3000;