@superblocksteam/sdk 2.0.153 → 2.0.154-next.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superblocksteam/sdk",
-  "version": "2.0.153",
+  "version": "2.0.154-next.1",
   "description": "Superblocks JS SDK",
   "homepage": "https://www.superblocks.com",
   "license": "Superblocks Community Software License",
@@ -57,11 +57,11 @@
     "vite-tsconfig-paths": "^6.0.4",
     "winston": "^3.17.0",
     "yaml": "^2.7.1",
-    "@superblocksteam/library-shared": "2.0.153",
-    "@superblocksteam/shared": "0.9605.3",
-    "@superblocksteam/telemetry": "2.0.153",
-    "@superblocksteam/util": "2.0.153",
-    "@superblocksteam/vite-plugin-file-sync": "2.0.153"
+    "@superblocksteam/shared": "0.9607.3",
+    "@superblocksteam/telemetry": "2.0.154-next.1",
+    "@superblocksteam/library-shared": "2.0.154-next.1",
+    "@superblocksteam/util": "2.0.154-next.1",
+    "@superblocksteam/vite-plugin-file-sync": "2.0.154-next.1"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.2",

package/src/cli-replacement/dev-s3-restore.test.mts

@@ -153,6 +153,7 @@ vi.mock("@superblocksteam/vite-plugin-file-sync/npm-registry", async () => {
   return {
     NpmInstallBlocked,
     shouldIgnoreInstallScripts: vi.fn(() => false),
+    maybeWriteNpmrcForDir: vi.fn(async () => undefined),
     // Used by the dependency-install-classifier reachable from installPackages'
     // catch path (APPS-4450). Previously the only test that hit this codepath
     // (`logs a structured error when the background install fails`) didn't

package/src/cli-replacement/dev-startup-git-before-dbfs-order.test.mts

@@ -121,7 +121,7 @@ vi.mock("@superblocksteam/vite-plugin-file-sync/ai-service", () => ({
     removeIntegrationCache = vi.fn(async () => undefined);
     remediateDeclaredDependencies = vi.fn(async () => undefined);
     chatSessionStore = { invalidateCache: vi.fn() };
-    getNpmRegistryClient = vi.fn(() => undefined);
+    getNpmRegistryClient = mockGetNpmRegistryClient;
   },
   AiServiceFeatureFlags: class {
     static create = vi.fn(() => ({}));
@@ -136,63 +136,84 @@ vi.mock("@superblocksteam/vite-plugin-file-sync/ai-service", () => ({
 
 vi.mock("@superblocksteam/vite-plugin-file-sync/npm-registry", () => ({
   shouldIgnoreInstallScripts: vi.fn(() => false),
+  maybeWriteNpmrcForDir: vi.fn(async () => {
+    // Delay before the log push so this test fails if syncHomeNpmrc is
+    // fire-and-forget (initiation order alone would still look correct).
+    await new Promise((resolve) => setTimeout(resolve, 5));
+    startupOpLog.push("project-npmrc:maybeWriteNpmrcForDir");
+  }),
 }));
 
-const { startupOpLog, buildMockGitService } = vi.hoisted(() => {
-  const startupOpLog: string[] = [];
-  function buildMockGitService(cwd: string) {
-    return {
-      workDir: cwd,
-      configure: vi.fn(async () => {
-        startupOpLog.push("git:configure");
-      }),
-      init: vi.fn(async () => {
-        startupOpLog.push("git:init");
-      }),
-      addRemote: vi.fn(async () => {
-        startupOpLog.push("git:addRemote");
+const { startupOpLog, buildMockGitService, mockGetNpmRegistryClient } =
+  vi.hoisted(() => {
+    const startupOpLog: string[] = [];
+    const mockGetNpmRegistryClient = vi.fn(
+      ():
+        | {
+            getConfig: ReturnType<typeof vi.fn>;
+            organizationId: string;
+          }
+        | undefined => ({
+        organizationId: "org-1",
+        getConfig: vi.fn(async () => ({
+          source: "not-configured",
+          config: { configured: false },
+        })),
       }),
-      fetch: vi.fn(async () => {
-        startupOpLog.push("git:fetch");
-      }),
-      raw: vi.fn(async (args: string | string[]) => {
-        const argv = Array.isArray(args) ? args : [args];
-        startupOpLog.push(`git:raw:${argv.join(" ")}`);
-        if (argv[0] === "ls-remote" && argv.includes("__live__")) {
-          return "deadbeefdeadbeefdeadbeefdeadbeefdeadbeef\trefs/heads/__live__\n";
-        }
-        if (argv[0] === "branch" && argv.includes("--show-current")) {
-          return "__live__\n";
-        }
-        if (argv[0] === "commit") {
+    );
+    function buildMockGitService(cwd: string) {
+      return {
+        workDir: cwd,
+        configure: vi.fn(async () => {
+          startupOpLog.push("git:configure");
+        }),
+        init: vi.fn(async () => {
+          startupOpLog.push("git:init");
+        }),
+        addRemote: vi.fn(async () => {
+          startupOpLog.push("git:addRemote");
+        }),
+        fetch: vi.fn(async () => {
+          startupOpLog.push("git:fetch");
+        }),
+        raw: vi.fn(async (args: string | string[]) => {
+          const argv = Array.isArray(args) ? args : [args];
+          startupOpLog.push(`git:raw:${argv.join(" ")}`);
+          if (argv[0] === "ls-remote" && argv.includes("__live__")) {
+            return "deadbeefdeadbeefdeadbeefdeadbeefdeadbeef\trefs/heads/__live__\n";
+          }
+          if (argv[0] === "branch" && argv.includes("--show-current")) {
+            return "__live__\n";
+          }
+          if (argv[0] === "commit") {
+            return "";
+          }
           return "";
-        }
-        return "";
-      }),
-      push: vi.fn(async () => {
-        startupOpLog.push("git:push");
-      }),
-      getDefaultBranch: vi.fn(async () => "main"),
-      getRemotes: vi.fn(async () => [
-        { name: "origin", refs: { fetch: "https://example.test/repo.git" } },
-      ]),
-      remote: vi.fn(async () => {
-        startupOpLog.push("git:remote");
-      }),
-      revparse: vi.fn(async (ref: string) => {
-        startupOpLog.push(`git:revparse:${ref}`);
-        return "abc123\n";
-      }),
-      checkout: vi.fn(async () => {
-        startupOpLog.push("git:checkout");
-      }),
-      checkoutOrCreate: vi.fn(async () => {
-        startupOpLog.push("git:checkoutOrCreate");
-      }),
-    };
-  }
-  return { startupOpLog, buildMockGitService };
-});
+        }),
+        push: vi.fn(async () => {
+          startupOpLog.push("git:push");
+        }),
+        getDefaultBranch: vi.fn(async () => "main"),
+        getRemotes: vi.fn(async () => [
+          { name: "origin", refs: { fetch: "https://example.test/repo.git" } },
+        ]),
+        remote: vi.fn(async () => {
+          startupOpLog.push("git:remote");
+        }),
+        revparse: vi.fn(async (ref: string) => {
+          startupOpLog.push(`git:revparse:${ref}`);
+          return "abc123\n";
+        }),
+        checkout: vi.fn(async () => {
+          startupOpLog.push("git:checkout");
+        }),
+        checkoutOrCreate: vi.fn(async () => {
+          startupOpLog.push("git:checkoutOrCreate");
+        }),
+      };
+    }
+    return { startupOpLog, buildMockGitService, mockGetNpmRegistryClient };
+  });
 
 vi.mock("@superblocksteam/vite-plugin-file-sync/git-service", () => ({
   createGitService: vi.fn((cwd: string) => {
@@ -284,10 +305,16 @@ vi.mock("./automatic-upgrades.js", () => ({
 // `getNpmRegistryClient()` stub so the call site doesn't `TypeError`
 // and silently swallow this mock.
 vi.mock("./home-npmrc.mjs", () => ({
-  syncHomeNpmrc: vi.fn(async () => ({
-    outcome: "skipped-not-configured",
-    path: "/tmp/.superblocks/npmrc",
-  })),
+  syncHomeNpmrc: vi.fn(async () => {
+    // Longer delay than maybeWriteNpmrcForDir: if both run without await,
+    // project pushes first and the order assertion fails.
+    await new Promise((resolve) => setTimeout(resolve, 30));
+    startupOpLog.push("home-npmrc:syncHomeNpmrc");
+    return {
+      outcome: "skipped-not-configured",
+      path: "/tmp/.superblocks/npmrc",
+    };
+  }),
   superblocksNpmrcPath: vi.fn(() => "/tmp/.superblocks/npmrc"),
   superblocksLogsPath: vi.fn((appDir: string) => `${appDir}/.superblocks/logs`),
 }));
@@ -383,6 +410,7 @@ function setupExecMock() {
       _opts: unknown,
       cb?: (err: null, result: { stdout: string }) => void,
     ) => {
+      startupOpLog.push("installPackages:exec");
       if (typeof _opts === "function") {
         (_opts as (err: null, result: { stdout: string }) => void)(null, {
           stdout: "installed",
@@ -399,6 +427,13 @@ describe("dev startup: git reconciliation before DBFS download", () => {
 
   beforeEach(async () => {
     vi.clearAllMocks();
+    mockGetNpmRegistryClient.mockImplementation(() => ({
+      organizationId: "org-1",
+      getConfig: vi.fn(async () => ({
+        source: "not-configured",
+        config: { configured: false },
+      })),
+    }));
     startupOpLog.length = 0;
     setupExecMock();
     mockCheckVersions.mockResolvedValue({
@@ -444,4 +479,40 @@ describe("dev startup: git reconciliation before DBFS download", () => {
       "[dev-startup] Post-download hash matches server",
     );
   });
+
+  it("reconciles project .npmrc after home sync and before boot install", async () => {
+    const { maybeWriteNpmrcForDir } =
+      await import("@superblocksteam/vite-plugin-file-sync/npm-registry");
+    const { syncHomeNpmrc } = await import("./home-npmrc.mjs");
+    const { dev } = await import("./dev.mjs");
+
+    await dev(buildDevOptions(testCwd) as any);
+
+    const homeIdx = startupOpLog.indexOf("home-npmrc:syncHomeNpmrc");
+    const projectIdx = startupOpLog.indexOf(
+      "project-npmrc:maybeWriteNpmrcForDir",
+    );
+    const installIdx = startupOpLog.indexOf("installPackages:exec");
+
+    expect(syncHomeNpmrc).toHaveBeenCalled();
+    expect(maybeWriteNpmrcForDir).toHaveBeenCalled();
+    expect(homeIdx).toBeGreaterThanOrEqual(0);
+    expect(projectIdx).toBeGreaterThanOrEqual(0);
+    expect(homeIdx).toBeLessThan(projectIdx);
+    if (installIdx >= 0) {
+      expect(projectIdx).toBeLessThan(installIdx);
+    }
+  });
+
+  it("skips project .npmrc reconcile when the npm registry client is absent", async () => {
+    mockGetNpmRegistryClient.mockReturnValue(undefined);
+    const { maybeWriteNpmrcForDir } =
+      await import("@superblocksteam/vite-plugin-file-sync/npm-registry");
+    const { dev } = await import("./dev.mjs");
+
+    await dev(buildDevOptions(testCwd) as any);
+
+    expect(maybeWriteNpmrcForDir).not.toHaveBeenCalled();
+    expect(startupOpLog).not.toContain("project-npmrc:maybeWriteNpmrcForDir");
+  });
 });

package/src/cli-replacement/dev.mts

@@ -1,6 +1,7 @@
 import * as child_process from "node:child_process";
 import * as nodeFs from "node:fs/promises";
 import type { Server as HttpServer } from "node:http";
+import os from "node:os";
 import path from "node:path";
 import * as readline from "node:readline";
 import { promisify } from "node:util";
@@ -24,6 +25,7 @@ import {
   isGitHubRemoteUrl,
   SUPERBLOCKS_LIVE_GIT_BRANCH,
 } from "@superblocksteam/shared";
+import { npmRegistryEmitter } from "@superblocksteam/telemetry";
 import { maskUnixSignals } from "@superblocksteam/util";
 import {
   AiService,
@@ -45,6 +47,7 @@ import {
   type NpmRegistryFetchResult,
   type ParseContext,
   NpmInstallBlocked,
+  maybeWriteNpmrcForDir,
   shouldIgnoreInstallScripts,
 } from "@superblocksteam/vite-plugin-file-sync/npm-registry";
 import { OperationQueue } from "@superblocksteam/vite-plugin-file-sync/operation-queue";
@@ -97,6 +100,7 @@ import {
   syncHomeNpmrc,
 } from "./home-npmrc.mjs";
 import { normalizeWorkspaceProtocolForNpm } from "./normalize-workspace-protocol.js";
+import { readReapedChildCpuSeconds } from "./npm-install-cpu.mjs";
 import { parseNpmInstallSummary } from "./npm-install-summary.mjs";
 import { consumeNpmInstallTimingAttributes } from "./npm-install-timing.mjs";
 import {
@@ -642,6 +646,11 @@ export async function installPackages(
         env: buildInstallEnv(superblocksNpmrcPath(), logsDir),
       });
     installStart = Date.now();
+    // Reaped-child cpu total before the install, so the delta across the
+    // awaited spawn below covers the cpu the install burned. Compared against
+    // the wall-clock duration it separates a compute-bound install from one
+    // that spent its time waiting on the network or the disk.
+    const childCpuSecondsBefore = await readReapedChildCpuSeconds();
 
     // Cheap `df` snapshot before the install (statfs only — no directory walk
     // on the happy path). On a 3Gi live-edit PVC this is the baseline that
@@ -660,6 +669,7 @@ export async function installPackages(
 
     const { stdout } = await runInstall();
     const installDurationMs = Date.now() - installStart;
+    const childCpuSecondsAfter = await readReapedChildCpuSeconds();
     // npm's `--timing` breakdown lives in a file, so it has to be read back
     // once the install is done. Only npm writes one; reading under pnpm would
     // report a leftover npm file as this install's timings. The `catch` keeps
@@ -682,11 +692,27 @@ export async function installPackages(
           "Package installation completed successfully",
           attributes,
         );
+      // Cpu the install burned, to be read against the wall-clock duration
+      // beside it. Omitted rather than zeroed where procfs is unavailable, so a
+      // reading we could not take never looks like an install that used no cpu.
+      // The core count is what makes the ratio interpretable: 19 cpu-seconds
+      // over 19 wall-seconds is saturated on one core and nearly idle on eight.
+      const cpuAttributes: Record<string, number> =
+        childCpuSecondsBefore !== null && childCpuSecondsAfter !== null
+          ? {
+              "superblocks.npm.install.cpu_count": os.availableParallelism(),
+              "superblocks.npm.install.cpu_seconds": Math.max(
+                0,
+                childCpuSecondsAfter - childCpuSecondsBefore,
+              ),
+            }
+          : {};
       // Reuse the existing npm-install namespace and its duration unit. The
       // package counts are log-only sizing data from this separate install path.
       const commonAttributes = {
         "superblocks.npm.install.disk_recovered": false,
         "superblocks.npm.install.duration_seconds": installDurationMs / 1000,
+        ...cpuAttributes,
         ...timingAttributes,
       };
       if (summary) {
@@ -1996,6 +2022,22 @@ export async function dev(options: {
               }
             }
 
+            // Reconcile the project-dir `.npmrc` on the live-edit PVC before
+            // the boot install. Home sync alone is not enough: npm prefers
+            // the project file, which can hold a stale JWT or a
+            // deleted-registry proxy URL across pod recycles.
+            if (npmRegistryClient) {
+              try {
+                await maybeWriteNpmrcForDir(cwd, npmRegistryClient);
+              } catch (error) {
+                logger.warn(
+                  "[project-npmrc] boot reconcile failed unexpectedly; project .npmrc left untouched",
+                  getErrorMeta(error),
+                );
+                npmRegistryEmitter.recordSyncProjectNpmrc("error");
+              }
+            }
+
             let hasCliUpdated = false;
             let upgradePromises: Promise<void>[] = [];
             const forceUpgrade =

package/src/cli-replacement/install-packages.npm-registry.test.mts

@@ -76,6 +76,16 @@ vi.mock("./npm-install-timing.mjs", () => ({
     consumeTimingMock(logsDir),
 }));
 
+// Install cpu time is read from procfs, which does not exist on macOS, so a
+// real read would make the emitted attributes differ between a developer
+// machine and CI. The reader has its own coverage in `npm-install-cpu.test.mts`;
+// here we only care that a reading reaches the success log line, and that no
+// reading leaves the attributes off it entirely.
+const readChildCpuMock = vi.fn<() => Promise<number | null>>(async () => null);
+vi.mock("./npm-install-cpu.mjs", () => ({
+  readReapedChildCpuSeconds: () => readChildCpuMock(),
+}));
+
 const mockLogger = {
   info: vi.fn(),
   infoStructured: vi.fn(),
@@ -392,6 +402,39 @@ describe("installPackages success logging", () => {
     expect(mockLogger.info).toHaveBeenCalledWith("ok");
   });
 
+  it("emits the cpu time the install burned alongside its wall-clock duration", async () => {
+    // Two reads bracket the install, so the emitted figure is the difference.
+    readChildCpuMock.mockResolvedValueOnce(12).mockResolvedValueOnce(30.5);
+    const { installPackages } = await import("./dev.mjs");
+
+    await installPackages("/tmp/app", mockLogger as never);
+
+    expect(mockLogger.infoStructured).toHaveBeenCalledWith(
+      "Package installation completed successfully",
+      expect.objectContaining({
+        "superblocks.npm.install.cpu_count": expect.any(Number),
+        "superblocks.npm.install.cpu_seconds": 18.5,
+        "superblocks.npm.install.duration_seconds": expect.any(Number),
+      }),
+    );
+  });
+
+  it("omits cpu attributes when only one of the two reads succeeds", async () => {
+    // Half a measurement is not one: a difference taken against a missing
+    // baseline would invent a number rather than report one.
+    readChildCpuMock.mockResolvedValueOnce(12).mockResolvedValueOnce(null);
+    const { installPackages } = await import("./dev.mjs");
+
+    await installPackages("/tmp/app", mockLogger as never);
+
+    expect(mockLogger.infoStructured).toHaveBeenCalledWith(
+      "Package installation completed successfully",
+      expect.not.objectContaining({
+        "superblocks.npm.install.cpu_seconds": expect.anything(),
+      }),
+    );
+  });
+
   it("marks parsed npm summaries and emits their counts", async () => {
     const stdout = JSON.stringify({
       added: 8,

package/src/cli-replacement/npm-install-cpu.mts

@@ -0,0 +1,86 @@
+/**
+ * npm's `--timing` breakdown says which phase an install spent its time in,
+ * but not whether the pod was working or waiting. Both readings are consistent
+ * with the same 19 second `reify:unpack`: npm streaming tarballs over the
+ * network, or npm burning cpu it cannot get enough of. Live edit pods request
+ * 200m of cpu and set no ceiling, so under contention they get a small
+ * proportional share of the machine, and the usual throttling metric never
+ * fires because there is no quota to throttle against.
+ *
+ * Comparing cpu time against wall time separates the two. An install that
+ * burns roughly its wall time in cpu is compute-bound and the share it gets
+ * matters; one that burns a fraction of it is waiting on the network or the
+ * disk, and cpu is a dead end.
+ *
+ * Linux tracks this per process in `/proc/self/stat`: `cutime` and `cstime`
+ * are the user and system time of children this process has already waited
+ * for. Bracketing an awaited spawn with two reads gives that spawn's cpu time
+ * without instrumenting npm itself.
+ *
+ * The figure is a ceiling rather than an exact attribution: any other child
+ * the dev-server happens to reap inside the same window lands in the same
+ * counters. Nothing else it spawns is remotely as expensive as an install, so
+ * the reading is dominated by npm, but a few hundred milliseconds of git in
+ * there is expected and does not change what the number is used for.
+ */
+import nodeFs from "node:fs/promises";
+
+/**
+ * `cutime`/`cstime` are in clock ticks. The kernel reports procfs times in
+ * USER_HZ, which is 100 on Linux regardless of the kernel's internal tick
+ * rate, and there is no way to read `sysconf(_SC_CLK_TCK)` from Node.
+ */
+const USER_HZ = 100;
+
+const PROC_SELF_STAT = "/proc/self/stat";
+
+/**
+ * Field offsets counted from `state`, which is the first field after the
+ * executable name. `/proc/[pid]/stat` numbers `state` as field 3, so a
+ * one-indexed field N from the man page sits at N - 3 here.
+ */
+const CUTIME_OFFSET = 13;
+const CSTIME_OFFSET = 14;
+
+/**
+ * Sum the cpu time of children this process has already reaped, in seconds.
+ *
+ * Returns null when the line cannot be read as procfs output, so a platform
+ * without procfs omits the measurement rather than reporting zero cpu.
+ */
+export function parseReapedChildCpuSeconds(stat: string): number | null {
+  // The executable name is unescaped and may itself contain spaces and
+  // parentheses, so the positional fields start after its LAST closing paren.
+  const commEnd = stat.lastIndexOf(")");
+  if (commEnd === -1) {
+    return null;
+  }
+
+  const fields = stat
+    .slice(commEnd + 1)
+    .trim()
+    .split(/\s+/);
+  const cutime = Number(fields[CUTIME_OFFSET]);
+  const cstime = Number(fields[CSTIME_OFFSET]);
+  if (!Number.isFinite(cutime) || !Number.isFinite(cstime)) {
+    return null;
+  }
+
+  return (cutime + cstime) / USER_HZ;
+}
+
+/**
+ * Read the reaped-child cpu total for this process.
+ *
+ * Never throws: this brackets a real install, and no telemetry read may turn a
+ * completed install into a failure.
+ */
+export async function readReapedChildCpuSeconds(
+  statPath: string = PROC_SELF_STAT,
+): Promise<number | null> {
+  try {
+    return parseReapedChildCpuSeconds(await nodeFs.readFile(statPath, "utf8"));
+  } catch {
+    return null;
+  }
+}

package/src/cli-replacement/npm-install-cpu.test.mts

@@ -0,0 +1,131 @@
+import nodeFs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import {
+  parseReapedChildCpuSeconds,
+  readReapedChildCpuSeconds,
+} from "./npm-install-cpu.mjs";
+
+/**
+ * Build a `/proc/self/stat` line. Real ones are a single space-separated line
+ * whose second field is the executable name in parentheses; everything after
+ * it is positional. Only utime/stime (fields 14 and 15) and cutime/cstime
+ * (fields 16 and 17) matter here, so the rest is filler.
+ */
+function statLine({
+  comm = "node",
+  utime = 0,
+  stime = 0,
+  cutime = 0,
+  cstime = 0,
+  trailing = 20,
+}: {
+  comm?: string;
+  utime?: number;
+  stime?: number;
+  cutime?: number;
+  cstime?: number;
+  trailing?: number;
+}): string {
+  const beforeTimes = [
+    "R", // 3 state
+    "1", // 4 ppid
+    "1", // 5 pgrp
+    "1", // 6 session
+    "0", // 7 tty_nr
+    "-1", // 8 tpgid
+    "4194304", // 9 flags
+    "0", // 10 minflt
+    "0", // 11 cminflt
+    "0", // 12 majflt
+    "0", // 13 cmajflt
+  ];
+  const fields = [
+    ...beforeTimes,
+    String(utime),
+    String(stime),
+    String(cutime),
+    String(cstime),
+    ...Array.from({ length: trailing }, () => "0"),
+  ];
+  return `42 (${comm}) ${fields.join(" ")}\n`;
+}
+
+let tmpDir: string;
+
+beforeEach(async () => {
+  tmpDir = await nodeFs.mkdtemp(path.join(os.tmpdir(), "npm-install-cpu-"));
+});
+
+afterEach(async () => {
+  await nodeFs.rm(tmpDir, { force: true, recursive: true });
+});
+
+describe("parseReapedChildCpuSeconds", () => {
+  it("sums the child user and system columns and converts clock ticks to seconds", () => {
+    // 250 + 150 ticks at 100 ticks per second.
+    expect(
+      parseReapedChildCpuSeconds(statLine({ cutime: 250, cstime: 150 })),
+    ).toBe(4);
+  });
+
+  it("ignores the process's own cpu columns", () => {
+    // utime/stime are this process's; only cutime/cstime cover reaped children.
+    expect(
+      parseReapedChildCpuSeconds(
+        statLine({ utime: 9999, stime: 9999, cutime: 100, cstime: 0 }),
+      ),
+    ).toBe(1);
+  });
+
+  it("reads a zero as a real measurement rather than as missing", () => {
+    // An install that spawned nothing genuinely burned no child cpu, which is
+    // exactly the case worth telling apart from a slow one.
+    expect(parseReapedChildCpuSeconds(statLine({}))).toBe(0);
+  });
+
+  it("handles an executable name containing spaces and parentheses", () => {
+    // The comm field is not escaped, so splitting on spaces from the left
+    // shifts every positional field after it.
+    expect(
+      parseReapedChildCpuSeconds(
+        statLine({ comm: "my (weird) proc", cutime: 100, cstime: 100 }),
+      ),
+    ).toBe(2);
+  });
+
+  it("returns null when the line has no closing parenthesis", () => {
+    expect(parseReapedChildCpuSeconds("42 node R 1 1 1")).toBeNull();
+  });
+
+  it("returns null when the line stops before the child cpu columns", () => {
+    expect(parseReapedChildCpuSeconds("42 (node) R 1 1 1")).toBeNull();
+  });
+
+  it("returns null when a child cpu column is not a number", () => {
+    expect(
+      parseReapedChildCpuSeconds(
+        statLine({ cutime: 100 }).replace(" 100 0", " x 0"),
+      ),
+    ).toBeNull();
+  });
+});
+
+describe("readReapedChildCpuSeconds", () => {
+  it("reads the measurement from the given path", async () => {
+    const file = path.join(tmpDir, "stat");
+    await nodeFs.writeFile(file, statLine({ cutime: 500, cstime: 500 }));
+    await expect(readReapedChildCpuSeconds(file)).resolves.toBe(10);
+  });
+
+  it("returns null when the file does not exist", async () => {
+    // macOS and any other non-procfs platform: the attribute is omitted
+    // rather than reported as zero cpu.
+    await expect(
+      readReapedChildCpuSeconds(path.join(tmpDir, "missing")),
+    ).resolves.toBeNull();
+  });
+});