reploid 0.0.0-stage → 0.1.0

package/server/native-owner/controls.js

@@ -0,0 +1,162 @@
+/** Owner admission gate for the native participant. It decides whether new stage
+ * work, contribution preparation and piece supply may start; it never cancels,
+ * aborts or closes work that was already admitted. With no owner policy the
+ * participant never creates it and behaves exactly as before. */
+import failureMessages from '../../packages/reploid/src/transport/partition-errors.json' with { type: 'json' };
+import { readNativeOwnerPolicy, validateNativeOwnerPolicy, nativeOwnerPolicyDigest, decideNativeOwnerAdmission, custodySupplyTransfers } from './policy.js';
+import { detectNativeOwnerSupport, createNativeOwnerMonitor, runNativeTool } from './monitor.js';
+import { createByteRateLimiter, createTransferMeter, paceCustodyChannel } from './rate.js';
+
+export const NO_OWNER_POLICY = Object.freeze({ status: 'no owner policy' });
+
+/** Compact admission state for each partition-state status line. */
+export function nativeOwnerStatus(owner) {
+  if (!owner) return NO_OWNER_POLICY;
+  const { action, message } = owner.decide();
+  return { status: 'owner policy', digest: owner.digest, action, message };
+}
+
+/** `file` (absolute owner policy path) or an already parsed `policy`. `custody` is the
+ * application's custody policy (self/config/chat-files.json). */
+export async function openNativeOwnerControls({ file, policy: parsed, custody, platform = process.platform, sysfsRoot = '/sys',
+  run = runNativeTool, now = Date.now, readGpuBuffers = null, onChange = () => {} }) {
+  const loaded = file !== undefined ? await readNativeOwnerPolicy(file, { custody })
+    : (policy => ({ policy, digest: nativeOwnerPolicyDigest(policy) }))(validateNativeOwnerPolicy(parsed, { custody }));
+  const { policy, digest } = loaded;
+  const support = await detectNativeOwnerSupport({ policy, platform, sysfsRoot, run });
+  const monitor = createNativeOwnerMonitor({ policy, support, platform, run, now, readGpuBuffers });
+  const limiter = key => policy.bandwidth?.[key] === undefined ? null
+    : createByteRateLimiter({ bytesPerSecond: policy.bandwidth[key], capacityBytes: custody.channel.maxChunkBytes, now });
+  const upload = limiter('uploadBytesPerSecond'), download = limiter('downloadBytesPerSecond'), meter = createTransferMeter();
+  // Paced supply admits only as many transfers as the rate can finish within custody deadlines.
+  const supplyTransfers = upload ? custodySupplyTransfers(custody, upload.bytesPerSecond) : custody.maxTransfers;
+  const startedAt = now(), cpuStart = process.cpuUsage(), waiters = new Map();
+  const counts = { stageAdmitted: 0, stageRefused: 0, supplyAdmitted: 0, supplyRefused: 0 };
+  const actionMs = { admit: 0, reduce: 0, defer: 0, reject: 0 };
+  let readings = null, last = null, closed = false, sampling = null, peakResidentBytes = 0, maxCelsius = null;
+  let previousTransfer = { at: startedAt, ...meter.getState() }, measuredRates = { suppliedBytesPerSecond: null, receivedBytesPerSecond: null };
+  const decide = () => decideNativeOwnerAdmission({ policy, support, readings, at: now() });
+  const stageAllowance = decision => decision.action === 'admit' ? Infinity
+    : decision.action === 'reduce' ? decision.limits.maxConcurrentAttempts : 0;
+  const supplyAllowance = decision => decision.action === 'admit' ? supplyTransfers
+    : decision.action === 'reduce' ? Math.min(supplyTransfers, decision.limits.maxSupplyTransfers) : 0;
+  const decisionRecord = decision => ({ action: decision.action, message: decision.message, at: new Date(decision.at).toISOString(),
+    reasons: decision.reasons.map(reason => reason.message), ...(decision.limits ? { limits: { ...decision.limits } } : {}) });
+
+  function summary() {
+    const decision = decide(), transfer = meter.getState(), cpu = process.cpuUsage(cpuStart);
+    return { status: 'owner policy', digest, decision: decisionRecord(decision),
+      waiting: [...new Set(waiters.values())],
+      readings: readings && { at: new Date(readings.at).toISOString(), processResidentBytes: readings.processResidentBytes,
+        gpuBuffers: readings.gpuBuffers, temperatureCelsius: readings.temperature?.maxCelsius ?? null,
+        gpuPowerWatts: readings.gpuPower?.watts ?? null, externalPower: readings.externalPower,
+        inputIdleSeconds: readings.inputIdleSeconds, foregroundSignal: readings.foregroundSignal },
+      transfer: { upload: { limitBytesPerSecond: upload?.bytesPerSecond ?? null, maxSupplyTransfers: supplyAllowance(decision),
+        suppliedBytes: transfer.suppliedBytes, measuredBytesPerSecond: measuredRates.suppliedBytesPerSecond, queuedBytes: upload?.getState().queuedBytes ?? 0 },
+      download: { limitBytesPerSecond: download?.bytesPerSecond ?? null, receivedBytes: transfer.receivedBytes,
+        measuredBytesPerSecond: measuredRates.receivedBytesPerSecond, queuedBytes: download?.getState().queuedBytes ?? 0 } },
+      measurements: { since: new Date(startedAt).toISOString(), elapsedMs: now() - startedAt,
+        cpuUserMicros: cpu.user, cpuSystemMicros: cpu.system, cpuScope: 'whole native process',
+        peakProcessResidentBytes: peakResidentBytes, maxTemperatureCelsius: maxCelsius, gpuEnergy: monitor.getEnergy(),
+        actionMs: { ...actionMs }, ...counts } };
+  }
+  function refresh() {
+    const decision = decide();
+    if (last) actionMs[last.action] += Math.max(0, decision.at - last.at);
+    const changed = !last || last.message !== decision.message;
+    last = decision;
+    for (const wake of [...waiters.keys()]) wake(decision);
+    if (changed && !closed) onChange(summary());
+    return decision;
+  }
+  function sample() {
+    return sampling ||= (async () => {
+      try {
+        const next = await monitor.sample();
+        readings = next;
+        peakResidentBytes = Math.max(peakResidentBytes, next.processResidentBytes);
+        const celsius = next.temperature?.maxCelsius;
+        if (typeof celsius === 'number') maxCelsius = maxCelsius === null ? celsius : Math.max(maxCelsius, celsius);
+        const transfer = meter.getState(), elapsed = (next.at - previousTransfer.at) / 1000;
+        if (elapsed > 0) measuredRates = { suppliedBytesPerSecond: (transfer.suppliedBytes - previousTransfer.suppliedBytes) / elapsed,
+          receivedBytesPerSecond: (transfer.receivedBytes - previousTransfer.receivedBytes) / elapsed };
+        previousTransfer = { at: next.at, ...transfer };
+      } catch { /* Previous readings age out and defer admission; they are never assumed safe. */ }
+      return refresh();
+    })().finally(() => { sampling = null; });
+  }
+  await sample();
+  const timer = setInterval(() => { if (!closed) sample(); }, policy.sampleIntervalMs);
+  timer.unref?.();
+
+  function admitStage(active) {
+    const allowed = active < stageAllowance(decide());
+    counts[allowed ? 'stageAdmitted' : 'stageRefused']++;
+    return allowed;
+  }
+  return Object.freeze({
+    policy, digest, support,
+    decide, sample, summary,
+    declaration: () => ({ status: 'owner policy', digest, policy, platform: support.platform, controls: structuredClone(support.controls) }),
+    /** Resolves when new work may start; rejects at once if the policy can never be enforced here. */
+    waitForAdmission({ kind, signal } = {}) {
+      return new Promise((resolve, reject) => {
+        const done = error => {
+          if (!waiters.delete(check)) return;
+          signal?.removeEventListener('abort', abort);
+          if (error) reject(error); else resolve(decide());
+        };
+        const check = decision => {
+          if (closed) done(new Error('Owner controls closed'));
+          else if (decision.action === 'reject') done(new Error('Owner policy ' + decision.message));
+          else if (decision.action !== 'defer') done(null);
+        };
+        const abort = () => done(signal.reason);
+        waiters.set(check, kind || 'work');
+        if (signal?.aborted) { abort(); return; }
+        signal?.addEventListener('abort', abort, { once: true });
+        check(decide());
+      });
+    },
+    /** Supply port for the custody exchange: `advertise` asks whether any new supply is admissible. */
+    admitSupply({ active, advertise = false }) {
+      const allowed = active < supplyAllowance(decide());
+      if (!advertise) counts[allowed ? 'supplyAdmitted' : 'supplyRefused']++;
+      return allowed;
+    },
+    paceChannel: createChannel => paceCustodyChannel(createChannel, { upload, download, meter }),
+    /** A paced download needs time for its bytes on top of the unchanged stall deadline. */
+    pieceTimeoutMs: (baseMs, maxBytes) => download ? baseMs + Math.ceil(maxBytes * 1000 / download.bytesPerSecond) : baseMs,
+    gpuBufferBytes: maxBytes => policy.memory?.maxGpuBufferBytes === undefined ? maxBytes : Math.min(maxBytes, policy.memory.maxGpuBufferBytes),
+    /** Gates only new attempts. An attempt this resident already holds keeps executing and settles normally. */
+    gateResident(resident) {
+      const ordered = typeof resident.executeStage === 'function' && typeof resident.transportId === 'string';
+      const holds = attemptId => typeof attemptId === 'string' && (resident.getState().reservations?.records || [])
+        .some(record => record.identity?.attemptId === attemptId && record.settledAt === null);
+      const active = () => resident.getState().reservations?.active ?? 0;
+      const gated = state => {
+        const reservations = state?.reservations;
+        if (!reservations) return state;
+        const allowed = Math.max(0, stageAllowance(decide()) - reservations.active);
+        return allowed >= reservations.availableSlots ? state : { ...state, reservations: { ...reservations, availableSlots: allowed } };
+      };
+      const admit = identity => {
+        if (holds(identity?.attemptId) || admitStage(active())) return;
+        // The same coded refusal the resident's own capacity limit produces on each path.
+        throw Object.assign(new Error(failureMessages.CAPACITY_UNAVAILABLE), { code: 'CAPACITY_UNAVAILABLE' });
+      };
+      return Object.freeze({ ...resident,
+        getState: () => gated(resident.getState()),
+        subscribe: listener => resident.subscribe(state => listener(gated(state))),
+        canAccept: identity => resident.canAccept(identity)
+          && (holds(identity?.attemptId) || stageAllowance(decide()) - active() > 0),
+        reserve: ordered ? async request => { admit(request?.identity); return resident.reserve(request); }
+          : identity => { admit(identity); return resident.reserve(identity); } });
+    },
+    close() {
+      if (closed) return;
+      closed = true; clearInterval(timer); upload?.close(); download?.close();
+      for (const wake of [...waiters.keys()]) wake(decide());
+    }
+  });
+}

package/server/native-owner/monitor.js

@@ -0,0 +1,251 @@
+/** Detects which owner controls this host can enforce and samples their readings.
+ * A control is supported only when a reading source was found and actually read;
+ * a configured setting alone never counts as enforcement. */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { execFile } from 'node:child_process';
+
+const readText = async file => (await fs.readFile(file, 'utf8')).trim();
+const readNumber = async file => { const value = Number(await readText(file)); if (!Number.isFinite(value)) throw new Error('Not numeric: ' + file); return value; };
+
+/** Runs a fixed system tool with no shell and a bounded wait; resolves its stdout. */
+export function runNativeTool(file, args, { timeoutMs }) {
+  return new Promise((resolve, reject) => {
+    execFile(file, args, { timeout: timeoutMs, maxBuffer: 4 * 1024 * 1024, windowsHide: true },
+      (error, stdout) => error ? reject(error) : resolve(String(stdout)));
+  });
+}
+
+/** Linux hwmon devices whose inputs were readable without elevated privileges. */
+export async function probeLinuxHwmon(sysfsRoot) {
+  const base = path.join(sysfsRoot, 'class', 'hwmon');
+  let entries;
+  try { entries = await fs.readdir(base); } catch { return []; }
+  const devices = [];
+  for (const id of entries.sort()) {
+    const directory = path.join(base, id);
+    let name, files;
+    try { name = await readText(path.join(directory, 'name')); files = await fs.readdir(directory); } catch { continue; }
+    const readable = async pattern => {
+      const found = [];
+      for (const file of files.filter(item => pattern.test(item)).sort()) {
+        try { await readNumber(path.join(directory, file)); found.push(file); } catch { /* unreadable input is not a source */ }
+      }
+      return found;
+    };
+    const powers = await readable(/^power\d+_(average|input)$/);
+    // One power input per channel; the driver's averaged value is preferred.
+    const channels = new Map();
+    for (const file of powers) { const channel = file.split('_')[0]; if (!channels.has(channel) || file.endsWith('_average')) channels.set(channel, file); }
+    devices.push({ id, name, directory, temperatures: await readable(/^temp\d+_input$/),
+      powers: [...channels.values()], energies: await readable(/^energy\d+_input$/) });
+  }
+  return devices;
+}
+
+/** System power supplies, excluding peripheral (scope=Device) batteries. */
+export async function probeLinuxPowerSupply(sysfsRoot) {
+  const base = path.join(sysfsRoot, 'class', 'power_supply');
+  let entries;
+  try { entries = await fs.readdir(base); } catch { return null; }
+  const supplies = [];
+  for (const id of entries.sort()) {
+    const directory = path.join(base, id);
+    let type, scope = null;
+    try { type = await readText(path.join(directory, 'type')); } catch { continue; }
+    try { scope = await readText(path.join(directory, 'scope')); } catch { /* optional */ }
+    if (scope === 'Device') continue;
+    supplies.push({ id, type, directory });
+  }
+  return supplies;
+}
+
+/** true: external power; false: running on a system battery; null: unknown. */
+async function readLinuxExternalPower(supplies) {
+  const batteries = supplies.filter(row => row.type === 'Battery');
+  const external = supplies.filter(row => row.type !== 'Battery');
+  let unreadable = false;
+  for (const supply of external) {
+    try { if (await readNumber(path.join(supply.directory, 'online')) === 1) return true; } catch { unreadable = true; }
+  }
+  if (!batteries.length) return true; // No system battery: the host runs on external power.
+  if (unreadable) return null;
+  if (external.length) return false;
+  // Only batteries are exposed: their charge status says whether external power is connected.
+  try {
+    const statuses = await Promise.all(batteries.map(row => readText(path.join(row.directory, 'status'))));
+    return !statuses.includes('Discharging');
+  } catch { return null; }
+}
+
+const parseIdleSeconds = output => {
+  const match = /"HIDIdleTime"\s*=\s*(\d+)/.exec(output);
+  return match ? Number(match[1]) / 1e9 : null;
+};
+const parseExternalPower = output => {
+  const match = /Now drawing from '([^']+)'/.exec(output);
+  return match ? match[1] === 'AC Power' : null;
+};
+
+async function readSignal(file) {
+  try { await fs.lstat(file); return true; }
+  catch (error) { return error.code === 'ENOENT' ? false : null; }
+}
+
+const MAC_TOOLS = { idle: ['/usr/sbin/ioreg', ['-c', 'IOHIDSystem', '-d', '4']], power: ['/usr/bin/pmset', ['-g', 'batt']] };
+
+/** Declares every owner control for this platform. Supported controls name their
+ * source; unsupported controls name why. `requested` marks controls the policy uses. */
+export async function detectNativeOwnerSupport({ policy, platform, sysfsRoot, run }) {
+  const timeoutMs = Math.floor(policy.sampleIntervalMs / 2);
+  const supported = (source, extra = {}) => ({ supported: true, source, ...extra });
+  const unsupported = reason => ({ supported: false, reason });
+  const controls = {
+    schedule: supported('host clock with policy IANA time zone'),
+    processMemory: supported('process resident set size'),
+    gpuBuffers: supported('Doppler device GPU buffer budget', { scope: 'application GPU buffer allocations, not physical VRAM' }),
+    uploadRate: supported('paced custody chunk supply', { scope: 'custody piece and file bytes; execution activations are not paced' }),
+    downloadRate: supported('paced custody chunk requests', { scope: 'custody piece and file bytes; execution activations are not paced' }),
+    temperature: unsupported('no non-root temperature source on ' + platform),
+    gpuPower: unsupported('no non-root GPU power source on ' + platform),
+    externalPower: unsupported('no power source reading on ' + platform),
+    inputIdle: unsupported('no input-idle source on ' + platform),
+    ownerSignal: supported('owner foreground signal file'),
+    wallPower: unsupported('wall power requires an external meter')
+  };
+  const hardware = { hwmon: [], supplies: null };
+  if (platform === 'linux') {
+    hardware.hwmon = await probeLinuxHwmon(sysfsRoot);
+    const names = devices => [...new Set(devices.map(device => device.name))];
+    const thermal = hardware.hwmon.filter(device => device.temperatures.length);
+    const electrical = hardware.hwmon.filter(device => device.powers.length || device.energies.length);
+    controls.temperature = thermal.length ? supported('linux hwmon', { sensors: names(thermal) })
+      : unsupported('no readable hwmon temperature input');
+    controls.gpuPower = electrical.length ? supported('linux hwmon', { sensors: names(electrical),
+      scope: 'component power reading, not wall power' }) : unsupported('no readable hwmon power or energy input');
+    hardware.supplies = await probeLinuxPowerSupply(sysfsRoot);
+    if (hardware.supplies) {
+      const external = await readLinuxExternalPower(hardware.supplies);
+      controls.externalPower = external === null ? unsupported('power_supply online state unreadable')
+        : supported('linux power_supply');
+    } else controls.externalPower = unsupported('no readable power_supply class');
+    controls.inputIdle = unsupported('no reliable non-root input-idle source; use foreground source "owner-signal"');
+  } else if (platform === 'darwin') {
+    controls.temperature = unsupported('no non-root temperature interface (powermetrics requires root)');
+    controls.gpuPower = unsupported('no non-root GPU power interface (powermetrics requires root)');
+    try {
+      controls.externalPower = parseExternalPower(await run(...MAC_TOOLS.power, { timeoutMs })) === null
+        ? unsupported('pmset reported no power source') : supported('pmset -g batt');
+    } catch (error) { controls.externalPower = unsupported('pmset unavailable: ' + error.message); }
+    try {
+      controls.inputIdle = parseIdleSeconds(await run(...MAC_TOOLS.idle, { timeoutMs })) === null
+        ? unsupported('ioreg reported no HIDIdleTime') : supported('ioreg IOHIDSystem HIDIdleTime');
+    } catch (error) { controls.inputIdle = unsupported('ioreg unavailable: ' + error.message); }
+  } else if (platform === 'win32') {
+    controls.temperature = unsupported('no non-administrator temperature interface implemented on Windows');
+    controls.gpuPower = unsupported('no GPU power interface implemented on Windows');
+    controls.externalPower = unsupported('no power source interface implemented on Windows');
+    controls.inputIdle = unsupported('input idle requires the interactive session; not implemented on Windows');
+  }
+  // A named sensor must exist; a sensor class alone does not enforce the owner's choice.
+  const requireSensors = (control, names) => {
+    const entry = controls[control];
+    if (!entry.supported) return;
+    const missing = names.filter(name => !entry.sensors.includes(name));
+    if (missing.length) controls[control] = unsupported('no readable sensor named ' + missing.join(', '));
+    else controls[control] = { ...entry, sensors: [...names] };
+  };
+  if (policy.temperature) requireSensors('temperature', policy.temperature.sensors);
+  if (policy.power?.gpuSensors) requireSensors('gpuPower', policy.power.gpuSensors);
+  if (policy.foreground?.source === 'owner-signal') {
+    const parent = path.dirname(policy.foreground.signalFile);
+    try { if (!(await fs.stat(parent)).isDirectory()) throw new Error('not a directory'); }
+    catch { controls.ownerSignal = unsupported('signal file directory is unavailable: ' + parent); }
+  }
+  const requested = {
+    schedule: !!policy.schedule, processMemory: policy.memory?.maxProcessResidentBytes !== undefined,
+    gpuBuffers: policy.memory?.maxGpuBufferBytes !== undefined, uploadRate: policy.bandwidth?.uploadBytesPerSecond !== undefined,
+    downloadRate: policy.bandwidth?.downloadBytesPerSecond !== undefined, temperature: !!policy.temperature,
+    // Measurement-only GPU sensors are declared but limit nothing, so they are not requested controls.
+    gpuPower: policy.power?.reduceAboveWatts !== undefined || policy.power?.deferAboveWatts !== undefined,
+    externalPower: !!policy.power?.requireExternalPower,
+    inputIdle: policy.foreground?.source === 'input-idle', ownerSignal: policy.foreground?.source === 'owner-signal', wallPower: false };
+  for (const [name, entry] of Object.entries(controls)) controls[name] = { requested: requested[name], ...entry };
+  return { platform, controls, hardware };
+}
+
+/** Samples readings for supported controls. Unsupported sources are never read and
+ * remain null. GPU energy uses energy counters where present, otherwise the
+ * integral of sampled power: both are component estimates, not wall power. */
+export function createNativeOwnerMonitor({ policy, support, platform, run, now, readGpuBuffers = null }) {
+  const timeoutMs = Math.floor(policy.sampleIntervalMs / 2);
+  const controls = support.controls, { hwmon, supplies } = support.hardware;
+  const named = (control, names) => controls[control].supported
+    ? hwmon.filter(device => (names || controls[control].sensors).includes(device.name)) : [];
+  // Only sensors the owner named are read.
+  const thermal = policy.temperature ? named('temperature', policy.temperature.sensors).filter(device => device.temperatures.length) : [];
+  const electrical = policy.power?.gpuSensors ? named('gpuPower', policy.power.gpuSensors)
+    .filter(device => device.powers.length || device.energies.length) : [];
+  const signalFile = policy.foreground?.source === 'owner-signal' ? policy.foreground.signalFile : null;
+  const counters = new Map(), lastPower = new Map(), methods = new Set();
+  let joules = 0;
+  async function temperature() {
+    const sensors = [];
+    for (const device of thermal) for (const file of device.temperatures) {
+      try { sensors.push({ name: device.name, input: file, celsius: await readNumber(path.join(device.directory, file)) / 1000 }); }
+      catch { return null; } // A configured sensor that stops reading must not pass as cool.
+    }
+    return sensors.length ? { maxCelsius: Math.max(...sensors.map(row => row.celsius)), sensors } : null;
+  }
+  async function gpuPower(at) {
+    let watts = 0, complete = true;
+    for (const device of electrical) {
+      if (device.powers.length) {
+        let deviceWatts = 0;
+        for (const file of device.powers) deviceWatts += await readNumber(path.join(device.directory, file)) / 1e6;
+        const last = lastPower.get(device.directory);
+        if (last && at > last.at) { joules += (last.watts + deviceWatts) / 2 * (at - last.at) / 1000; methods.add('integrated hwmon power samples'); }
+        lastPower.set(device.directory, { watts: deviceWatts, at });
+        watts += deviceWatts;
+        continue;
+      }
+      for (const file of device.energies) {
+        const key = path.join(device.directory, file), microjoules = await readNumber(key);
+        const last = counters.get(key); counters.set(key, { microjoules, at });
+        // The first sample or a counter reset has no interval to measure.
+        if (!last || at <= last.at || microjoules < last.microjoules) { complete = false; continue; }
+        watts += (microjoules - last.microjoules) / (at - last.at) / 1000;
+        joules += (microjoules - last.microjoules) / 1e6; methods.add('hwmon energy counters');
+      }
+    }
+    return complete ? { watts } : null;
+  }
+  async function sample() {
+    const at = now(), memory = process.memoryUsage(), cpu = process.cpuUsage();
+    const readings = { at, processResidentBytes: memory.rss, cpuUserMicros: cpu.user, cpuSystemMicros: cpu.system,
+      gpuBuffers: null, temperature: null, gpuPower: null, externalPower: null, inputIdleSeconds: null, foregroundSignal: null };
+    if (readGpuBuffers) {
+      try { const value = await readGpuBuffers(); readings.gpuBuffers = value && { liveBytes: value.liveBytes, peakBytes: value.peakBytes, maxBytes: value.maxBytes }; }
+      catch { readings.gpuBuffers = null; }
+    }
+    if (thermal.length) readings.temperature = await temperature();
+    if (electrical.length) {
+      // A failed read leaves a gap; power is not integrated across it.
+      try { readings.gpuPower = await gpuPower(at); } catch { readings.gpuPower = null; lastPower.clear(); }
+    }
+    if (controls.externalPower.supported && policy.power?.requireExternalPower) {
+      try {
+        readings.externalPower = platform === 'linux' ? await readLinuxExternalPower(supplies)
+          : parseExternalPower(await run(...MAC_TOOLS.power, { timeoutMs }));
+      } catch { readings.externalPower = null; }
+    }
+    if (controls.inputIdle.supported && policy.foreground?.source === 'input-idle') {
+      try { readings.inputIdleSeconds = parseIdleSeconds(await run(...MAC_TOOLS.idle, { timeoutMs })); }
+      catch { readings.inputIdleSeconds = null; }
+    }
+    if (controls.ownerSignal.supported && signalFile) readings.foregroundSignal = await readSignal(signalFile);
+    return readings;
+  }
+  return Object.freeze({ sample,
+    getEnergy: () => methods.size ? { gpuJoules: joules, method: [...methods].join(' + '), scope: 'GPU component estimate, not wall power' } : null });
+}