@code-yeongyu/senpi-codemode 2026.10.4 → 2026.10.6

package/src/kernels/py/kernel.ts

@@ -1,7 +1,8 @@
 // allow: SIZE_OK — one persistent Python lifecycle state machine owns queue, generation, and retirement.
-import type { KernelInterruptHandle } from "../../tool/types.ts";
+import type { KernelInterruptHandle, PendingCell } from "../../tool/types.ts";
 import type { KernelToolsInvokeOptions } from "../js/kernel-tools-types.ts";
 import { rejectKernelToolsUnavailable } from "../kernel-tools-unavailable.ts";
+import { describeExit } from "../shared/kernel-death.ts";
 import { KernelMemoryHost } from "../shared/kernel-memory-host.ts";
 import { KernelPreludeTracker } from "../shared/kernel-prelude-plan.ts";
 import type { PendingRun, PythonKernelRunOptions, PythonKernelStartOptions, ResultMessage } from "./kernel-contract.ts";
@@ -27,6 +28,7 @@ export class PythonKernel {
 	readonly #memory: KernelMemoryHost | null;
 	#generation = 0;
 	#closed = false;
+	#dead = false;
 
 	private constructor(options: PythonKernelStartOptions) {
 		this.#options = options;
@@ -43,6 +45,18 @@ export class PythonKernel {
 		return [];
 	}
 
+	isAlive(): boolean {
+		return !this.#dead;
+	}
+
+	drainPending(): readonly PendingCell[] {
+		return [...this.#queue].map((pending) => {
+			this.#pending.delete(pending.input.cellId);
+			this.#removePending(pending);
+			return { input: pending.input, settle: pending.resolve };
+		});
+	}
+
 	describeKernelTools(_names: readonly string[]): Promise<never> {
 		return rejectKernelToolsUnavailable();
 	}
@@ -54,6 +68,7 @@ export class PythonKernel {
 	run(input: PythonKernelRunOptions): Promise<ResultMessage> {
 		if (this.#failure) return Promise.reject(this.#failure);
 		if (this.#closed) return Promise.reject(new Error("Python kernel is closed"));
+		if (this.#dead) return Promise.reject(new Error("Python kernel died"));
 		return new Promise<ResultMessage>((resolve, reject) => {
 			const pending: PendingRun = { input, resolve, reject, startedAt: null, timeoutTimer: null };
 			this.#pending.set(input.cellId, pending);
@@ -156,6 +171,7 @@ export class PythonKernel {
 	#startNext(): void {
 		if (
 			this.#closed ||
+			this.#dead ||
 			this.#failure ||
 			this.#active ||
 			this.#starting ||
@@ -234,11 +250,11 @@ export class PythonKernel {
 			isOwned: () => !this.#closed && generation === this.#generation,
 			onRetirementFailure: (transport, error) => {
 				if (!this.#transport) this.#transport = transport;
-				this.#recordFailure(error);
+				this.#recoverWhenGone(transport, this.#recordFailure(error));
 			},
 			onResult: (transport, result) => this.#onResult(transport, result),
 			onError: (transport, error) => this.#onError(transport, error),
-			onExit: (transport, error) => this.#onExit(transport, error),
+			onExit: (transport, error, exit) => this.#onExit(transport, error, describeExit(exit.code, exit.signal)),
 		});
 	}
 
@@ -262,15 +278,37 @@ export class PythonKernel {
 		void this.reset().catch(() => undefined);
 	}
 
-	#onExit(transport: PythonKernelTransport, error: Error): void {
+	#onExit(transport: PythonKernelTransport, error: Error, reason: string): void {
 		if (this.#transport !== transport) return;
 		this.#transport = null;
+		// With an owner listening, a death is final for this instance: the cells that never started stay
+		// queued for `drainPending` and the owner replaces it. Without one it respawns lazily, as before.
+		const onDeath = this.#options.onDeath;
+		if (onDeath) this.#dead = true;
 		const active = this.#active;
 		if (active) {
 			if (active.resolveStateRetained) active.resolveStateRetained(false);
-			this.#settleRun(active, failedPythonResult(active.input.cellId, "Python kernel died", error.message));
+			const message = onDeath ? "Python kernel died; every global is lost" : "Python kernel died";
+			this.#settleRun(active, failedPythonResult(active.input.cellId, message, error.message));
 		}
-		this.#startNext();
+		if (onDeath) onDeath(reason);
+		else this.#startNext();
+	}
+
+	/**
+	 * A retirement that timed out is reported, and no second interpreter starts while the first may live.
+	 * Once that process is seen to exit after all, the failure is over: this instance is dead, not broken.
+	 */
+	#recoverWhenGone(transport: PythonKernelTransport, failure: Error): void {
+		const onDeath = this.#options.onDeath;
+		if (!onDeath) return;
+		void transport.whenGone().then(() => {
+			if (this.#closed || this.#failure !== failure) return;
+			this.#failure = null;
+			this.#dead = true;
+			if (this.#transport === transport) this.#transport = null;
+			onDeath("an interpreter that outlived its SIGKILL grace");
+		});
 	}
 
 	#onError(transport: PythonKernelTransport, error: Error): void {
@@ -349,8 +387,10 @@ export class PythonKernel {
 			try {
 				await transport.retire();
 			} catch (error) {
-				if (error instanceof Error) throw this.#recordFailure(error);
-				throw error;
+				if (!(error instanceof Error)) throw error;
+				const failure = this.#recordFailure(error);
+				this.#recoverWhenGone(transport, failure);
+				throw failure;
 			}
 			if (this.#transport === transport) this.#transport = null;
 		})();

package/src/kernels/py/prelude.py

@@ -354,6 +354,11 @@ def write(path: str | Path, content: str) -> Path:
     return target
 
 
+# The bridge is a loopback call: urllib's default opener would route it through a configured proxy
+# (the environment everywhere, the registry on Windows), which a 127.0.0.1 request must never use.
+_BRIDGE_OPENER = urllib.request.build_opener(urllib.request.ProxyHandler({}))
+
+
 def bridge_post(path: str, payload: dict[str, Any]) -> Any:
     port = CONNECTION.get("port")
     token = CONNECTION.get("token")
@@ -369,7 +374,7 @@ def bridge_post(path: str, payload: dict[str, Any]) -> Any:
     emit_status(TIMEOUT_PAUSE_OP, force=True)
     try:
         try:
-            with urllib.request.urlopen(request, timeout=60) as response:
+            with _BRIDGE_OPENER.open(request, timeout=60) as response:
                 response_data = response.read()
         except urllib.error.HTTPError as exc:
             response_data = exc.read()

package/src/kernels/py/transport.ts

@@ -52,7 +52,11 @@ export interface PythonTransportOptions {
 	readonly onRetirementFailure: (transport: PythonKernelTransport, error: Error) => void;
 	readonly onResult: (transport: PythonKernelTransport, result: PythonTransportResult) => void;
 	readonly onError: (transport: PythonKernelTransport, error: Error) => void;
-	readonly onExit: (transport: PythonKernelTransport, error: Error) => void;
+	readonly onExit: (
+		transport: PythonKernelTransport,
+		error: Error,
+		exit: { readonly code: number | null; readonly signal: string | null },
+	) => void;
 }
 
 const hardKillWaitMs = 500;
@@ -79,12 +83,29 @@ export class PythonKernelTransport {
 	#active = true;
 	#exited = false;
 	#retirement: Promise<void> | null = null;
+	#gone: Promise<void> | null = null;
+	#isGone = false;
 
 	private constructor(options: PythonTransportOptions, child: KernelChild) {
 		this.#options = options;
 		this.#child = child;
 	}
 
+	/**
+	 * A retirement that timed out is confirmed only by this: the process really exited after all. The
+	 * watch is attached on demand, so a transport nobody asks this of leaves no listener on its child.
+	 */
+	whenGone(): Promise<void> {
+		if (this.#exited || this.#isGone) return Promise.resolve();
+		this.#gone ??= new Promise<void>((resolve) => {
+			this.#child.once("exit", () => {
+				this.#isGone = true;
+				resolve();
+			});
+		});
+		return this.#gone;
+	}
+
 	static async start(options: PythonTransportOptions): Promise<PythonKernelTransport> {
 		const scriptPath = resolvePythonPreludePath();
 		const invocation = splitCommand(options.interpreterPath);
@@ -139,7 +160,7 @@ export class PythonKernelTransport {
 	}
 
 	async close(): Promise<void> {
-		if (this.#exited) return;
+		if (this.#exited || this.#isGone) return;
 		if (this.#retirement) {
 			await this.#retirement;
 			return;
@@ -162,7 +183,7 @@ export class PythonKernelTransport {
 	}
 
 	retire(): Promise<void> {
-		if (this.#exited) return Promise.resolve();
+		if (this.#exited || this.#isGone) return Promise.resolve();
 		if (this.#retirement) return this.#retirement;
 		this.#active = false;
 		const retirement = hardKill(this.#child, hardKillWaitMs).finally(() => {
@@ -244,7 +265,7 @@ export class PythonKernelTransport {
 		const error = new Error(this.#stderrTail.trim() || `Python kernel exited (${code ?? signal ?? "unknown"})`);
 		this.#detachListeners();
 		if (!active) return;
-		if (!this.#settleStartup(error)) this.#options.onExit(this, error);
+		if (!this.#settleStartup(error)) this.#options.onExit(this, error, { code, signal });
 	}
 
 	#onError(error: Error): void {

package/src/kernels/rb/kernel.ts

@@ -1,10 +1,12 @@
 import { join } from "node:path";
 import type { BridgeConnectionConfig, KernelToHostMessage } from "../../bridge/protocol.ts";
 import type { SessionEnvironment } from "../session-env.ts";
+import type { KernelLifecycle } from "../shared/kernel-death.ts";
+import { readProcessGroupCpuTime } from "../shared/process-group-cpu.ts";
 import { type CodemodeRuntimeAssetEnvironment, requireCodemodeRuntimeAsset } from "../shared/runtime-asset.ts";
 import { SubprocessKernel, type SubprocessKernelMemory, type SubprocessSpawn } from "../shared/subprocess-kernel.ts";
 
-export interface RubyKernelStartOptions {
+export interface RubyKernelStartOptions extends KernelLifecycle {
 	readonly cwd: string;
 	readonly sessionId: string;
 	readonly connection: BridgeConnectionConfig;
@@ -13,7 +15,7 @@ export interface RubyKernelStartOptions {
 	readonly command?: string;
 	readonly spawn?: SubprocessSpawn;
 	readonly onMessage?: (message: KernelToHostMessage) => void;
-	/** Ceiling-only memory management (no notice or globals list: the runner reports no memory). */
+	/** Memory management: the runner reports its largest globals and the host reads the interpreter footprint for the ceiling. */
 	readonly memory?: SubprocessKernelMemory;
 }
 
@@ -41,6 +43,8 @@ export class RubyKernel extends SubprocessKernel {
 			spawn: options.spawn,
 			onMessage: options.onMessage,
 			memory: options.memory && { language: "rb", ...options.memory },
+			onDeath: options.onDeath,
+			startup: { label: "Ruby", readGroupCpuTime: readProcessGroupCpuTime },
 		});
 	}
 }

package/src/kernels/rb/runner.rb

@@ -1,6 +1,10 @@
+$stdout.write("{\"type\":\"status\",\"event\":{\"op\":\"kernel-startup\",\"stage\":\"stdlib-imports\"}}\n")
+$stdout.flush
 require "json"
 require "net/http"
 require "uri"
+$stdout.write("{\"type\":\"status\",\"event\":{\"op\":\"kernel-startup\",\"stage\":\"runtime-init\"}}\n")
+$stdout.flush
 
 $__senpi_binding = TOPLEVEL_BINDING
 $__senpi_frame_mutex = Mutex.new
@@ -119,6 +123,135 @@ rescue JSON::GeneratorError
   value.inspect
 end
 
+$__senpi_memory = nil
+
+SENPI_SIZER_SAMPLE = 1_000
+SENPI_SIZER_NODE_BUDGET = 5_000
+SENPI_SIZER_MAX_DEPTH = 64
+SENPI_SIZER_POINTER = 8
+SENPI_SIZER_OBJECT = 40
+SENPI_SIZER_MIN_REPORTED = 1024 * 1024
+SENPI_ARRAY_AT = Array.instance_method(:[])
+SENPI_ARRAY_SIZE = Array.instance_method(:size)
+SENPI_HASH_SIZE = Hash.instance_method(:size)
+SENPI_HASH_EACH = Hash.instance_method(:each_pair)
+SENPI_STRING_BYTESIZE = String.instance_method(:bytesize)
+SENPI_IVARS = Kernel.instance_method(:instance_variables)
+SENPI_IVAR_GET = Kernel.instance_method(:instance_variable_get)
+
+# Sizes a global without running user code: built-ins are read through their own unbound methods, so an
+# override in a subclass is never called. Collections are sampled, and each global gets its own node
+# budget (leaves count against it too), so one deep global never hides the ones measured after it.
+class SenpiGlobalSizer
+  attr_reader :approximate
+
+  def initialize
+    @seen = {}.compare_by_identity
+    @nodes = 0
+    @approximate = false
+  end
+
+  def measure(value)
+    @approximate = false
+    @nodes = 0
+    SENPI_SIZER_POINTER + size(value, 0)
+  end
+
+  private
+
+  def size(value, depth)
+    @nodes += 1
+    return 0 if NilClass === value || TrueClass === value || FalseClass === value || Symbol === value
+    return ObjectSpace.memsize_of(value) if Integer === value || Float === value
+    return 0 if @seen.key?(value)
+    @seen[value] = true
+    return SENPI_SIZER_OBJECT + SENPI_STRING_BYTESIZE.bind_call(value) if String === value
+    if depth >= SENPI_SIZER_MAX_DEPTH || @nodes >= SENPI_SIZER_NODE_BUDGET
+      @approximate = true
+      return ObjectSpace.memsize_of(value)
+    end
+    if Array === value
+      length = SENPI_ARRAY_SIZE.bind_call(value)
+      SENPI_SIZER_OBJECT + length * SENPI_SIZER_POINTER + sampled(length, depth) { |index| SENPI_ARRAY_AT.bind_call(value, index) }
+    elsif Hash === value
+      hash_size(value, depth)
+    else
+      ivars = SENPI_IVARS.bind_call(value)
+      ObjectSpace.memsize_of(value) + sampled(ivars.length, depth) { |index| SENPI_IVAR_GET.bind_call(value, ivars[index]) }
+    end
+  end
+
+  def hash_size(hash, depth)
+    count = SENPI_HASH_SIZE.bind_call(hash)
+    taken = 0
+    total = 0
+    SENPI_HASH_EACH.bind_call(hash) do |key, item|
+      total += size(key, depth + 1) + size(item, depth + 1)
+      taken += 1
+      break if taken >= SENPI_SIZER_SAMPLE
+    end
+    @approximate = true if taken < count
+    SENPI_SIZER_OBJECT + count * 2 * SENPI_SIZER_POINTER + (taken.zero? ? 0 : total * count / taken)
+  end
+
+  # Up to SENPI_SIZER_SAMPLE evenly spaced elements; when the walk budget runs out part-way, the elements
+  # measured so far stand in for the rest, so a cut-short container is scaled up, not under-counted.
+  def sampled(length, depth)
+    return 0 if length.zero?
+    picks = [length, SENPI_SIZER_SAMPLE].min
+    @approximate = true if picks < length
+    step = length.to_f / picks
+    total = 0
+    measured = 0
+    picks.times do |sample|
+      if @nodes >= SENPI_SIZER_NODE_BUDGET
+        @approximate = true
+        break
+      end
+      total += size(yield((sample * step).floor), depth + 1)
+      measured += 1
+    end
+    measured.zero? ? 0 : (total.to_f / measured * length).round
+  end
+end
+
+def __senpi_largest_globals(limit)
+  require "objspace"
+  sizer = SenpiGlobalSizer.new
+  sized = []
+  measure = lambda do |name, value|
+    bytes = sizer.measure(value)
+    next if bytes < SENPI_SIZER_MIN_REPORTED
+    entry = { "name" => name, "bytes" => bytes }
+    entry["approximate"] = true if sizer.approximate
+    sized << entry
+  end
+  $__senpi_binding.local_variables.each do |name|
+    next if $__senpi_memory_baseline_locals.include?(name)
+    measure.call(name.to_s, $__senpi_binding.local_variable_get(name))
+  end
+  global_variables.each do |name|
+    next if $__senpi_memory_baseline_globals.include?(name) || name.to_s.start_with?("$__senpi_")
+    measure.call(name.to_s, eval(name.to_s))
+  end
+  sized.sort_by { |entry| -entry["bytes"] }.first(limit)
+rescue StandardError
+  []
+end
+
+# The host reads the interpreter's footprint and decides on the notice; the runner only names its
+# largest globals. Nothing here spawns a process, so the user's `$?` is left alone.
+def __senpi_memory_report
+  return nil if $__senpi_memory.nil?
+  named = __senpi_largest_globals(5)
+  # The host replaces liveBytes with the interpreter footprint it reads itself; only globals is used.
+  report = { "liveBytes" => 0, "measure" => "footprint" }
+  report["globals"] = named unless named.empty?
+  report
+rescue StandardError
+  nil
+end
+
 SENPI_NON_DISPLAY_NODES = %i[
   LASGN IASGN GASGN CVASGN DASGN OP_ASGN OP_CDECL CDECL MASGN CASGN
   DEFN DEFS CLASS MODULE SCLASS ALIAS UNDEF
@@ -172,6 +305,8 @@ def __senpi_run_cell(message)
       "durationMs" => ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000).round,
     }
     frame["valueRepr"] = __senpi_value_repr(value) if !value.nil? && __senpi_should_display_result?(source)
+    memory = __senpi_memory_report
+    frame["memory"] = memory unless memory.nil?
     __senpi_emit(frame)
   rescue Exception => error
     __senpi_emit({
@@ -187,11 +322,17 @@ def __senpi_run_cell(message)
   end
 end
 
+# Everything defined so far belongs to the runner or the interpreter, never to the user's cells.
+$__senpi_memory_baseline_locals = $__senpi_binding.local_variables
+$__senpi_memory_baseline_globals = global_variables
+
 $__senpi_protocol_stdin.each_line do |line|
   message = JSON.parse(line)
   case message["type"]
   when "init"
+    __senpi_emit({ "type" => "status", "event" => { "op" => "kernel-startup", "stage" => "host-init" } })
     $__senpi_connection = message["connection"]
+    $__senpi_memory = message["memory"]
     __senpi_emit({ "type" => "ready" })
   when "run"
     __senpi_run_cell(message)

package/src/kernels/session-env.ts

@@ -17,6 +17,7 @@ export const SESSION_ENVIRONMENT_KEYS = [
 	"PI_PROVIDER",
 	"PI_MODEL",
 	"PI_REASONING_LEVEL",
+	"OMO_BROWSER_ENGINE",
 ] as const;
 
 /** Resolved per-session values for {@link SESSION_ENVIRONMENT_KEYS}; absent keys stay unset. */
@@ -32,6 +33,7 @@ export interface SessionEnvironmentSource {
 	};
 	readonly model?: { readonly provider: string; readonly id: string } | undefined;
 	readonly thinkingLevel?: string | undefined;
+	readonly browserEngine?: string | undefined;
 }
 
 export function sessionEnvironmentFrom(source: SessionEnvironmentSource): SessionEnvironment {
@@ -47,6 +49,7 @@ export function sessionEnvironmentFrom(source: SessionEnvironmentSource): Sessio
 		env.PI_MODEL = model.id;
 	}
 	if (source.thinkingLevel) env.PI_REASONING_LEVEL = source.thinkingLevel;
+	if (source.browserEngine) env.OMO_BROWSER_ENGINE = source.browserEngine;
 	return env;
 }
 

package/src/kernels/shared/kernel-death.ts

@@ -0,0 +1,39 @@
+import { constants } from "node:os";
+import type { EvalKernelResult, EvalLanguage } from "../../tool/types.ts";
+
+/** How the session manager hears that a kernel's interpreter died. */
+export interface KernelLifecycle {
+	/** Called once when the interpreter died on its own; the kernel then keeps its unstarted cells for `drainPending`. */
+	readonly onDeath?: (reason: string) => void;
+}
+
+/** The wording a restart notice uses for an exit nobody asked for: "signal 9", "exit code 1". */
+export function describeExit(code: number | null, signal: string | null): string {
+	if (signal !== null) {
+		const number = Object.entries(constants.signals).find(([name]) => name === signal)?.[1];
+		return `signal ${number ?? signal}`;
+	}
+	return code === null ? "an exit with no status" : `exit code ${code}`;
+}
+
+export function restartNotice(language: EvalLanguage, reason: string): string {
+	return `[${language} kernel was restarted after ${reason}; every global is lost]`;
+}
+
+export const EVAL_KERNEL_UNAVAILABLE = "eval_kernel_unavailable";
+
+/** A queued cell that never ran: its kernel died again before the replacement finished one cell. */
+export class KernelUnavailableError extends Error {
+	readonly name = "KernelUnavailableError";
+	readonly code = EVAL_KERNEL_UNAVAILABLE;
+
+	constructor(language: EvalLanguage, reason: string) {
+		super(
+			`${EVAL_KERNEL_UNAVAILABLE}: the ${language} kernel died again (${reason}) before its replacement finished a cell; this cell never ran. Run it again to start a fresh kernel.`,
+		);
+	}
+}
+
+export function unstartedResult(cellId: string, message: string): EvalKernelResult {
+	return { type: "result", cellId, ok: false, error: { message }, durationMs: 0, kernelState: "not-run" };
+}

package/src/kernels/shared/kernel-memory-host.ts

@@ -10,8 +10,9 @@ export type FootprintReader = (pid: number) => { readonly bytes: number } | unde
 
 export interface KernelMemoryHostOptions {
 	/**
-	 * Host-measured kernel (rb, jl): the kernel reports no memory itself, so the host reads the
-	 * interpreter's footprint after each result. Such a kernel gets the ceiling only - no notice, no globals.
+	 * Host-measured kernel (rb, jl): the host reads the interpreter's footprint after each result and
+	 * replaces the runner's live reading with it; the runner still names its largest globals, so the
+	 * notice and the ceiling both apply, with every reading counting (no collection precedes it).
 	 */
 	readonly readFootprint?: FootprintReader;
 }
@@ -31,12 +32,15 @@ export class KernelMemoryHost {
 		this.#policy =
 			this.#readFootprint === undefined
 				? new KernelMemoryPolicy(language, thresholds)
-				: new KernelMemoryPolicy(language, { ...thresholds, noticeBytes: 0 }, { collects: false });
+				: new KernelMemoryPolicy(language, thresholds, { collects: false });
 	}
 
 	annotate(result: ResultMessage, pid?: number): ResultMessage {
+		const runnerReport = result.memory;
 		const report =
-			this.#readFootprint === undefined ? result.memory : this.#footprintReport(this.#readFootprint, pid);
+			this.#readFootprint === undefined
+				? runnerReport
+				: this.#footprintReport(this.#readFootprint, pid, runnerReport);
 		return report === undefined ? result : { ...result, memory: this.#policy.annotate(report) };
 	}
 
@@ -54,10 +58,14 @@ export class KernelMemoryHost {
 		this.#policy.kernelRetired();
 	}
 
-	#footprintReport(read: FootprintReader, pid: number | undefined) {
+	#footprintReport(read: FootprintReader, pid: number | undefined, runnerReport: ResultMessage["memory"]) {
 		if (pid === undefined) return undefined;
 		const footprint = read(pid);
 		if (footprint === undefined) return undefined;
-		return { liveBytes: Math.round(footprint.bytes), measure: "footprint" as const };
+		return {
+			liveBytes: Math.round(footprint.bytes),
+			measure: "footprint" as const,
+			...(runnerReport?.globals === undefined ? {} : { globals: runnerReport.globals }),
+		};
 	}
 }

package/src/kernels/{js/kernel-tools-host.ts → shared/kernel-tools-pump.ts}

@@ -1,13 +1,13 @@
 import type { HostToKernelMessage, KernelToHostMessage } from "../../bridge/protocol.ts";
 import { generateCorrelationId } from "../../bridge/protocol.ts";
 import { RESERVED_AGENT_TOOL } from "../../bridge/reserved.ts";
-import { kernelToolError } from "./kernel-tools-errors.ts";
+import { kernelToolError } from "../js/kernel-tools-errors.ts";
 import type {
 	KernelToolsDescribeResult,
 	KernelToolsInvokeOptions,
 	KernelToolsInvokeRequest,
 	KernelToolsInvokeScope,
-} from "./kernel-tools-types.ts";
+} from "../js/kernel-tools-types.ts";
 
 type KernelToolReply = Extract<
 	KernelToHostMessage,

package/src/kernels/shared/process-group-cpu.ts

@@ -0,0 +1,139 @@
+/**
+ * CPU time a process group has used so far, read from the kernel without spawning anything, in
+ * platform units that only ever grow: the startup watchdog compares two readings and never converts.
+ *
+ * - darwin: every member from `proc_listpgrppids`, each `ri_user_time + ri_system_time` from
+ *   `proc_pid_rusage(RUSAGE_INFO_V2)` (libproc, via `bun:ffi`);
+ * - linux: every `/proc/<pid>/stat` whose process group is `pgid`, `utime + stime` in clock ticks;
+ * - darwin on a runtime without `bun:ffi` (Node): the members' `cputime` from one `ps` call, in
+ *   hundredths of a second;
+ * - win32 and anything else: `undefined`. Windows has no process groups, and the launcher's own time
+ *   misses the interpreter a launcher such as juliaup starts, so the caller treats the CPU as unknown.
+ *
+ * `bun:ffi` is fetched with `process.getBuiltinModule` so the module still loads on Node, the same
+ * runtime boundary `process-footprint.ts` in coding-agent uses. Every read is synchronous and never throws.
+ */
+import { execFileSync } from "node:child_process";
+import { readdirSync, readFileSync } from "node:fs";
+
+type BunFfi = typeof import("bun:ffi");
+type GroupCpuReader = (pgid: number) => bigint | undefined;
+
+const RUSAGE_INFO_V2 = 2;
+const RI_USER_TIME_OFFSET = 16;
+const RI_SYSTEM_TIME_OFFSET = 24;
+const RUSAGE_BUFFER_BYTES = 256;
+const MAX_GROUP_MEMBERS = 4096;
+const PS_TIMEOUT_MS = 2_000;
+
+let groupReader: GroupCpuReader | null | undefined;
+
+export function readProcessGroupCpuTime(pgid: number): bigint | undefined {
+	if (!Number.isInteger(pgid) || pgid <= 0) return undefined;
+	if (groupReader === undefined) groupReader = createGroupReader() ?? null;
+	return groupReader?.(pgid);
+}
+
+/** `utime + stime` and the process group from `/proc/<pid>/stat` text, or `undefined` when malformed. */
+export function parseProcStat(stat: string): { readonly pgrp: number; readonly cpuTicks: bigint } | undefined {
+	// The command name may itself contain spaces or parentheses: the fields start after the last ")".
+	const fields = stat.slice(stat.lastIndexOf(")") + 2).split(" ");
+	const pgrp = Number(fields[2]);
+	const utime = fields[11];
+	const stime = fields[12];
+	if (!Number.isInteger(pgrp) || utime === undefined || stime === undefined) return undefined;
+	if (!/^\d+$/.test(utime) || !/^\d+$/.test(stime)) return undefined;
+	return { pgrp, cpuTicks: BigInt(utime) + BigInt(stime) };
+}
+
+/** `ps` `cputime` (`[[hh:]mm:]ss.cc`) in hundredths of a second, or `undefined` when malformed. */
+export function parsePsCpuTime(text: string): bigint | undefined {
+	const match = /^(?:(\d+):)?(?:(\d+):)?(\d+)\.(\d{2})$/.exec(text.trim());
+	if (match === null) return undefined;
+	const [, first, second, seconds, hundredths] = match;
+	const hours = second === undefined ? 0 : Number(first ?? 0);
+	const minutes = second === undefined ? Number(first ?? 0) : Number(second);
+	return BigInt(((hours * 60 + minutes) * 60 + Number(seconds)) * 100 + Number(hundredths));
+}
+
+function createGroupReader(): GroupCpuReader | undefined {
+	if (process.platform === "linux") return linuxGroupReader;
+	if (process.platform !== "darwin") return undefined;
+	const ffi = process.getBuiltinModule("bun:ffi") as BunFfi | undefined;
+	if (ffi === undefined) return darwinPsGroupReader;
+	try {
+		return darwinGroupReader(ffi);
+	} catch {
+		// A library or symbol this build cannot bind: read the group through ps instead.
+		return darwinPsGroupReader;
+	}
+}
+
+function darwinPsGroupReader(pgid: number): bigint | undefined {
+	let listing: string;
+	try {
+		listing = execFileSync("ps", ["-A", "-o", "pgid=,cputime="], { encoding: "utf8", timeout: PS_TIMEOUT_MS });
+	} catch {
+		return undefined;
+	}
+	let total = 0n;
+	let members = 0;
+	for (const line of listing.split("\n")) {
+		const [group, cputime] = line.trim().split(/\s+/);
+		if (group !== String(pgid) || cputime === undefined) continue;
+		const used = parsePsCpuTime(cputime);
+		if (used === undefined) continue;
+		total += used;
+		members += 1;
+	}
+	return members === 0 ? undefined : total;
+}
+
+function linuxGroupReader(pgid: number): bigint | undefined {
+	let entries: string[];
+	try {
+		entries = readdirSync("/proc");
+	} catch {
+		return undefined;
+	}
+	let total = 0n;
+	let members = 0;
+	for (const entry of entries) {
+		if (!/^\d+$/.test(entry)) continue;
+		let stat: string;
+		try {
+			stat = readFileSync(`/proc/${entry}/stat`, "utf8");
+		} catch {
+			// The process exited between the directory read and this one.
+			continue;
+		}
+		const parsed = parseProcStat(stat);
+		if (parsed === undefined || parsed.pgrp !== pgid) continue;
+		total += parsed.cpuTicks;
+		members += 1;
+	}
+	return members === 0 ? undefined : total;
+}
+
+function darwinGroupReader({ dlopen, FFIType, ptr }: BunFfi): GroupCpuReader {
+	const library = dlopen("libSystem.B.dylib", {
+		proc_listpgrppids: { args: [FFIType.i32, FFIType.ptr, FFIType.i32], returns: FFIType.i32 },
+		proc_pid_rusage: { args: [FFIType.i32, FFIType.i32, FFIType.ptr], returns: FFIType.i32 },
+	});
+	const pids = new Int32Array(MAX_GROUP_MEMBERS);
+	const usage = new Uint8Array(RUSAGE_BUFFER_BYTES);
+	const view = new DataView(usage.buffer);
+	return (pgid) => {
+		const count = library.symbols.proc_listpgrppids(pgid, ptr(pids), pids.byteLength);
+		if (count <= 0) return undefined;
+		let total = 0n;
+		let members = 0;
+		for (const pid of pids.subarray(0, Math.min(count, MAX_GROUP_MEMBERS))) {
+			usage.fill(0);
+			if (library.symbols.proc_pid_rusage(pid, RUSAGE_INFO_V2, ptr(usage)) !== 0) continue;
+			total += view.getBigUint64(RI_USER_TIME_OFFSET, true) + view.getBigUint64(RI_SYSTEM_TIME_OFFSET, true);
+			members += 1;
+		}
+		return members === 0 ? undefined : total;
+	};
+}