@hienlh/ppm 0.18.8 → 0.18.9

package/src/services/system-metrics/kill-identity-resolver.ts

@@ -0,0 +1,72 @@
+/**
+ * Live re-query for a kill request. A pid is not an identity: Windows recycles
+ * pids fast enough that the `node` the user clicked two seconds ago can be
+ * `lsass` by the time the POST lands. The route therefore never authorises
+ * against the snapshot — it re-collects the process table (one round trip, the
+ * same per-OS source the tick uses), compares the client's `startedAt` claim
+ * with the live one, and hands the guard the FRESH name plus fresh ppid maps.
+ */
+import type { ProcessCollector, RawProcessRow } from "./process-collector-types.ts";
+
+export interface LiveProcessIdentity {
+  pid: number;
+  name: string;
+  startedAt: number;
+}
+
+/** macOS `ps` start times are 1 s resolution and other sources may be coarser. */
+export const IDENTITY_TOLERANCE_MS = 2000;
+
+/** An unknown start time (0) on either side cannot prove a mismatch. */
+export function identityMatches(claimedStartedAt: number, liveStartedAt: number): boolean {
+  if (!claimedStartedAt || !liveStartedAt) return true;
+  return Math.abs(claimedStartedAt - liveStartedAt) <= IDENTITY_TOLERANCE_MS;
+}
+
+export interface GuardMaps {
+  ppidOf: Map<number, number>;
+  startedAtOf: Map<number, number>;
+  byPid: Map<number, RawProcessRow>;
+  /** Rows that were refused because their pid was already present. */
+  warnings: string[];
+}
+
+/**
+ * A pid appears once in any real process table. A second row for the same pid
+ * can only be a forged line that slipped through the transport, so the FIRST
+ * row wins and the duplicate is refused — a forgery must never be able to
+ * overwrite the name the kill guard is about to trust.
+ */
+export function buildGuardMaps(rows: readonly RawProcessRow[]): GuardMaps {
+  const ppidOf = new Map<number, number>();
+  const startedAtOf = new Map<number, number>();
+  const byPid = new Map<number, RawProcessRow>();
+  const warnings: string[] = [];
+  for (const r of rows) {
+    if (byPid.has(r.pid)) {
+      warnings.push(`Duplicate row for PID ${r.pid} ignored (name "${r.name}")`);
+      continue;
+    }
+    byPid.set(r.pid, r);
+    ppidOf.set(r.pid, r.ppid);
+    startedAtOf.set(r.pid, r.startedAt);
+  }
+  return { ppidOf, startedAtOf, byPid, warnings };
+}
+
+export interface LiveResolution {
+  live: LiveProcessIdentity | null;
+  maps: GuardMaps;
+  warnings: string[];
+}
+
+export async function resolveLiveProcess(pid: number, collector: ProcessCollector): Promise<LiveResolution> {
+  const collection = await collector.collect();
+  const maps = buildGuardMaps(collection.rows);
+  const row = maps.byPid.get(pid);
+  return {
+    live: row ? { pid: row.pid, name: row.name, startedAt: row.startedAt } : null,
+    maps,
+    warnings: [...collection.warnings, ...maps.warnings],
+  };
+}

package/src/services/system-metrics/kill-request-handler.ts

@@ -0,0 +1,79 @@
+/**
+ * The kill decision chain, transport-free so it is testable without Hono:
+ *   parse → live re-query → identity check → guard on the FRESH name → execute.
+ * Authorising against the snapshot would authorise against data up to one tick
+ * old, and Windows recycles pids fast enough for that to matter.
+ */
+import type { KillProcessRequest, KillProcessResult, MetricsPlatform } from "../../types/system-metrics.ts";
+import { ok, err, type ApiResponse } from "../../types/api.ts";
+import type { ProcessCollector } from "./process-collector-types.ts";
+import { identityMatches, resolveLiveProcess } from "./kill-identity-resolver.ts";
+import { checkKillAllowed } from "./kill-guard.ts";
+import type { ProtectedPids } from "./ppm-protected-pids.ts";
+
+export interface KillHandlerDeps {
+  platform: MetricsPlatform;
+  collector: ProcessCollector;
+  resolveProtected: (isAlive: (pid: number) => boolean, nameOf: (pid: number) => string | undefined) => ProtectedPids;
+  execute: (pid: number, tree: boolean) => Promise<KillProcessResult>;
+  /** Audit line: pid + name + result ONLY. `~/.ppm/ppm.log`'s tail is served
+   *  unauthenticated by `/api/logs/recent`, so a command line must never land here. */
+  log: (line: string) => void;
+}
+
+export type KillStatus = 200 | 400 | 403 | 404 | 409 | 500;
+
+export interface KillOutcome {
+  status: KillStatus;
+  body: ApiResponse<KillProcessResult>;
+}
+
+export function parseKillRequest(body: unknown): KillProcessRequest | null {
+  if (!body || typeof body !== "object") return null;
+  const b = body as Record<string, unknown>;
+  const pid = b.pid;
+  const startedAt = b.startedAt;
+  if (typeof pid !== "number" || !Number.isInteger(pid) || pid <= 0) return null;
+  if (typeof startedAt !== "number" || !Number.isFinite(startedAt) || startedAt < 0) return null;
+  if (b.tree !== undefined && typeof b.tree !== "boolean") return null;
+  return { pid, startedAt, tree: b.tree === true };
+}
+
+export async function handleKillRequest(body: unknown, deps: KillHandlerDeps): Promise<KillOutcome> {
+  const req = parseKillRequest(body);
+  if (!req) return { status: 400, body: err("Body must be {pid: positive integer, startedAt: epoch ms, tree?: boolean}") };
+  const tree = req.tree === true;
+
+  const { live, maps } = await resolveLiveProcess(req.pid, deps.collector);
+  if (!live) return { status: 404, body: err(`PID ${req.pid} is no longer running`) };
+  if (!identityMatches(req.startedAt, live.startedAt)) {
+    return { status: 409, body: err(`PID ${req.pid} was recycled — refresh and try again`) };
+  }
+
+  const protectedPids = deps.resolveProtected(
+    (pid) => maps.byPid.has(pid),
+    (pid) => maps.byPid.get(pid)?.name.toLowerCase(),
+  );
+  const verdict = checkKillAllowed({ pid: live.pid, name: live.name }, tree, {
+    platform: deps.platform,
+    protectedPids: protectedPids.pids,
+    ppidOf: maps.ppidOf,
+    startedAtOf: maps.startedAtOf,
+  });
+  const prefix = `[SystemMetrics] kill pid=${live.pid} name=${live.name} tree=${tree}`;
+  if (!verdict.allowed) {
+    deps.log(`${prefix} → refused: ${verdict.reason}`);
+    return { status: 403, body: err(verdict.reason ?? "Refused") };
+  }
+
+  deps.log(`${prefix} → allowed`);
+  try {
+    const result = await deps.execute(live.pid, tree);
+    deps.log(`${prefix} → done (${result.method}, ${result.killed.length} signalled)`);
+    return { status: 200, body: ok(result) };
+  } catch (e) {
+    const message = (e as Error)?.message ?? String(e);
+    deps.log(`${prefix} → failed: ${message}`);
+    return { status: 500, body: err(`Failed to end PID ${live.pid}: ${message}`) };
+  }
+}

package/src/services/system-metrics/metrics-collector-lock.ts

@@ -0,0 +1,36 @@
+/**
+ * One holder at a time for the process collector. The PowerShell session takes
+ * a single request at a time, and a kill re-collects through the same collector
+ * the poll tick uses — so a kill waits for an in-flight tick, while a tick that
+ * arrives during a kill (or another tick) is simply skipped: metrics are lossy,
+ * a dropped poll is harmless, but two overlapping collections would either fail
+ * with "request already in flight" or double-consume the CPU delta baseline.
+ */
+export class CollectorLock {
+  private inflight: Promise<unknown> | null = null;
+
+  isHeld(): boolean {
+    return this.inflight !== null;
+  }
+
+  /** Run now if free, otherwise skip and resolve to `null`. */
+  async tryRun<T>(work: () => Promise<T>): Promise<T | null> {
+    if (this.inflight) return null;
+    return this.hold(work());
+  }
+
+  /** Wait for the current holder (however it ends), then run. */
+  async runExclusive<T>(work: () => Promise<T>): Promise<T> {
+    while (this.inflight) await this.inflight.catch(() => {});
+    return this.hold(work());
+  }
+
+  private async hold<T>(p: Promise<T>): Promise<T> {
+    this.inflight = p;
+    try {
+      return await p;
+    } finally {
+      this.inflight = null;
+    }
+  }
+}

package/src/services/system-metrics/metrics-poll-scheduler.ts

@@ -0,0 +1,83 @@
+/**
+ * Turns live subscriber demand into exactly one poll timer, plus the delayed
+ * child teardown when full-tier demand disappears. Timers follow demand:
+ * ≥1 full subscriber → full cadence; else ≥1 light → light cadence; else none.
+ */
+import type { MetricsTier } from "../../types/system-metrics.ts";
+
+export interface PollSchedulerOptions {
+  intervals: { full: number; light: number };
+  /** Grace before `onIdle` fires after the last full subscriber leaves, so a
+   *  window reopen does not pay the PowerShell bootstrap again. */
+  idleTeardownMs: number;
+  onTick: () => void;
+  /** Full-tier demand has been absent for the whole grace period. */
+  onIdle: () => void;
+  /** Full-tier collection is about to start for the first time. */
+  onFullStart: () => void;
+}
+
+export class PollScheduler {
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private idleTimer: ReturnType<typeof setTimeout> | null = null;
+  private tier: MetricsTier | null = null;
+
+  constructor(private readonly opts: PollSchedulerOptions) {}
+
+  activeTier(): MetricsTier | null {
+    return this.tier;
+  }
+
+  /** Returns true when the active tier changed (so delta baselines may need a reset). */
+  reconcile(fullCount: number, lightCount: number): boolean {
+    const desired: MetricsTier | null = fullCount > 0 ? "full" : lightCount > 0 ? "light" : null;
+    if (desired === "full") this.clearIdle();
+    else if (this.tier === "full") this.armIdle();
+    if (desired === this.tier) return false;
+
+    if (this.timer) clearInterval(this.timer);
+    this.timer = null;
+    this.tier = desired;
+    if (desired === "full") this.opts.onFullStart();
+    if (desired) {
+      this.timer = setInterval(this.opts.onTick, this.opts.intervals[desired]);
+      this.opts.onTick();
+    }
+    return true;
+  }
+
+  /** Re-arm the idle teardown after an out-of-band full collection (a kill). */
+  armIdle(): void {
+    this.clearIdle();
+    this.idleTimer = setTimeout(() => {
+      this.idleTimer = null;
+      if (this.tier !== "full") this.opts.onIdle();
+    }, this.opts.idleTeardownMs);
+  }
+
+  stop(): void {
+    if (this.timer) clearInterval(this.timer);
+    this.timer = null;
+    this.tier = null;
+    this.clearIdle();
+  }
+
+  private clearIdle(): void {
+    if (this.idleTimer) clearTimeout(this.idleTimer);
+    this.idleTimer = null;
+  }
+}
+
+const installedTeardowns = new WeakSet<() => void>();
+
+/** A hard exit must not leave a PowerShell child holding the server's
+ *  inheritable listening socket (the zombie-port state). The server's own
+ *  SIGTERM/SIGINT handler calls `process.exit`, which fires `exit` — so this
+ *  hook only tears down and never exits itself. Installed once per teardown fn. */
+export function installProcessExitHooks(teardown: () => void): void {
+  if (installedTeardowns.has(teardown)) return;
+  installedTeardowns.add(teardown);
+  process.on("exit", teardown);
+  process.on("SIGTERM", teardown);
+  process.on("SIGINT", teardown);
+}

package/src/services/system-metrics/metrics-subscriber-registry.ts

@@ -0,0 +1,85 @@
+/**
+ * SSE subscriber leases. A proxy in front of PPM (Cloudflare Tunnel) may keep
+ * the origin request alive after the browser left, so `cancel()` cannot be
+ * trusted: each subscriber holds a lease the client renews by pinging, and the
+ * server reaps silent ones. Without this, a phone that closed its tab would keep
+ * the PowerShell child running forever and burn one of the five stream slots.
+ */
+import type { MetricsSnapshot, MetricsTier } from "../../types/system-metrics.ts";
+
+export interface MetricsSubscriber {
+  sid: string;
+  tier: MetricsTier;
+  lastPingAt: number;
+  deliver: (snapshot: MetricsSnapshot) => void;
+  /** Called once when the server drops the subscriber (reap or explicit stop). */
+  close: () => void;
+}
+
+export const SID_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
+
+/** Accept only a short opaque id so a hostile query cannot bloat the map. */
+export function isValidSid(raw: string | undefined): raw is string {
+  return typeof raw === "string" && SID_PATTERN.test(raw);
+}
+
+export class SubscriberRegistry {
+  private readonly subs = new Map<string, MetricsSubscriber>();
+
+  add(sub: MetricsSubscriber): void {
+    this.subs.set(sub.sid, sub);
+  }
+
+  has(sid: string): boolean {
+    return this.subs.has(sid);
+  }
+
+  /** Remove and end the stream, so an explicit DELETE also closes the HTTP
+   *  response a proxy might otherwise hold open. `close` must be idempotent. */
+  remove(sid: string): boolean {
+    const s = this.subs.get(sid);
+    if (!s) return false;
+    this.subs.delete(sid);
+    try { s.close(); } catch { /* stream already gone */ }
+    return true;
+  }
+
+  ping(sid: string, now: number): boolean {
+    const s = this.subs.get(sid);
+    if (!s) return false;
+    s.lastPingAt = now;
+    return true;
+  }
+
+  /** Drop and close every lease silent for longer than `timeoutMs`. */
+  reap(now: number, timeoutMs: number): MetricsSubscriber[] {
+    const expired: MetricsSubscriber[] = [];
+    for (const s of this.subs.values()) {
+      if (now - s.lastPingAt > timeoutMs) expired.push(s);
+    }
+    for (const s of expired) {
+      this.subs.delete(s.sid);
+      try { s.close(); } catch { /* stream already gone */ }
+    }
+    return expired;
+  }
+
+  count(tier?: MetricsTier): number {
+    if (!tier) return this.subs.size;
+    let n = 0;
+    for (const s of this.subs.values()) if (s.tier === tier) n++;
+    return n;
+  }
+
+  list(tier: MetricsTier): MetricsSubscriber[] {
+    return [...this.subs.values()].filter((s) => s.tier === tier);
+  }
+
+  /** Close everything — server shutdown. */
+  clear(): void {
+    for (const s of this.subs.values()) {
+      try { s.close(); } catch { /* stream already gone */ }
+    }
+    this.subs.clear();
+  }
+}

package/src/services/system-metrics/powershell-session-bootstrap.ts

@@ -0,0 +1,48 @@
+/**
+ * The PowerShell REPL bootstrap and the real spawner for the long-lived session.
+ *
+ * Why not `-Command -` with stdin scripts: PS 5.1 executes stdin line by line,
+ * so a multi-line construct makes the child exit 0 silently with no stderr.
+ * Instead this bootstrap IS the loop: one request = one line
+ * `<id> <base64(UTF-16LE script)>`, one reply = everything up to a literal
+ * `__END_<id>__` line. Per-request ids mean a hostile command line containing a
+ * sentinel can desync at most the one in-flight reply.
+ */
+
+/** One `-Command` string. `try{} catch{}` must stay one logical statement — a
+ *  semicolon before `catch` is a parse error that kills the child at startup
+ *  with `MissingCatchOrFinally`. */
+export const POWERSHELL_BOOTSTRAP = [
+  "[Console]::OutputEncoding=[Text.Encoding]::UTF8",
+  "$ErrorActionPreference='Continue'",
+  "$in=[Console]::In",
+  "while($true){ $line=$in.ReadLine(); if($null -eq $line){break}; if($line -eq ''){continue}; " +
+    "$sp=$line.IndexOf(' '); $id=$line.Substring(0,$sp); " +
+    "$code=[Text.Encoding]::Unicode.GetString([Convert]::FromBase64String($line.Substring($sp+1))); " +
+    "try { Invoke-Expression $code | Out-String -Width 1000000 -Stream | ForEach-Object { $_ } } catch { Write-Output ('__ERR__ ' + $_.Exception.Message) }; " +
+    "Write-Output ('__END_' + $id + '__') }",
+].join("; ");
+
+/** The minimal duplex surface the session needs, so tests can inject a fake. */
+export interface PsChild {
+  pid: number;
+  stdin: { write(data: string): unknown; flush?(): unknown };
+  stdout: ReadableStream<Uint8Array>;
+  stderr?: ReadableStream<Uint8Array> | null;
+  exited: Promise<number>;
+  kill(): void;
+}
+
+export type PsSpawner = () => PsChild;
+
+/** `-NoProfile`: a user profile can redefine cmdlets and poison the parse.
+ *  `-NonInteractive`: a prompt would wedge the pipe forever. */
+export const defaultPsSpawner: PsSpawner = () =>
+  Bun.spawn(["powershell.exe", "-NoProfile", "-NonInteractive", "-Command", POWERSHELL_BOOTSTRAP], {
+    stdin: "pipe", stdout: "pipe", stderr: "pipe", windowsHide: true,
+  }) as unknown as PsChild;
+
+/** Encode one request line. The id is a small monotonic counter, never user input. */
+export function encodeRequestLine(id: string, script: string): string {
+  return `${id} ${Buffer.from(script, "utf16le").toString("base64")}\n`;
+}

package/src/services/system-metrics/powershell-session.ts

@@ -0,0 +1,182 @@
+/**
+ * ONE long-lived PowerShell child for the polling lifetime.
+ *
+ * Why not spawn per tick: every `powershell.exe` spawn costs a 32 MiB allocator
+ * segment Bun never returns to the OS (see windows-process-tree.ts) and ~400 ms
+ * versus ~140 ms in-session. Requests are serialised, time-limited, and a
+ * failed child may be restarted only a fixed number of times for the server's
+ * whole life — a refilling budget would re-arm against a permanently wedged
+ * CIM provider and spawn hundreds of times a day.
+ */
+import { defaultPsSpawner, encodeRequestLine, type PsChild, type PsSpawner } from "./powershell-session-bootstrap.ts";
+
+export { POWERSHELL_BOOTSTRAP, defaultPsSpawner, type PsChild, type PsSpawner } from "./powershell-session-bootstrap.ts";
+
+export interface PowerShellSessionOptions {
+  spawn?: PsSpawner;
+  /** Measured p95 real tick is 206 ms; 5 s only fires on a wedged CIM provider. */
+  requestTimeoutMs?: number;
+  /** Absolute cap for the server's lifetime — a refilling budget would re-arm
+   *  against a permanently wedged provider and spawn hundreds of times a day. */
+  maxRestarts?: number;
+  /** Child working set creeps over hours; a scheduled recycle is free of the budget. */
+  recycleAfterMs?: number;
+  now?: () => number;
+}
+
+export const PS_DISABLED_WARNING = "Windows process collection disabled after repeated PowerShell failures";
+
+export class PsSessionBusyError extends Error { constructor() { super("PowerShell request already in flight"); } }
+export class PsSessionDisabledError extends Error { constructor() { super(PS_DISABLED_WARNING); } }
+
+interface Pending { id: string; resolve: (s: string) => void; reject: (e: Error) => void; timer: ReturnType<typeof setTimeout> }
+
+/** Anything larger than this without an end marker is not a reply we want. */
+const MAX_BUFFER_CHARS = 8 * 1024 * 1024;
+
+export class PowerShellSession {
+  private readonly spawn: PsSpawner;
+  private readonly requestTimeoutMs: number;
+  private readonly maxRestarts: number;
+  private readonly recycleAfterMs: number;
+  private readonly now: () => number;
+
+  private child: PsChild | null = null;
+  private generation = 0;
+  private spawnedAt = 0;
+  private restarts = 0;
+  private everStarted = false;
+  private previousDiedAbnormally = false;
+  private disabled = false;
+  private buffer = "";
+  private pending: Pending | null = null;
+  private nextId = 1;
+
+  constructor(opts: PowerShellSessionOptions = {}) {
+    this.spawn = opts.spawn ?? defaultPsSpawner;
+    this.requestTimeoutMs = opts.requestTimeoutMs ?? 5000;
+    this.maxRestarts = opts.maxRestarts ?? 5;
+    this.recycleAfterMs = opts.recycleAfterMs ?? 6 * 60 * 60 * 1000;
+    this.now = opts.now ?? Date.now;
+  }
+
+  isHealthy(): boolean { return this.child !== null && !this.disabled; }
+  isDisabled(): boolean { return this.disabled; }
+  isBusy(): boolean { return this.pending !== null; }
+  restartCount(): number { return this.restarts; }
+  childPid(): number | null { return this.child?.pid ?? null; }
+
+  request(script: string): Promise<string> {
+    if (this.disabled) return Promise.reject(new PsSessionDisabledError());
+    if (this.pending) return Promise.reject(new PsSessionBusyError());
+    if (this.child && this.now() - this.spawnedAt >= this.recycleAfterMs) this.stop();
+    if (!this.child) {
+      try { this.start(); } catch (e) { return Promise.reject(e as Error); }
+    }
+    const child = this.child!;
+    const id = String(this.nextId++);
+    return new Promise<string>((resolve, reject) => {
+      const timer = setTimeout(() => this.onFailure(`PowerShell request timed out after ${this.requestTimeoutMs} ms`), this.requestTimeoutMs);
+      this.pending = { id, resolve, reject, timer };
+      try {
+        child.stdin.write(encodeRequestLine(id, script));
+        child.stdin.flush?.();
+      } catch (e) {
+        this.onFailure(`PowerShell stdin write failed: ${(e as Error).message}`);
+      }
+    });
+  }
+
+  /** Write nothing, kill, clear. Safe to call repeatedly. No subscribers must mean no child. */
+  stop(): void {
+    this.teardown(new Error("PowerShell session stopped"));
+  }
+
+  private teardown(pendingError: Error): void {
+    const child = this.child;
+    this.child = null;
+    this.generation++;
+    this.buffer = "";
+    this.failPending(pendingError);
+    if (child) { try { child.kill(); } catch { /* already gone */ } }
+  }
+
+  private start(): void {
+    if (this.everStarted && this.previousDiedAbnormally) {
+      if (this.restarts >= this.maxRestarts) {
+        this.disabled = true;
+        throw new PsSessionDisabledError();
+      }
+      this.restarts++;
+    }
+    this.everStarted = true;
+    this.previousDiedAbnormally = false;
+    const gen = ++this.generation;
+    const child = this.spawn();
+    this.child = child;
+    this.spawnedAt = this.now();
+    this.buffer = "";
+    void this.pump(child, gen);
+    void drain(child.stderr);
+    child.exited.then(
+      () => { if (gen === this.generation) this.onFailure("PowerShell exited unexpectedly"); },
+      () => { if (gen === this.generation) this.onFailure("PowerShell exited unexpectedly"); },
+    );
+  }
+
+  private async pump(child: PsChild, gen: number): Promise<void> {
+    const reader = child.stdout.getReader();
+    const decoder = new TextDecoder();
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done || gen !== this.generation) break;
+        this.buffer += decoder.decode(value, { stream: true });
+        this.scan();
+      }
+    } catch { /* stream torn down with the child */ }
+    if (gen === this.generation) this.onFailure("PowerShell stdout closed");
+  }
+
+  /** Resolve the pending request on ITS marker; discard any stale marker's output. */
+  private scan(): void {
+    while (true) {
+      const m = /__END_(\d+)__/.exec(this.buffer);
+      if (!m) {
+        if (this.buffer.length > MAX_BUFFER_CHARS) this.buffer = "";
+        return;
+      }
+      const reply = this.buffer.slice(0, m.index);
+      this.buffer = this.buffer.slice(m.index + m[0].length).replace(/^\r?\n/, "");
+      const p = this.pending;
+      if (p && p.id === m[1]) {
+        this.pending = null;
+        clearTimeout(p.timer);
+        p.resolve(reply);
+      }
+    }
+  }
+
+  /** Timeout, exit or write failure: kill, mark for a counted restart, reject. */
+  private onFailure(reason: string): void {
+    this.previousDiedAbnormally = true;
+    this.teardown(new Error(reason));
+  }
+
+  private failPending(error: Error): void {
+    const p = this.pending;
+    if (!p) return;
+    this.pending = null;
+    clearTimeout(p.timer);
+    p.reject(error);
+  }
+}
+
+/** A full stderr pipe would block the child; read and discard it. */
+async function drain(stream: ReadableStream<Uint8Array> | null | undefined): Promise<void> {
+  if (!stream) return;
+  try {
+    const reader = stream.getReader();
+    while (!(await reader.read()).done) { /* discard */ }
+  } catch { /* closed with the child */ }
+}

package/src/services/system-metrics/ppm-process-ownership.ts

@@ -0,0 +1,34 @@
+/**
+ * The cosmetic `ppm` flag: PPM's roots (server + supervisor/parent), every
+ * descendant of those roots, and the app share tunnel. Drives the "PPM only"
+ * filter in the UI. It is NOT a safety mechanism — the kill guard walks the
+ * ppid maps itself and never keys off this flag.
+ */
+import { collectDescendants } from "./kill-guard.ts";
+
+export interface PpmOwnershipInput {
+  roots: ReadonlySet<number>;
+  /** Extra pids owned outright (the share tunnel, preview tunnels). */
+  extraPids: readonly number[];
+  ppidOf: ReadonlyMap<number, number>;
+  startedAtOf: ReadonlyMap<number, number>;
+}
+
+/**
+ * Descendants follow ppid links only while the parent started no later than
+ * the child — Windows never clears a dead parent's ppid reference, so an
+ * unguarded walk would adopt whatever unrelated process later reused that pid.
+ */
+export function computePpmPids(input: PpmOwnershipInput): Set<number> {
+  const out = new Set<number>();
+  const ctx = { ppidOf: input.ppidOf, startedAtOf: input.startedAtOf };
+  for (const root of input.roots) {
+    if (!input.ppidOf.has(root)) continue;
+    out.add(root);
+    for (const pid of collectDescendants(root, ctx)) out.add(pid);
+  }
+  for (const pid of input.extraPids) {
+    if (input.ppidOf.has(pid)) out.add(pid);
+  }
+  return out;
+}