@hydranium/core 1.0.0-next.10

package/src/node/node-file-system-provider.ts

@@ -0,0 +1,252 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+import { type Tracer } from '@hydranium/protocol';
+import { URI, UriUtils } from '@hydranium/langium';
+import { NodeFileSystemProvider } from '@hydranium/langium/node';
+import { randomUUID } from 'node:crypto';
+import { realpathSync } from 'node:fs';
+import * as fsp from 'node:fs/promises';
+import { type WritableFileSystemProvider } from '../documents/ast-document-manager.js';
+import { type SelfSaveRegistry } from '../documents/self-save-registry.js';
+import { type LogNameOptions } from '../langium/diagnostics/logger.js';
+import { serverSharedFactory, type ServerSharedServicesMinimal } from '../langium/shared-services.js';
+import { serveVirtualDocument } from '../langium/workspace/virtual-document.js';
+
+/**
+ * Node-based default {@link WritableFileSystemProvider}. Extends Langium's
+ * {@link NodeFileSystemProvider} with an async {@link writeFile} that
+ * creates parent directories on demand, replaces the target indivisibly unless
+ * that would break a hard link, and registers the resulting mtime with the
+ * {@link SelfSaveRegistry} bound at `services.workspace.SelfSaveRegistry` — so
+ * consumers can suppress the `didChangeWatchedFiles` echo for their own writes.
+ *
+ * Server-only (`@hydranium/core/node`): pulls `node:fs`. The portable `.`
+ * entry binds `DefaultEmptyFileSystemProvider` by default, so a Node host
+ * must rebind this slot — through `context.fileSystemProvider` or directly — to
+ * get real disk I/O.
+ */
+export class DefaultFileSystemProvider extends NodeFileSystemProvider implements WritableFileSystemProvider {
+   readonly selfSaveRegistry: SelfSaveRegistry;
+   protected readonly tracer: Tracer;
+
+   constructor(
+      protected readonly services: ServerSharedServicesMinimal,
+      options: LogNameOptions = {}
+   ) {
+      super();
+      this.selfSaveRegistry = services.workspace.SelfSaveRegistry;
+      this.tracer = services.Tracer.for(options.logName ?? this.constructor.name).trace('instantiated');
+   }
+
+   // Serve virtual documents from the registered document before touching disk
+   // (a virtual URI has no `fsPath` backing); delegate everything else to Node.
+   override readFile(uri: URI): Promise<string> {
+      const served = serveVirtualDocument(this.services, uri);
+      return served !== undefined ? Promise.resolve(served) : super.readFile(uri);
+   }
+
+   override readFileSync(uri: URI): string {
+      return serveVirtualDocument(this.services, uri) ?? super.readFileSync(uri);
+   }
+
+   /**
+    * Write `content` to `uri` via a staging file and a `rename` — or, onto a
+    * destination carrying more than one hard link, in place — then register the
+    * resulting mtime with the {@link SelfSaveRegistry}.
+    *
+    * The rename is what makes the replacement indivisible: a concurrent reader
+    * observes either the previous complete file or the new one. An in-place
+    * overwrite cannot offer that, because the target is truncated before the
+    * first byte lands, so a reader in that window gets a short or empty file —
+    * and a model file that fails to parse is worse than one holding a previous
+    * good revision. It does NOT serialise writers: two writers still race, and
+    * the loser's content is replaced wholesale rather than interleaved.
+    *
+    * The destination is the RESOLVED path, via {@link realpath}: a `rename`
+    * onto a symlink replaces the link itself with a regular file and leaves the
+    * file it pointed at holding the previous revision, where an in-place write
+    * would have followed the link. A URI that resolves to nothing is the create
+    * case and stages beside its own path — which includes a DANGLING link,
+    * matching {@link realpath}, whose `undefined` there is the same "absent"
+    * answer the document-identity policy acts on.
+    *
+    * Three constraints on the staging file. It is a sibling of the RESOLVED
+    * DESTINATION and not of `uri` — `rename` is only indivisible within one
+    * filesystem, and a link can point across one. Its name carries the pid and
+    * a random component, so two writers cannot select the same path and destroy
+    * each other's staging copy. And it ends in a suffix no grammar claims, so a
+    * workspace scan crossing the window cannot mistake it for a document.
+    *
+    * Replacing a file carries its permission bits over, and the staging file is
+    * created no wider than them so the pending content is never briefly more
+    * readable than what it replaces. Ownership, extended attributes and ACLs are
+    * NOT carried over, so a target relying on any of them must not be written
+    * through here: an owner cannot be restored by a process that does not own
+    * it, and Node exposes no API to read the other two, so copying them would
+    * mean shelling out.
+    *
+    * A destination with more than one hard link is written IN PLACE instead,
+    * keeping the inode. Renaming over such a path gives it a NEW inode, so
+    * every other name silently keeps the previous revision — the same stale-read
+    * outcome the staging file exists to prevent, and it happens on every write
+    * rather than only under contention. Keeping the inode preserves all its
+    * names, plus the mode, owner, extended attributes and ACLs that hang off it,
+    * for free; what it gives up is indivisibility, so that one write CAN be read
+    * torn by a concurrent reader. Breaking a link is certain where tearing is
+    * only possible, which is what settles the trade.
+    */
+   async writeFile(uri: URI, content: string): Promise<void> {
+      await fsp.mkdir(UriUtils.dirname(uri).fsPath, { recursive: true });
+      const destination = this.realpath(uri)?.fsPath ?? uri.fsPath;
+      const replaced = await replacedFile(destination);
+      if (replaced !== undefined && replaced.links > 1) {
+         // Keeping the inode is the only way this write reaches the other names.
+         await fsp.writeFile(destination, content);
+      } else {
+         const staging = `${destination}.${process.pid}.${randomUUID()}.tmp`;
+         try {
+            const mode = replaced?.mode;
+            await fsp.writeFile(staging, content, { mode });
+            if (mode !== undefined) {
+               // `open` masks its mode argument with the umask, so the create
+               // above can only under-permit; an explicit chmod is what makes
+               // the carried mode exact.
+               await fsp.chmod(staging, mode);
+            }
+            await renameOverOpenReaders(staging, destination);
+         } catch (err: unknown) {
+            // A failed write must not leave the staging file behind for the next
+            // workspace scan or a later `--force` cleanup to trip over.
+            await fsp.rm(staging, { force: true });
+            throw err;
+         }
+      }
+      const mtimeMs = await this.mtimeMs(uri);
+      if (mtimeMs !== undefined) {
+         this.selfSaveRegistry.register(uri.fsPath, mtimeMs);
+      }
+   }
+
+   async mtimeMs(uri: URI): Promise<number | undefined> {
+      try {
+         const stat = await fsp.stat(uri.fsPath);
+         return stat.mtimeMs;
+      } catch {
+         // Missing file / stat failure — caller treats as "unknown".
+         return undefined;
+      }
+   }
+
+   /**
+    * Real on-disk identity of `uri` via `fs.realpathSync` — symlinks collapsed,
+    * `..`/`.` walked, case-folded on case-insensitive filesystems. A non-`file:`
+    * URI cannot be statted, so it passes through unchanged (treated as present).
+    * A resolution failure (missing / unreadable) returns `undefined` — the
+    * filesystem's "absent" signal the document-identity policy depends on.
+    *
+    * Uncached on purpose: `realpathSync` is a syscall, but the kernel caches the
+    * dentry/inode lookups it walks, so repeated resolution of a live path is
+    * cheap. A userspace cache would add a staleness hazard (a re-pointed symlink
+    * resolving to its old target with no invalidation) for no measured gain.
+    */
+   realpath(uri: URI): URI | undefined {
+      if (uri.scheme !== 'file') {
+         return uri;
+      }
+      try {
+         return URI.file(realpathSync(uri.fsPath));
+      } catch {
+         return undefined;
+      }
+   }
+}
+
+/**
+ * What a write has to know about the regular file at `path` before replacing
+ * it: the permission bits to carry over, and how many names share its inode.
+ * Both come off one stat, so neither costs a syscall the other does not.
+ */
+interface ReplacedFile {
+   /** Permission bits, masked to the mode a `chmod` takes. */
+   readonly mode: number;
+   /** `nlink` — above 1, a rename would strand every other name. */
+   readonly links: number;
+}
+
+/**
+ * Facts about the regular file `path` replaces, or `undefined` when there is
+ * nothing to replace — the path is absent (a create, which takes the process
+ * default mode and has no other name), or is not a regular file (a directory,
+ * where the write is about to fail anyway).
+ */
+async function replacedFile(path: string): Promise<ReplacedFile | undefined> {
+   try {
+      const stat = await fsp.stat(path);
+      return stat.isFile() ? { mode: stat.mode & 0o777, links: stat.nlink } : undefined;
+   } catch {
+      return undefined;
+   }
+}
+
+/**
+ * Errno values a rename reports on Windows when another handle holds the
+ * destination open. POSIX renames are unaffected by open handles, so this
+ * cannot fire there and the retry below costs nothing.
+ */
+const RENAME_CONTENTION_CODES = new Set(['EPERM', 'EACCES', 'EBUSY']);
+
+/**
+ * `rename` the staged content over `destination`, retrying while Windows
+ * reports the destination as held open.
+ *
+ * The staging file exists so a reader never sees a half-written file, and on
+ * Windows the very presence of that reader is what makes the replacing rename
+ * fail — so the indivisible write breaks under exactly the contention it was
+ * built for, and it breaks intermittently, which is worse than never working.
+ * A reader's handle is released in milliseconds, so waiting turns a spurious
+ * failure into a slightly later success.
+ *
+ * BOUNDED, not open-ended: a genuine permission fault raises the same errno and
+ * is distinguishable from contention only by never clearing, so an unbounded
+ * wait would convert a hard error into a hang. Exhausting the budget rethrows
+ * the last failure, leaving the caller's cleanup and error contract unchanged.
+ */
+async function renameOverOpenReaders(staging: string, destination: string): Promise<void> {
+   const deadline = Date.now() + 2_000;
+   for (let attempt = 0; ; attempt++) {
+      try {
+         await fsp.rename(staging, destination);
+         return;
+      } catch (err: unknown) {
+         const code = err instanceof Error && 'code' in err ? String((err as NodeJS.ErrnoException).code) : undefined;
+         if (code === undefined || !RENAME_CONTENTION_CODES.has(code) || Date.now() >= deadline) {
+            throw err;
+         }
+         // Backs off to keep a long contention window from spinning, capped so
+         // a late attempt still lands promptly once the handle is released.
+         await new Promise(resolve => setTimeout(resolve, Math.min(2 ** attempt, 50)));
+      }
+   }
+}
+
+/**
+ * Module fragment that binds the writable Node {@link DefaultFileSystemProvider},
+ * spread into the services context on a Node host.
+ *
+ * The framework counterpart to Langium's `NodeFileSystem` (`langium/node`): same
+ * role, but supplies the *writable* provider (`writeFile` + `mtimeMs`) the
+ * framework slot requires. Langium's fragment cannot stand in for it — its
+ * provider carries no `writeFile`, so the slot silently falls back to
+ * `DefaultEmptyFileSystemProvider` and the host gets no-op writes and a
+ * throwing `readFile` instead of disk access.
+ */
+export const NodeFileSystem = {
+   fileSystemProvider: serverSharedFactory(services => new DefaultFileSystemProvider(services))
+};

package/src/node/process-memory.ts

@@ -0,0 +1,299 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+/*
+ * Node-only process- and pod-level memory introspection plus heap-snapshot
+ * writing. Everything here is generic OS-level code (V8 stats, cgroup v2/v1,
+ * `/proc`); the only host-specific part is naming the processes, which a head
+ * supplies through a `ProcessClassifier`.
+ */
+
+import { Format } from '@hydranium/protocol';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import * as v8 from 'node:v8';
+
+/**
+ * Format a one-shot memory snapshot of the CURRENT process (heap, rss, external, V8 limit).
+ * Suited to a process that hosts no Langium documents (e.g. a host backend); for the
+ * language-server process with document counts, see `formatServerState`.
+ */
+export function formatProcessMemory(label: string): string {
+   const mem = process.memoryUsage();
+   const heap = v8.getHeapStatistics();
+   const heapPercent = Math.round((mem.heapUsed / heap.heap_size_limit) * 100);
+   return [
+      `${label}:`,
+      `  heap      ${Format.bytes(mem.heapUsed)} used / ${Format.bytes(mem.heapTotal)} total / ` +
+         `${Format.bytes(heap.heap_size_limit)} limit (${heapPercent}% of limit)`,
+      `  rss       ${Format.bytes(mem.rss)}, external ${Format.bytes(mem.external)}, arrayBuffers ${Format.bytes(mem.arrayBuffers)}`,
+      `  uptime    ${Math.round(process.uptime())}s, pid ${process.pid}`
+   ].join('\n');
+}
+
+/**
+ * Compose an absolute artifact file path of the form `<prefix>[-<label>].<ext>` inside
+ * {@link directory} (e.g. the workspace folder, so it lands on the persistent volume in cloud and
+ * is visible in the file explorer), falling back to the OS temp dir when the directory is missing
+ * or does not exist. The {@link prefix} carries the origin-first stem (e.g. `server-cpu`) and, when
+ * a non-empty {@link label} is given (a named capture window), it is sanitised (non-word characters
+ * → `_`, truncated to 40 chars) and appended as `-<label>`; an empty label yields the bare
+ * `<prefix>.<ext>` so the manifest `kind` equals the filename stem. No timestamp — a fresh session
+ * directory per run keeps names stable and collision-free. Shared by the heap-snapshot writer and
+ * the sampled-profile capture so heap / CPU / allocation artefacts land identically, differing only
+ * by extension.
+ */
+export function snapshotFilePath(directory: string | undefined, label: string, prefix: string, ext: string): string {
+   const safeLabel = label ? label.replace(/[^\w.-]+/g, '_').slice(0, 40) : '';
+   const dir = directory && fs.existsSync(directory) ? directory : os.tmpdir();
+   const stem = safeLabel ? `${prefix}-${safeLabel}` : prefix;
+   return path.join(dir, `${stem}.${ext}`);
+}
+
+/**
+ * Write a V8 heap snapshot of the CURRENT process to {@link directory}, falling back to the OS temp
+ * dir when it is missing (see {@link snapshotFilePath}). `v8.writeHeapSnapshot` runs a full GC first and
+ * briefly pauses the process; it also transiently inflates RSS while serialising. Returns the
+ * absolute file path. The {@link prefix} (default `server-heap`, the origin-first stem) and
+ * {@link label} are folded into the name.
+ */
+export function writeHeapSnapshotToDir(directory: string | undefined, label: string, prefix = 'server-heap'): string {
+   const filePath = snapshotFilePath(directory, label, prefix, 'heapsnapshot');
+   v8.writeHeapSnapshot(filePath);
+   return filePath;
+}
+
+const CGROUP_ROOT = '/sys/fs/cgroup';
+
+function readNumber(file: string): number | undefined {
+   try {
+      const text = fs.readFileSync(file, 'utf8').trim();
+      if (text === 'max') {
+         return Number.POSITIVE_INFINITY;
+      }
+      const value = Number(text);
+      return Number.isFinite(value) ? value : undefined;
+   } catch {
+      return undefined;
+   }
+}
+
+/** Parse a `key value` per-line file (cgroup memory.stat) into a map. */
+function readKeyedBytes(file: string): Record<string, number> {
+   const out: Record<string, number> = {};
+   try {
+      for (const line of fs.readFileSync(file, 'utf8').split('\n')) {
+         const [key, value] = line.trim().split(/\s+/);
+         if (key && value !== undefined) {
+            const num = Number(value);
+            if (Number.isFinite(num)) {
+               out[key] = num;
+            }
+         }
+      }
+   } catch {
+      // file absent or unreadable; caller handles the empty map.
+   }
+   return out;
+}
+
+interface ProcInfo {
+   pid: number;
+   rssBytes: number;
+   label: string;
+}
+
+interface RawProc extends ProcInfo {
+   ppid: number;
+}
+
+/** A readable role for a process, whether it belongs to the app, and whether exactly one is expected. */
+export interface ProcessRole {
+   /** Human-readable role shown in the snapshot. */
+   role: string;
+   /** Whether this process is part of the application (vs. tooling/debugger), counted in the app total. */
+   isApp: boolean;
+   /**
+    * Set when at most one instance of this role should exist; `formatPodMemory` warns when more than
+    * one is found (e.g. a duplicated/ghost language server).
+    */
+   singletonExpected?: boolean;
+}
+
+/** Map a raw command line to a {@link ProcessRole}. A head supplies this to label its own processes. */
+export type ProcessClassifier = (cmdline: string) => ProcessRole;
+
+/** Generic fallback: every process is shown under the app heading, labelled by its (truncated) command line. */
+const defaultProcessClassifier: ProcessClassifier = cmdline => ({ role: cmdline ? cmdline.slice(0, 60) : 'process', isApp: true });
+
+/** Read /proc for every visible process: pid, ppid, RSS, and a command label. */
+function readAllProcs(): RawProc[] {
+   const procs: RawProc[] = [];
+   let entries: string[] = [];
+   try {
+      entries = fs.readdirSync('/proc');
+   } catch {
+      return procs;
+   }
+   for (const entry of entries) {
+      if (!/^\d+$/.test(entry)) {
+         continue;
+      }
+      let status = '';
+      try {
+         status = fs.readFileSync(`/proc/${entry}/status`, 'utf8');
+      } catch {
+         continue;
+      }
+      const rssMatch = status.match(/^VmRSS:\s+(\d+)\s+kB/m);
+      if (!rssMatch) {
+         continue;
+      }
+      const ppid = Number(status.match(/^PPid:\s+(\d+)/m)?.[1] ?? 0);
+      let label = '';
+      try {
+         label = fs.readFileSync(`/proc/${entry}/cmdline`, 'utf8').replace(/\0/g, ' ').trim();
+      } catch {
+         // fall back to the process name from status below.
+      }
+      if (!label) {
+         label = status.match(/^Name:\s+(.+)$/m)?.[1] ?? `pid ${entry}`;
+      }
+      procs.push({ pid: Number(entry), ppid, rssBytes: Number(rssMatch[1]) * 1024, label });
+   }
+   return procs;
+}
+
+/**
+ * Sum and list per-process RSS. When {@link rootPid} is given, restrict to that process and its
+ * descendants (the app's own process tree), which keeps the figure meaningful in local dev where
+ * /proc otherwise shows the whole machine. In a container's PID namespace the tree is effectively
+ * all the pod's processes anyway.
+ */
+function collectProcessRss(rootPid?: number): { total: number; processes: ProcInfo[]; scoped: boolean } {
+   const all = readAllProcs();
+   let selected: RawProc[] = all;
+   let scoped = false;
+   if (rootPid !== undefined) {
+      const childrenByPpid = new Map<number, RawProc[]>();
+      for (const proc of all) {
+         (childrenByPpid.get(proc.ppid) ?? childrenByPpid.set(proc.ppid, []).get(proc.ppid)!).push(proc);
+      }
+      const tree: RawProc[] = [];
+      const queue = all.filter(proc => proc.pid === rootPid);
+      while (queue.length > 0) {
+         const proc = queue.shift()!;
+         tree.push(proc);
+         queue.push(...(childrenByPpid.get(proc.pid) ?? []));
+      }
+      if (tree.length > 0) {
+         selected = tree;
+         scoped = true;
+      }
+   }
+   const total = selected.reduce((sum, proc) => sum + proc.rssBytes, 0);
+   selected.sort((a, b) => b.rssBytes - a.rssBytes);
+   return { total, processes: selected, scoped };
+}
+
+/** Options for {@link formatPodMemory}. */
+export interface PodMemoryOptions {
+   /** Map a process command line to a readable role; lets a head label its own processes. */
+   classify?: ProcessClassifier;
+   /** Heading for the in-app process group (default `Application`). */
+   appLabel?: string;
+}
+
+/**
+ * Format a pod/container-level memory snapshot read from the cgroup this process belongs to
+ * (cgroup v2 `memory.current`/`peak`/`max`/`stat`, falling back to cgroup v1). This is the figure
+ * the Kubernetes OOM-killer watches — it covers every process in the pod plus page cache and kernel
+ * memory, so it is higher than any single `process.memoryUsage().rss`. Also sums per-process RSS so
+ * the per-process split is visible. Explains itself when no cgroup memory controller is present
+ * (e.g. local dev outside a container).
+ */
+export function formatPodMemory(options: PodMemoryOptions = {}): string {
+   const classify = options.classify ?? defaultProcessClassifier;
+   const appLabel = options.appLabel ?? 'Application';
+   const lines: string[] = ['Pod memory snapshot:'];
+
+   const v2Current = path.join(CGROUP_ROOT, 'memory.current');
+   const v1Usage = path.join(CGROUP_ROOT, 'memory', 'memory.usage_in_bytes');
+
+   if (fs.existsSync(v2Current)) {
+      const current = readNumber(v2Current);
+      const peak = readNumber(path.join(CGROUP_ROOT, 'memory.peak'));
+      const max = readNumber(path.join(CGROUP_ROOT, 'memory.max'));
+      const stat = readKeyedBytes(path.join(CGROUP_ROOT, 'memory.stat'));
+      lines.push('  cgroup    v2');
+      lines.push(`  current   ${current !== undefined ? Format.bytes(current) : 'n/a'}`);
+      lines.push(`  peak      ${peak !== undefined ? Format.bytes(peak) : 'n/a (kernel too old for memory.peak)'}`);
+      lines.push(`  limit     ${max === Number.POSITIVE_INFINITY ? 'unlimited' : max !== undefined ? Format.bytes(max) : 'n/a'}`);
+      if (Object.keys(stat).length > 0) {
+         lines.push(
+            `  breakdown anon ${Format.bytes(stat.anon ?? 0)} (heaps/stacks), file ${Format.bytes(stat.file ?? 0)} (page cache), ` +
+               `kernel ${Format.bytes(stat.kernel ?? stat.slab ?? 0)}, sock ${Format.bytes(stat.sock ?? 0)}`
+         );
+      }
+   } else if (fs.existsSync(v1Usage)) {
+      const v1 = path.join(CGROUP_ROOT, 'memory');
+      const current = readNumber(v1Usage);
+      const peak = readNumber(path.join(v1, 'memory.max_usage_in_bytes'));
+      const limit = readNumber(path.join(v1, 'memory.limit_in_bytes'));
+      const stat = readKeyedBytes(path.join(v1, 'memory.stat'));
+      lines.push('  cgroup    v1');
+      lines.push(`  current   ${current !== undefined ? Format.bytes(current) : 'n/a'}`);
+      lines.push(`  peak      ${peak !== undefined ? Format.bytes(peak) : 'n/a'}`);
+      // v1 reports a huge sentinel for "unlimited"; treat anything >= 2^60 as unlimited.
+      lines.push(`  limit     ${limit !== undefined && limit < 2 ** 60 ? Format.bytes(limit) : 'unlimited'}`);
+      if (Object.keys(stat).length > 0) {
+         lines.push(
+            `  breakdown rss ${Format.bytes(stat.rss ?? 0)}, cache ${Format.bytes(stat.cache ?? 0)} (page cache), ` +
+               `kernel ${Format.bytes(stat.kernel ?? 0)}`
+         );
+      }
+   } else {
+      lines.push('  cgroup    no memory controller under /sys/fs/cgroup (not running in a container?)');
+   }
+
+   // Root at this process so local dev reports only the app's tree, not the whole machine.
+   const { processes } = collectProcessRss(process.pid);
+   if (processes.length > 0) {
+      const classified = processes.map(proc => ({ ...proc, ...classify(proc.label) }));
+      const appProcs = classified.filter(proc => proc.isApp);
+      const otherProcs = classified.filter(proc => !proc.isApp);
+      const appTotal = appProcs.reduce((sum, proc) => sum + proc.rssBytes, 0);
+
+      lines.push('');
+      lines.push(`  ${appLabel}: ${Format.bytes(appTotal)} across ${appProcs.length} process(es)`);
+      for (const proc of appProcs) {
+         lines.push(`    ${Format.bytes(proc.rssBytes).padStart(10)}  ${proc.role}  (pid ${proc.pid})`);
+      }
+      const singletonCounts = new Map<string, number>();
+      for (const proc of appProcs) {
+         if (proc.singletonExpected) {
+            singletonCounts.set(proc.role, (singletonCounts.get(proc.role) ?? 0) + 1);
+         }
+      }
+      for (const [role, count] of singletonCounts) {
+         if (count > 1) {
+            lines.push(`  WARNING: ${count} instances of "${role}" running - likely ghost process(es); expected 1`);
+         }
+      }
+      if (otherProcs.length > 0) {
+         const otherTotal = otherProcs.reduce((sum, proc) => sum + proc.rssBytes, 0);
+         lines.push(`  Other (tooling/debugger, not counted above): ${Format.bytes(otherTotal)} across ${otherProcs.length} process(es)`);
+      }
+      lines.push('  Note: in a real pod the cgroup figure above is the OOM ceiling; this per-process');
+      lines.push('  split is for attribution. Local dev may include debugger processes (excluded here).');
+   }
+
+   return lines.join('\n');
+}