@hienlh/ppm 0.23.5 → 0.23.7

package/src/services/system-services/apps-linux.ts

@@ -0,0 +1,174 @@
+/**
+ * The Apps page: which desktop applications are running, and which pids are
+ * theirs - Mission Center's app list.
+ *
+ * Matching is primary-source rather than heuristic. A systemd graphical session
+ * puts every launched app in its own app scope whose unit name states the desktop
+ * entry id, so a pid names its app outright (see app-cgroup-linux.ts). The exec
+ * fallback below exists only for a session that is not systemd-managed, where
+ * there is no scope to read.
+ *
+ * Injectable filesystem throughout, so the whole thing is fixture-tested.
+ */
+import type { AppInfo } from "../../types/system-metrics.ts";
+import type { LinuxFs } from "../system-metrics/linux-fs.ts";
+import { realLinuxFs } from "../system-metrics/linux-fs.ts";
+import { appIdFromCgroup } from "./app-cgroup-linux.ts";
+import { execBinary, parseDesktopEntry, type DesktopEntry } from "./desktop-entry.ts";
+
+const DESKTOP_SUFFIX = ".desktop";
+
+/**
+ * The XDG search path, most specific first. Precedence is what decides which copy
+ * of a duplicated id wins: a user's own entry must beat the system one, which is
+ * how an override in the home directory works at all.
+ */
+export function desktopDirs(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 seen = new Set<string>();
+  const dirs: string[] = [];
+  for (const base of [dataHome, ...dataDirs]) {
+    const dir = `${base}/applications`;
+    if (!seen.has(dir)) {
+      seen.add(dir);
+      dirs.push(dir);
+    }
+  }
+  return dirs;
+}
+
+/** id to entry. The FIRST directory to define an id wins, per XDG precedence. */
+export function loadDesktopEntries(dirs: readonly string[], fs: LinuxFs): Map<string, DesktopEntry> {
+  const entries = new Map<string, DesktopEntry>();
+  for (const dir of dirs) {
+    for (const file of fs.list(dir) ?? []) {
+      if (!file.endsWith(DESKTOP_SUFFIX)) continue;
+      const id = file.slice(0, -DESKTOP_SUFFIX.length);
+      if (entries.has(id)) continue;
+      const text = fs.read(`${dir}/${file}`);
+      const entry = text === null ? null : parseDesktopEntry(id, text);
+      if (entry) entries.set(id, entry);
+    }
+  }
+  return entries;
+}
+
+/** What the tick calls once per full snapshot. */
+export type AppCollector = (processes: readonly AppProcess[]) => AppInfo[];
+
+/** A process as this module needs it - the subset the tick already has in hand. */
+export interface AppProcess {
+  pid: number;
+  ppid: number;
+  name: string;
+}
+
+export interface CollectAppsInput {
+  processes: readonly AppProcess[];
+  entries: Map<string, DesktopEntry>;
+  /** `/proc/<pid>/cgroup` for one pid, or null when it is gone. */
+  readCgroup: (pid: number) => string | null;
+}
+
+/**
+ * Apps with at least one live process, name-sorted.
+ *
+ * A NoDisplay entry is skipped: its author asked for it not to appear in menus,
+ * and including them would list every url-handler and console helper shipped
+ * beside a real app.
+ */
+export function collectApps(input: CollectAppsInput): AppInfo[] {
+  const { processes, entries, readCgroup } = input;
+  const byBinary = execBinaryIndex(entries);
+  const pidsByApp = new Map<string, number[]>();
+
+  for (const proc of processes) {
+    const id = matchApp(proc, entries, byBinary, readCgroup);
+    if (!id) continue;
+    const list = pidsByApp.get(id);
+    if (list) list.push(proc.pid);
+    else pidsByApp.set(id, [proc.pid]);
+  }
+
+  const ppidOf = new Map(processes.map((p) => [p.pid, p.ppid]));
+  const apps: AppInfo[] = [];
+  for (const [id, pids] of pidsByApp) {
+    const entry = entries.get(id);
+    if (!entry) continue;
+    apps.push({ id, name: entry.name, icon: entry.icon, pids: primaryPids(pids, ppidOf) });
+  }
+  return apps.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * The pids that stand for the app: those whose parent is not also one of its own.
+ * Each is the root of a subtree, which is what an app row's figures sum over -
+ * counting every member would count a helper's CPU once per level of nesting.
+ */
+export function primaryPids(pids: readonly number[], ppidOf: Map<number, number>): number[] {
+  const own = new Set(pids);
+  return pids.filter((pid) => !own.has(ppidOf.get(pid) ?? -1)).sort((a, b) => a - b);
+}
+
+/**
+ * Exec binary to id, for the fallback match. Ambiguous binaries are dropped
+ * entirely rather than resolved arbitrarily: two entries launching `sh` must not
+ * make every shell on the machine look like one of them.
+ */
+export function execBinaryIndex(entries: Map<string, DesktopEntry>): Map<string, string> {
+  const index = new Map<string, string>();
+  const ambiguous = new Set<string>();
+  for (const entry of entries.values()) {
+    if (entry.noDisplay) continue;
+    const binary = execBinary(entry.exec);
+    if (!binary) continue;
+    if (index.has(binary)) ambiguous.add(binary);
+    else index.set(binary, entry.id);
+  }
+  for (const binary of ambiguous) index.delete(binary);
+  return index;
+}
+
+function matchApp(
+  proc: AppProcess,
+  entries: Map<string, DesktopEntry>,
+  byBinary: Map<string, string>,
+  readCgroup: (pid: number) => string | null,
+): string | null {
+  const cgroup = readCgroup(proc.pid);
+  const scoped = cgroup ? appIdFromCgroup(cgroup) : null;
+  if (scoped) {
+    const entry = entries.get(scoped);
+    // A scope naming an id no entry defines is still not an app PPM can show:
+    // it has no name and no icon to draw.
+    if (entry && !entry.noDisplay) return scoped;
+    return null;
+  }
+  // Not in an app scope. Only an exact executable-name match counts, so a shell
+  // or an editor started by something else is not attributed to an app.
+  const id = byBinary.get(proc.name);
+  return id && !entries.get(id)?.noDisplay ? id : null;
+}
+
+/** Production wiring: the real XDG dirs and the real /proc. */
+export function createLinuxAppCollector(fs: LinuxFs = realLinuxFs) {
+  const dirs = desktopDirs(process.env, process.env.HOME ?? "/root");
+  let entries: Map<string, DesktopEntry> | null = null;
+  return {
+    /** Desktop entries change only when a package is installed; read once. */
+    entries(): Map<string, DesktopEntry> {
+      entries ??= loadDesktopEntries(dirs, fs);
+      return entries;
+    },
+    collect(processes: readonly AppProcess[]): AppInfo[] {
+      return collectApps({
+        processes,
+        entries: this.entries(),
+        readCgroup: (pid) => fs.read(`/proc/${pid}/cgroup`),
+      });
+    },
+  };
+}
+
+export type LinuxAppCollector = ReturnType<typeof createLinuxAppCollector>;

package/src/services/system-services/desktop-entry.ts

@@ -0,0 +1,103 @@
+/**
+ * freedesktop `.desktop` parsing for the Apps page - Mission Center's app list.
+ *
+ * MC delegates this to its own `app-rummage` crate; PPM parses the entries
+ * directly because it only needs four fields, and the matching is done from
+ * systemd's app cgroups (see `app-cgroup-linux.ts`), which name the desktop id
+ * outright rather than guessing it from an executable path.
+ *
+ * Pure: every function takes the file's text. Nothing here touches the disk.
+ */
+
+export interface DesktopEntry {
+  /** File name without the suffix - the id systemd's app cgroups carry. */
+  id: string;
+  name: string;
+  /** A theme icon name or an absolute path. Null when the entry has none. */
+  icon: string | null;
+  /** Exec with the field codes removed. Null when the entry has none. */
+  exec: string | null;
+  /** The author asked for this entry not to appear in menus. */
+  noDisplay: boolean;
+}
+
+/**
+ * The percent-codes an Exec may carry. The launcher substitutes files and URLs
+ * for them, so one left in the string would be shown to the user and would break
+ * any comparison against a real command line.
+ */
+const FIELD_CODES = /%[fFuUdDnNickvm]/g;
+/** A doubled percent is a literal one; parking it keeps the round trip lossless. */
+const PERCENT_SENTINEL = " PPM_PCT ";
+
+export function stripFieldCodes(exec: string): string {
+  return exec
+    .replaceAll("%%", PERCENT_SENTINEL)
+    .replace(FIELD_CODES, " ")
+    .replaceAll(PERCENT_SENTINEL, "%")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+/**
+ * Reads the `[Desktop Entry]` group only. An entry's actions live in their own
+ * `[Desktop Action ...]` groups with their own Name, Icon and Exec, so a parser
+ * that scans the whole file takes the LAST action's name as the app's.
+ *
+ * Returns null for anything that is not a launchable application: a Link entry,
+ * `Hidden=true` (the spec says treat it as deleted) and an entry with no Name.
+ */
+export function parseDesktopEntry(id: string, text: string): DesktopEntry | null {
+  const fields: Record<string, string> = {};
+  let inGroup = false;
+  for (const raw of text.split("\n")) {
+    const line = raw.trim();
+    if (line.startsWith("[")) {
+      inGroup = line === "[Desktop Entry]";
+      continue;
+    }
+    if (!inGroup || !line || line.startsWith("#")) continue;
+    const eq = line.indexOf("=");
+    if (eq <= 0) continue;
+    const key = line.slice(0, eq).trim();
+    // A bracketed key is a translation. PPM shows the unlocalised value so the
+    // id, the list and any log line all name the app the same way.
+    if (key.includes("[")) continue;
+    if (fields[key] === undefined) fields[key] = line.slice(eq + 1).trim();
+  }
+
+  if (fields.Type !== "Application") return null;
+  if (fields.Hidden === "true") return null;
+  const name = fields.Name?.trim();
+  if (!name) return null;
+
+  const exec = fields.Exec ? stripFieldCodes(fields.Exec) : "";
+  return {
+    id,
+    name,
+    icon: fields.Icon?.trim() || null,
+    exec: exec || null,
+    noDisplay: fields.NoDisplay === "true",
+  };
+}
+
+/**
+ * The program an Exec actually runs, as a bare file name - the fallback match for
+ * an app started outside a systemd app scope (from a terminal, say), where there
+ * is no cgroup to read the id from.
+ *
+ * Leading assignments and an `env` wrapper are skipped: an Exec of
+ * `env GDK_BACKEND=x11 /usr/bin/foo` runs foo, not env.
+ */
+export function execBinary(exec: string | null): string | null {
+  if (!exec) return null;
+  const tokens = exec.match(/"[^"]*"|\S+/g) ?? [];
+  for (const token of tokens) {
+    const t = token.replace(/^"|"$/g, "");
+    if (!t || t === "env" || t.includes("=")) continue;
+    const slash = t.lastIndexOf("/");
+    const base = slash >= 0 ? t.slice(slash + 1) : t;
+    return base || null;
+  }
+  return null;
+}

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

@@ -0,0 +1,124 @@
+/**
+ * Which service actions PPM refuses, and why.
+ *
+ * Mission Center refuses nothing — it asks systemd and lets polkit decide. PPM
+ * cannot: it is *inside* one of the units it lists, so "stop ppm.service" would
+ * end the request mid-flight and leave the user with no way back in. The refusal
+ * is derived from PPM's own cgroup rather than a hardcoded unit name, so it is
+ * still right when the unit is renamed, run system-wide, or run under a
+ * different user manager.
+ *
+ * One function produces both the per-row `refused` map and the route's verdict,
+ * so a disabled button and a 403 can never disagree.
+ */
+import type { ServiceAction, ServiceScope } from "../../types/system-services.ts";
+import { SERVICE_ACTIONS } from "../../types/system-services.ts";
+import { systemdHierarchy } from "./app-cgroup-linux.ts";
+
+/** Actions that take a running unit away. `start` and `enable` never do. */
+const DISRUPTIVE: readonly ServiceAction[] = ["stop", "restart", "disable"];
+
+/**
+ * Units whose loss takes the session or the machine with it. Stopping journald
+ * or the message bus is not recoverable from a web UI, and `-.mount` is the root
+ * filesystem.
+ */
+export const CRITICAL_UNITS: readonly string[] = [
+  "-.mount",
+  "dbus.service",
+  "dbus.socket",
+  "dbus-broker.service",
+  "systemd-journald.service",
+  "systemd-journald.socket",
+  "systemd-logind.service",
+  "systemd-udevd.service",
+  "init.scope",
+];
+
+export interface ServiceGuardContext {
+  /** `/proc/self/cgroup`'s path for PPM itself. Null → only the static list applies. */
+  selfCgroup: string | null;
+}
+
+/**
+ * The unit names on PPM's own cgroup path, innermost last:
+ * `/user.slice/user-1000.slice/user@1000.service/app.slice/ppm.service`
+ * → `["user@1000.service", "ppm.service"]`.
+ *
+ * Slices are not returned: they are not one of the three unit types the page
+ * lists, so they can never be the target of an action anyway.
+ *
+ * The file is parsed by `systemdHierarchy` rather than split directly. Two
+ * reasons, and both are the difference between refusing PPM's own unit and
+ * offering a Stop button for it. The kernel terminates the line, so a direct
+ * split ends on `"ppm.service\n"`, which no suffix test matches. And under
+ * cgroup v1 the file is one line per controller, whose hierarchies need not
+ * agree — only the `name=systemd` line describes the unit tree.
+ */
+export function selfUnitChain(cgroup: string | null): string[] {
+  if (!cgroup) return [];
+  const path = systemdHierarchy(cgroup);
+  if (!path) return [];
+  return path
+    .split("/")
+    .filter((part) => part.endsWith(".service") || part.endsWith(".scope") || part.endsWith(".socket"));
+}
+
+/** Every action this unit refuses, with the reason shown to the user. */
+export function serviceRefusals(
+  unit: string,
+  scope: ServiceScope,
+  ctx: ServiceGuardContext,
+): Partial<Record<ServiceAction, string>> {
+  const refusals: Partial<Record<ServiceAction, string>> = {};
+  const chain = selfUnitChain(ctx.selfCgroup);
+
+  if (chain.includes(unit)) {
+    const reason = unit === chain[chain.length - 1]
+      ? `${unit} is PPM itself — stopping it would end this session`
+      : `${unit} is the manager PPM runs under — stopping it would end this session`;
+    for (const action of DISRUPTIVE) refusals[action] = reason;
+    return refusals;
+  }
+
+  if (CRITICAL_UNITS.includes(unit)) {
+    const reason = `${unit} is required by the system — PPM will not stop it`;
+    for (const action of DISRUPTIVE) refusals[action] = reason;
+    return refusals;
+  }
+
+  // A user-scope unit named like the system manager cannot exist, so the scope
+  // is only carried for the message. Kept in the signature because the route
+  // passes it and a future scope-specific rule must not change every call site.
+  void scope;
+  return refusals;
+}
+
+export interface ServiceActionVerdict {
+  allowed: boolean;
+  reason?: string;
+}
+
+export function checkServiceActionAllowed(
+  unit: string,
+  scope: ServiceScope,
+  action: ServiceAction,
+  ctx: ServiceGuardContext,
+): ServiceActionVerdict {
+  if (!SERVICE_ACTIONS.includes(action)) return { allowed: false, reason: `Unknown action "${action}"` };
+  // A unit name reaches `systemctl` as one argv element, never a shell string,
+  // but it is still bounded here: anything with a slash or whitespace in it is
+  // not a unit name and has no business being passed on.
+  if (!isPlausibleUnitName(unit)) return { allowed: false, reason: "Not a unit name" };
+  const reason = serviceRefusals(unit, scope, ctx)[action];
+  return reason ? { allowed: false, reason } : { allowed: true };
+}
+
+/** systemd unit names: no slash, no whitespace, bounded length. */
+export function isPlausibleUnitName(unit: string): boolean {
+  return typeof unit === "string"
+    && unit.length > 0
+    && unit.length <= 256
+    && !/[\s/]/.test(unit)
+    && /\.[a-z]+$/.test(unit);
+}

package/src/services/system-services/systemd-collector.ts

@@ -0,0 +1,203 @@
+/**
+ * The Services page's backend: TWO `systemctl` spawns for a whole scope's list,
+ * one more for a unit's details, one `journalctl` for its log.
+ *
+ * Two traps, both found against a real host and both load-bearing:
+ *
+ *  - A unit name may begin with a dash. The root mount is literally `-.mount`,
+ *    so every call that takes unit names passes them after `--`, or systemctl
+ *    reads the name as an option bundle and the whole call fails.
+ *  - An action without `--no-ask-password` can BLOCK on a polkit prompt nobody
+ *    can answer, turning "stop this unit" into a wedged request until the
+ *    timeout. PPM is not root, so a system-scope action is expected to be
+ *    refused by systemd; it must be refused quickly and reported plainly.
+ */
+import type {
+  ServiceAction, ServiceActionResult, ServiceDetails, ServiceInfo, ServiceLogLine,
+  ServiceScope, ServicesSnapshot,
+} from "../../types/system-services.ts";
+import type { RunResult, Runner } from "../host-info/spawn-runner.ts";
+import { defaultRunner } from "../host-info/spawn-runner.ts";
+import { realLinuxFs } from "../system-metrics/linux-fs.ts";
+import {
+  keepUnit, parseJournalJson, parseListUnits, parseShowBlock, parseShowRecords,
+  SHOW_DETAIL_PROPERTIES, SHOW_PROPERTIES, toServiceInfo, type ListUnitsRow,
+} from "./systemd-parse.ts";
+import { checkServiceActionAllowed, serviceRefusals, type ServiceGuardContext } from "./service-guard.ts";
+
+export const SYSTEMCTL_TIMEOUT_MS = 10_000;
+/** An action may legitimately take a while; a stop waits for the unit to settle. */
+export const ACTION_TIMEOUT_MS = 20_000;
+export const MAX_LOG_LINES = 200;
+
+export const SCOPES: readonly ServiceScope[] = ["system", "user"];
+
+export function systemctlArgv(scope: ServiceScope, args: readonly string[]): string[] {
+  return scope === "user" ? ["systemctl", "--user", ...args] : ["systemctl", ...args];
+}
+
+/** `--unit=<name>` rather than `--unit <name>`: see the dash trap above. */
+export function journalctlArgv(scope: ServiceScope, unit: string, lines: number): string[] {
+  const argv = ["journalctl"];
+  if (scope === "user") argv.push("--user");
+  argv.push(
+    `--unit=${unit}`, "--boot", `--lines=${lines}`,
+    "--no-pager", "--output=json", "--output-fields=MESSAGE",
+  );
+  return argv;
+}
+
+export interface SystemdDeps {
+  run: Runner;
+  guard: ServiceGuardContext;
+}
+
+/** Attaches the refusals this unit carries, from the same function the action
+ *  route enforces — so a greyed-out button and a 403 cannot disagree. */
+export function withRefusals(info: ServiceInfo, guard: ServiceGuardContext): ServiceInfo {
+  const refused = serviceRefusals(info.unit, info.scope, guard);
+  return Object.keys(refused).length > 0 ? { ...info, refused } : info;
+}
+
+export function failureText(result: RunResult): string {
+  if (result.timedOut) return "timed out";
+  return result.stderr.trim() || result.stdout.trim() || `exited ${result.code}`;
+}
+
+export interface ScopeListing {
+  services: ServiceInfo[];
+  warnings: string[];
+  /** False when this manager did not answer at all (no systemd, no user bus). */
+  ok: boolean;
+}
+
+export async function listScope(scope: ServiceScope, deps: SystemdDeps): Promise<ScopeListing> {
+  const list = await deps.run(systemctlArgv(scope, [
+    "list-units", "--type=service,socket,mount", "--all", "--no-legend", "--plain", "--no-pager",
+  ]), SYSTEMCTL_TIMEOUT_MS);
+  if (list.timedOut || list.code !== 0) {
+    return { services: [], warnings: [`${scope} services unavailable: ${failureText(list)}`], ok: false };
+  }
+
+  const rows = parseListUnits(list.stdout).filter(keepUnit);
+  if (rows.length === 0) return { services: [], warnings: [], ok: true };
+
+  const show = await deps.run(systemctlArgv(scope, [
+    "show", `--property=${SHOW_PROPERTIES.join(",")}`, "--no-pager", "--", ...rows.map((r) => r.unit),
+  ]), SYSTEMCTL_TIMEOUT_MS);
+
+  const warnings: string[] = [];
+  let byId = new Map<string, Record<string, string>>();
+  if (show.timedOut || show.code !== 0) {
+    // The list still stands: LOAD/ACTIVE/SUB came from `list-units`. Only the
+    // unit-file state and the main pid are lost, so the page degrades rather
+    // than emptying.
+    warnings.push(`${scope} service details unavailable: ${failureText(show)}`);
+  } else {
+    byId = parseShowRecords(show.stdout);
+  }
+
+  const services = rows.map((row) => withRefusals(toServiceInfo(row, scope, byId.get(row.unit)), deps.guard));
+  return { services, warnings, ok: true };
+}
+
+export async function collectServices(deps: SystemdDeps): Promise<ServicesSnapshot> {
+  const listings = await Promise.all(SCOPES.map((scope) => listScope(scope, deps)));
+  return {
+    // Either manager answering is enough: a container commonly has the system
+    // one and no user session, and a headless server the other way round.
+    supported: listings.some((l) => l.ok),
+    services: listings.flatMap((l) => l.services),
+    warnings: listings.flatMap((l) => l.warnings),
+  };
+}
+
+export async function serviceLogs(
+  unit: string,
+  scope: ServiceScope,
+  deps: SystemdDeps,
+  lines: number = MAX_LOG_LINES,
+): Promise<ServiceLogLine[]> {
+  const result = await deps.run(journalctlArgv(scope, unit, lines), SYSTEMCTL_TIMEOUT_MS);
+  // Not gated on the exit code: journalctl exits non-zero for a unit with no
+  // entries this boot while still being perfectly healthy.
+  if (result.timedOut || !result.stdout.trim()) return [];
+  return parseJournalJson(result.stdout);
+}
+
+/** Null when the unit does not exist — the route turns that into a 404. */
+export async function serviceDetails(
+  unit: string,
+  scope: ServiceScope,
+  deps: SystemdDeps,
+): Promise<ServiceDetails | null> {
+  const show = await deps.run(systemctlArgv(scope, [
+    "show", `--property=${SHOW_DETAIL_PROPERTIES.join(",")}`, "--no-pager", "--", unit,
+  ]), SYSTEMCTL_TIMEOUT_MS);
+  if (show.timedOut || show.code !== 0) return null;
+
+  const record = parseShowBlock(show.stdout);
+  // `show` answers for a unit it has never heard of too, with LoadState=not-found
+  // and every other field blank. That is a 404, not a unit with no description.
+  if (!record.Id || record.LoadState === "not-found") return null;
+
+  const row: ListUnitsRow = {
+    unit: record.Id,
+    loadState: record.LoadState ?? "",
+    activeState: record.ActiveState ?? "",
+    subState: record.SubState ?? "",
+    description: record.Description ?? "",
+  };
+  const info = withRefusals(toServiceInfo(row, scope, record), deps.guard);
+  return {
+    ...info,
+    user: record.User || null,
+    group: record.Group || null,
+    fragmentPath: record.FragmentPath || null,
+    logs: await serviceLogs(record.Id, scope, deps),
+  };
+}
+
+/** Thrown when PPM's own guard refuses; the route maps it to 403, not 500. */
+export class ServiceActionRefused extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ServiceActionRefused";
+  }
+}
+
+export function actionFailureText(result: RunResult, scope: ServiceScope): string {
+  const text = failureText(result);
+  if (/interactive authentication required/i.test(text)) {
+    return scope === "system"
+      ? "systemd refused: PPM does not run as root, so system units cannot be changed from here"
+      : "systemd refused: this action needs an authentication PPM cannot provide";
+  }
+  return text;
+}
+
+export async function runServiceAction(
+  unit: string,
+  scope: ServiceScope,
+  action: ServiceAction,
+  deps: SystemdDeps,
+): Promise<ServiceActionResult> {
+  const verdict = checkServiceActionAllowed(unit, scope, action, deps.guard);
+  if (!verdict.allowed) throw new ServiceActionRefused(verdict.reason ?? "Refused");
+
+  const result = await deps.run(
+    systemctlArgv(scope, ["--no-ask-password", action, "--no-pager", "--", unit]),
+    ACTION_TIMEOUT_MS,
+  );
+  if (result.timedOut || result.code !== 0) throw new Error(actionFailureText(result, scope));
+  return { unit, scope, action };
+}
+
+/** PPM's own cgroup, which is what the guard derives its refusals from. */
+export function readSelfCgroup(): string | null {
+  return realLinuxFs.read("/proc/self/cgroup");
+}
+
+export function createSystemdServices(run: Runner = defaultRunner): SystemdDeps {
+  return { run, guard: { selfCgroup: readSelfCgroup() } };
+}