@cleocode/core 2026.10.6 → 2026.10.7-rc.ci.674

package/dist/doctor/system-health.d.ts

@@ -0,0 +1,189 @@
+/**
+ * `cleo doctor system`: what is hurting this machine, ranked, with the exact
+ * remedy for each finding (T13435).
+ *
+ * On 2026-10-10 one Mac ran at 24 of 25 GB swap with load 24: 49 playwright-mcp,
+ * 33 mcpvault and ~60 agentmbx stdio MCP servers (one set per harness session),
+ * 475 dangling docker volumes from throwaway Postgres runs, long-lived database
+ * containers, and full typechecks started outside `cleo run`. None of it was
+ * visible from one place. This module makes it visible.
+ *
+ * Two halves, so the analysis is testable on any platform:
+ * - {@link collectSystemSnapshot} reads the machine: one resource sample
+ *   (reusing the governor's Darwin/Linux backends), one `ps`, the admission
+ *   ledger, docker (each call time-boxed, skipped when absent) and the
+ *   project's Spotlight/Time Machine state.
+ * - {@link assessSystemHealth} is pure: snapshot in, ranked report out.
+ *
+ * Read-only. It never signals a process. A remedy that deletes data or stops a
+ * process is marked `needsOwnerChoice` so the agent asks the owner first.
+ *
+ * @task T13435
+ * @epic T13434
+ */
+import type { ResourceSample } from '../resources/backend.js';
+import { type MemoryGuardAudit } from '../resources/memory-guard.js';
+/** How urgent a finding is. Findings are ranked by this, then by memory impact. */
+export type SystemFindingSeverity = 'critical' | 'warning' | 'info';
+/** One value in a finding's evidence. */
+export type SystemEvidenceValue = string | number | boolean | null | readonly string[];
+/** The fix for a finding. */
+export interface SystemRemedy {
+    /** The exact command to run, or `null` when the fix is a manual setting. */
+    readonly command: string | null;
+    /** What the remedy does, and what it costs. */
+    readonly description: string;
+}
+/** One ranked, agent-relayable finding. */
+export interface SystemFinding {
+    /** Stable id, e.g. `mcp-fanout:playwright-mcp`. */
+    readonly id: string;
+    /** Which check produced it. */
+    readonly category: SystemCheck;
+    readonly severity: SystemFindingSeverity;
+    /** One line for the owner. */
+    readonly title: string;
+    /** The measurements behind the verdict. */
+    readonly evidence: Readonly<Record<string, SystemEvidenceValue>>;
+    /** Resident memory the finding accounts for, in bytes, when known (ranking). */
+    readonly impactBytes: number | null;
+    readonly remedy: SystemRemedy | null;
+    /** True when the remedy deletes data, stops work or changes machine settings: ask the owner. */
+    readonly needsOwnerChoice: boolean;
+}
+/** The checks the report runs. */
+export type SystemCheck = 'memory' | 'mcp-fanout' | 'heavy-ungoverned' | 'containers' | 'sessions' | 'indexing' | 'memory-guard';
+/** Whether a check ran. A missing finding means healthy only when its check is `ok`. */
+export interface SystemCoverage {
+    readonly check: SystemCheck;
+    readonly status: 'ok' | 'skipped' | 'error';
+    readonly reason?: string;
+}
+/** The `cleo doctor system` result. */
+export interface SystemHealthReport {
+    readonly platform: NodeJS.Platform;
+    readonly sampledAt: string;
+    readonly summary: {
+        readonly critical: number;
+        readonly warning: number;
+        readonly info: number;
+    };
+    /** Worst first. */
+    readonly findings: readonly SystemFinding[];
+    readonly coverage: readonly SystemCoverage[];
+}
+/** Docker state, or `null` fields when a call failed. */
+export interface DockerSnapshot {
+    /** `docker volume ls -q -f dangling=true` output. */
+    readonly danglingVolumes: string | null;
+    /** `docker system df --format '{{json .}}'` output. */
+    readonly systemDf: string | null;
+    /** `docker ps --format '{{.ID}}\t{{.Names}}\t{{.Image}}\t{{.CreatedAt}}\t{{.Labels}}'` output. */
+    readonly containers: string | null;
+}
+/** The project's indexing state (macOS). `null` fields were not measured. */
+export interface IndexingSnapshot {
+    /** The project root the checks looked at. */
+    readonly projectRoot: string;
+    /** `tmutil isexcluded <root>/node_modules` output, `null` when there is no node_modules. */
+    readonly timeMachine: string | null;
+    /** `mdfind -onlyin <root>/node_modules -count …` output. */
+    readonly spotlightCount: string | null;
+}
+/** Everything {@link assessSystemHealth} needs, gathered by {@link collectSystemSnapshot}. */
+export interface SystemSnapshot {
+    readonly platform: NodeJS.Platform;
+    readonly sampledAtMs: number;
+    readonly totalMemBytes: number;
+    readonly cpuCount: number;
+    readonly loadAvg1: number;
+    /** The governor's resource sample, or `null` when it could not be read. */
+    readonly sample: ResourceSample | null;
+    /** Linux swap from `/proc/meminfo`; macOS carries it on `sample.darwinMemory`. */
+    readonly linuxSwap: {
+        readonly usedBytes: number;
+        readonly totalBytes: number;
+    } | null;
+    /** `ps -A -o pid=,ppid=,pgid=,rss=,pcpu=,etime=,args=` output, `null` when ps failed. */
+    readonly ps: string | null;
+    /** Process groups and pids `cleo run` holds (the admission ledger). */
+    readonly governedPgids: readonly number[];
+    readonly governedPids: readonly number[];
+    /** `null` when docker is not installed or its daemon did not answer. */
+    readonly docker: DockerSnapshot | null;
+    readonly indexing: IndexingSnapshot | null;
+    /** Linux only. */
+    readonly memoryGuard: MemoryGuardAudit | null;
+}
+/** One `ps` row. */
+export interface ProcessRow {
+    readonly pid: number;
+    readonly ppid: number;
+    readonly pgid: number;
+    readonly rssBytes: number;
+    readonly pcpu: number;
+    readonly elapsedSec: number;
+    readonly args: string;
+    /** `args` split on whitespace (ps does not quote; good enough for recognition). */
+    readonly argv: readonly string[];
+}
+/** `[[dd-]hh:]mm:ss` (both BSD and procps `etime`) to seconds. */
+export declare function parseEtime(etime: string): number;
+/** Parse `ps -A -o pid=,ppid=,pgid=,rss=,pcpu=,etime=,args=` output. */
+export declare function parsePs(output: string): ProcessRow[];
+/**
+ * The command words with the interpreter dropped and the script's extension
+ * stripped: `node …/typescript/bin/tsc -b` → `['tsc', '-b']`.
+ */
+export declare function commandWords(argv: readonly string[]): string[];
+/** An interactive agent session (claude, codex, opencode, kimi, …). */
+export declare function isHarnessSession(row: ProcessRow): boolean;
+/**
+ * The MCP server a process runs, or `null` when it is not one. Recognised by
+ * `mcp` in the command or script name (`playwright-mcp`, `mcpvault`,
+ * `agentmbx mcp`, `railway mcp`, `…/axiom-qa-mcp/dist/server.js`).
+ */
+export declare function mcpServerName(row: ProcessRow): string | null;
+/**
+ * The package a launcher runs (`npx -y @playwright/mcp@latest` → `@playwright/mcp`),
+ * `null` when a launcher names none, `undefined` when `words` is not a launcher.
+ * The scope is kept (`@a/mcp` and `@b/mcp` are different servers); the version is not.
+ */
+export declare function launchedPackage(words: readonly string[]): string | null | undefined;
+/** `2026-10-10 10:23:54 -0700 PDT` (docker CreatedAt) to epoch ms, `NaN` when unparseable. */
+export declare function parseDockerCreatedAt(value: string): number;
+/** Docker's human sizes (`52.3GB`, `16.38kB`, `0B`) to bytes. */
+export declare function parseDockerSize(value: string): number;
+/**
+ * Turn a snapshot into a ranked report. Pure: no I/O.
+ *
+ * @param s - the raw machine state from {@link collectSystemSnapshot}.
+ * @returns findings worst first, plus which checks ran.
+ *
+ * @example
+ * ```ts
+ * const report = assessSystemHealth(await collectSystemSnapshot({ projectRoot }));
+ * for (const f of report.findings) console.error(f.severity, f.title, f.remedy?.command);
+ * ```
+ *
+ * @task T13435
+ */
+export declare function assessSystemHealth(s: SystemSnapshot): SystemHealthReport;
+/** Linux swap from `/proc/meminfo`, `null` when unreadable. */
+export declare function parseLinuxSwap(meminfo: string): {
+    usedBytes: number;
+    totalBytes: number;
+} | null;
+/** Options for {@link collectSystemSnapshot}. */
+export interface CollectSystemSnapshotOptions {
+    /** The project to check Spotlight/Time Machine for; `null` skips those checks. */
+    readonly projectRoot: string | null;
+}
+/**
+ * Read the machine for {@link assessSystemHealth}. Read-only, never throws:
+ * a failed source leaves its field `null` and the report marks the check.
+ *
+ * @task T13435
+ */
+export declare function collectSystemSnapshot(opts: CollectSystemSnapshotOptions): Promise<SystemSnapshot>;
+//# sourceMappingURL=system-health.d.ts.map

package/dist/doctor/system-health.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-health.d.ts","sourceRoot":"","sources":["../../src/doctor/system-health.ts"],"names":[],"mappings":"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"}