create-walle 0.10.2 → 0.10.3

package/template/coding-task-manager/lib/host-stats.js

@@ -20,12 +20,25 @@
 // injected runner (`this.exec(...)`): bin/main-thread-lint.js's bare-launch rule reads a bare
 // `execFile(` as a new, unledgered main-thread spawn site, and this WP does not own the exemption
 // ledger. Behavior is identical — one async execFile with a fixed argv and a 3 s timeout.
+//
+// WP-0 M-6 (docs/hub-local-cpu-memory-burn-2026-10-31.html §1.1-§1.2, §7 M-6, Q-7): `cpuByCategory`
+// — cores used per process category over the interval since the previous sample — rides along in the
+// same row. It is MEASUREMENT ONLY: one extra async `ps` snapshot per tick, the same never-throws
+// contract as every other read here, and `null` (never a fabricated number) on the first sample or a
+// failed probe. The classification and the delta arithmetic are pure and live in
+// lib/host-cpu-categories.js; this file owns the launch, the previous-snapshot map and the field.
+// Gated by CTM_PERF_ATTRIBUTION (on by default in source; `=0` skips the launch AND the field).
 
 const os = require('node:os');
 const fs = require('node:fs');
 const childProcess = require('node:child_process');
 const { promisify } = require('node:util');
 
+const {
+  parsePsOutput, snapshotCpuMap, cpuByCategoryDelta, withUnattributed, PS_ARGS, PS_TIMEOUT_MS, PS_MAX_BUFFER,
+} = require('./host-cpu-categories');
+const { boolFlag } = require('./env-flags');
+
 const DEFAULT_RETENTION_MS = 24 * 60 * 60 * 1000;
 const DEFAULT_HISTORY_LIMIT = 1440;
 
@@ -37,6 +50,14 @@ const NVIDIA_SMI_ARGS = Object.freeze([
 ]);
 const NVIDIA_SMI_TIMEOUT_MS = 3000;
 
+// WP-1 (docs/lid-closed-pool-host-always-on-2026-10-25.html §6/§8): the two darwin probes behind the
+// Machines card's Power fact row. `kern.sleeptime` / `kern.waketime` are the kernel's own last sleep
+// and wake timevals (both `{ sec = 0 }` until the box has slept since boot); `pmset -g ps`'s first
+// line names the active power source. Same async, 3 s-bounded shape as the nvidia-smi probe.
+const POWER_PROBE_TIMEOUT_MS = 3000;
+const SYSCTL_SLEEP_ARGS = Object.freeze(['-n', 'kern.sleeptime', 'kern.waketime']);
+const PMSET_PS_ARGS = Object.freeze(['-g', 'ps']);
+
 const BYTES_PER_MIB = 1024 * 1024;
 const BYTES_PER_KIB = 1024;
 
@@ -94,6 +115,45 @@ function parseNvidiaSmi(stdout) {
   };
 }
 
+/**
+ * §6/§8 WP-1: one `sysctl -n kern.sleeptime kern.waketime` line — a C timeval plus a ctime suffix,
+ * e.g. `{ sec = 1792970037, usec = 158373 } Sun Oct 25 16:13:57 2026` → epoch ms. `sec = 0` is the
+ * kernel's "never slept since boot", which is NOT the epoch — it is `null`. Anything that does not
+ * match the timeval shape is also `null`, never a fabricated number.
+ */
+function parseSysctlTimeval(line) {
+  const match = /\{\s*sec\s*=\s*(\d+),\s*usec\s*=\s*(\d+)\s*\}/.exec(String(line == null ? '' : line));
+  if (!match) return null;
+  const sec = Number(match[1]);
+  const usec = Number(match[2]);
+  if (!Number.isFinite(sec) || !Number.isFinite(usec) || sec === 0) return null;
+  return sec * 1000 + Math.floor(usec / 1000);
+}
+
+/**
+ * §6/§8 WP-1: the two lines `sysctl -n kern.sleeptime kern.waketime` prints (sleeptime first,
+ * waketime second). A missing/blank line → that field `null`; a non-string → both `null`.
+ */
+function parseSleepWake(stdout) {
+  if (typeof stdout !== 'string') return { lastSleepAt: null, lastWakeAt: null };
+  const lines = stdout.split('\n');
+  return {
+    lastSleepAt: parseSysctlTimeval(lines[0]),
+    lastWakeAt: parseSysctlTimeval(lines[1]),
+  };
+}
+
+/**
+ * §6/§8 WP-1: the first line of `pmset -g ps` names the active source — `'AC Power'` → true,
+ * `'Battery Power'` → false, anything else (a missing read, an unexpected locale) → `null`.
+ */
+function parsePmsetPs(stdout) {
+  const first = String(stdout == null ? '' : stdout).split('\n')[0] || '';
+  if (first.indexOf('AC Power') !== -1) return true;
+  if (first.indexOf('Battery Power') !== -1) return false;
+  return null;
+}
+
 /** Cumulative cpu times, summed over cores — the delta between two calls is the util numerator. */
 function cpuTimes(cpuList) {
   let idle = 0;
@@ -117,18 +177,29 @@ function createHostStats({
   statfs = (p) => fs.promises.statfs(p),
   readFile = (p) => fs.promises.readFile(p, 'utf8'),
   execFile = promisify(childProcess.execFile),
+  // WP-0 M-6: its own injectable runner, deliberately NOT the shared `execFile` above — the ps
+  // snapshot is a different probe with its own argv/timeout/maxBuffer, and reusing `execFile` would
+  // make the existing nvidia-smi/power fixtures count an extra launch per tick.
+  runPs = promisify(childProcess.execFile),
   diskPath = os.homedir(),
   nvidiaSmiPath = '/usr/bin/nvidia-smi',
+  sysctlPath = '/usr/sbin/sysctl',
+  pmsetPath = '/usr/bin/pmset',
   countTasks = () => ({ running: 0, needsYou: 0, idle: 0, workers: 0 }),
   lastCreateAt = () => 0,
   retentionMs = DEFAULT_RETENTION_MS,
 } = {}) {
   // Method-position calls only (see the header): the lint's bare-launch rule scans for a bare
   // `execFile(`, not an injected runner reached through its owning bag.
-  const io = { statfs, readFile, execFile };
+  const io = { statfs, readFile, execFile, runPs };
 
   let lastCpu = null;
   let latestSample = null;
+  // WP-0 M-6: the previous ps snapshot (pid → cumulative cpuMs) and the sample instant it was taken
+  // at, so the next tick can report the delta over exactly that interval. Bounded by the live process
+  // count (~1,000 rows on the hub); a pid that exits is simply absent from the next snapshot.
+  let lastPsMap = null;
+  let lastPsAt = 0;
   // nvidia-smi presence is probed ONCE per process: the boot image of a box does not change under it.
   let nvidiaSmiAvailability = null;
 
@@ -225,6 +296,32 @@ function createHostStats({
     }
   }
 
+  // WP-1 §6/§8: darwin-only. The kernel's own sleep/wake timevals and pmset's active power source,
+  // read concurrently. Each read is guarded on its own (a common wrapper that never rejects), so a
+  // pmset that times out or a missing binary costs only its own field — the sysctl numbers survive,
+  // and vice versa. A rejected or synchronously-throwing probe is a NULL field, never a wrong number.
+  async function _power() {
+    if (platform !== 'darwin') return null; // expected: power facts are darwin-only by design
+    async function read(cmdPath, args) {
+      try {
+        const { stdout } = await io.execFile(cmdPath, [...args], { timeout: POWER_PROBE_TIMEOUT_MS });
+        return { ok: true, stdout };
+      } catch {
+        return { ok: false, stdout: '' }; // expected: the probe timed out, or the binary is absent
+      }
+    }
+    const [sleep, ps] = await Promise.all([
+      read(sysctlPath, SYSCTL_SLEEP_ARGS),
+      read(pmsetPath, PMSET_PS_ARGS),
+    ]);
+    const times = sleep.ok ? parseSleepWake(sleep.stdout) : { lastSleepAt: null, lastWakeAt: null };
+    return {
+      onAC: ps.ok ? parsePmsetPs(ps.stdout) : null,
+      lastSleepAt: times.lastSleepAt,
+      lastWakeAt: times.lastWakeAt,
+    };
+  }
+
   // D-10: the sampler's own process tree rss, in bytes.
   function _ctmRssBytes(snapshot) {
     const rssMB = snapshot && snapshot.processTree ? Number(snapshot.processTree.rssMB) : NaN;
@@ -256,16 +353,49 @@ function createHostStats({
     }
   }
 
+  /**
+   * WP-0 M-6 (§1.1-§1.2): one async `ps` snapshot per tick → cores per process category over the
+   * interval since the previous sample.
+   *
+   * Returns:
+   *   * `undefined` when CTM_PERF_ATTRIBUTION is off — the caller omits the FIELD entirely (§7: "no
+   *     cpuByCategory field"), and no process is launched;
+   *   * `null` on the FIRST sample (no previous snapshot, so no interval — never a fabricated 0) and
+   *     on any probe failure / non-positive interval;
+   *   * otherwise `{ [category]: cores }` from the pure classifier.
+   *
+   * A failed probe leaves lastPsMap/lastPsAt untouched, so the next successful sample spans the two
+   * intervals — the delta stays truthful rather than restarting at 0.
+   */
+  async function _cpuByCategory(at) {
+    if (!boolFlag('CTM_PERF_ATTRIBUTION', true)) return undefined; // expected: attribution disabled by flag
+    try {
+      const { stdout } = await io.runPs('ps', [...PS_ARGS], { timeout: PS_TIMEOUT_MS, maxBuffer: PS_MAX_BUFFER });
+      const rows = parsePsOutput(stdout);
+      const current = snapshotCpuMap(rows);
+      const previous = lastPsMap;
+      const previousAt = lastPsAt;
+      lastPsMap = current;
+      lastPsAt = at;
+      if (!previous || !(Number(previousAt) > 0) || !(at - previousAt > 0)) return null; // first sample
+      return cpuByCategoryDelta(previous, rows, at - previousAt, { selfPid: process.pid });
+    } catch {
+      return null; // expected: ps absent, timed out, or unusable output — the column degrades to null
+    }
+  }
+
   /**
    * One sample per resource tick. Never throws and never rejects: every sub-read is guarded and a
    * failed one contributes `null` (or the all-zero task bucket) to the sample.
    */
   async function record(resourceSnapshot) {
     const at = now();
-    const [memory, disk, gpu] = await Promise.all([
+    const [memory, disk, gpu, power, cpuByCategory] = await Promise.all([
       _memory(resourceSnapshot),
       _disk(),
       _gpu(),
+      _power(),
+      _cpuByCategory(at),
     ]);
     const load = _load();
     const sample = {
@@ -281,10 +411,14 @@ function createHostStats({
       diskFreeBytes: disk.diskFreeBytes,
       diskTotalBytes: disk.diskTotalBytes,
       gpu,
+      power,
       ctmRssBytes: _ctmRssBytes(resourceSnapshot),
       tasks: _tasks(),
       lastUsedAt: _lastUsedAt(),
     };
+    // WP-0 M-6: the field exists only while attribution is on, so a disabled box's rows are byte-for-
+    // byte the shape they had before this WP ("no cpuByCategory field").
+    if (cpuByCategory !== undefined) sample.cpuByCategory = withUnattributed(cpuByCategory, sample.cpuPct, sample.cores);
     // Memory FIRST, then the write: a reader that pairs latest() with history() (lib/api/host-stats.js
     // does, and asserts latest.at >= samples[last].at) must never see a stored row newer than the
     // in-memory sample beside it. record()'s row is committed before this await resolves, so setting
@@ -325,4 +459,17 @@ function createHostStats({
   return { record, latest, history };
 }
 
-module.exports = { createHostStats, parseMeminfo, parseNvidiaSmi, cpuTimes, NVIDIA_SMI_ARGS, DEFAULT_RETENTION_MS };
+module.exports = {
+  createHostStats,
+  parseMeminfo,
+  parseNvidiaSmi,
+  parseSysctlTimeval,
+  parseSleepWake,
+  parsePmsetPs,
+  cpuTimes,
+  NVIDIA_SMI_ARGS,
+  POWER_PROBE_TIMEOUT_MS,
+  SYSCTL_SLEEP_ARGS,
+  PMSET_PS_ARGS,
+  DEFAULT_RETENTION_MS,
+};