@code-yeongyu/senpi-codemode 2026.10.5 → 2026.10.7

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(value).call() 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(value).call()
+      SENPI_SIZER_OBJECT + length * SENPI_SIZER_POINTER + sampled(length, depth) { |index| SENPI_ARRAY_AT.bind(value).call(index) }
+    elsif Hash === value
+      hash_size(value, depth)
+    else
+      ivars = SENPI_IVARS.bind(value).call()
+      ObjectSpace.memsize_of(value) + sampled(ivars.length, depth) { |index| SENPI_IVAR_GET.bind(value).call(ivars[index]) }
+    end
+  end
+
+  def hash_size(hash, depth)
+    count = SENPI_HASH_SIZE.bind(hash).call()
+    taken = 0
+    total = 0
+    SENPI_HASH_EACH.bind(hash).call() 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/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;
+	};
+}

package/src/kernels/shared/subprocess-contract.ts

@@ -5,6 +5,7 @@ import type { SessionEnvironment } from "../session-env.ts";
 import type { KernelLifecycle } from "./kernel-death.ts";
 import type { FootprintReader } from "./kernel-memory-host.ts";
 import type { SubprocessSpawn } from "./subprocess-process.ts";
+import type { SubprocessStartupOptions } from "./subprocess-startup.ts";
 
 export type KernelRunInput = EvalKernelRunInput;
 
@@ -29,4 +30,6 @@ export interface SubprocessKernelOptions extends KernelLifecycle {
 	readonly spawn?: SubprocessSpawn;
 	readonly onMessage?: (message: KernelToHostMessage) => void;
 	readonly memory?: SubprocessKernelMemory & { readonly language: EvalLanguage };
+	/** Fails a start that stops making progress before `ready`; absent, the kernel waits for `ready` indefinitely. */
+	readonly startup?: SubprocessStartupOptions;
 }

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

@@ -23,6 +23,7 @@ import {
 	settlePendingRun,
 	timeoutResult,
 } from "./subprocess-run.ts";
+import { SubprocessStartupWatchdog } from "./subprocess-startup.ts";
 
 export type {
 	KernelResult,
@@ -40,6 +41,7 @@ export class SubprocessKernel {
 	private readonly memory: KernelMemoryHost | null;
 	private process: SubprocessProcess | null = null;
 	private processReady = false;
+	private startup: SubprocessStartupWatchdog | null = null;
 	private retirementPromise: Promise<void> | null = null;
 	private retirementProcess: SubprocessProcess | null = null;
 	private retirementFailure: Error | null = null;
@@ -133,6 +135,7 @@ export class SubprocessKernel {
 	async close(): Promise<void> {
 		const wasClosed = this.closed;
 		this.closed = true;
+		this.startup?.stop();
 		if (!wasClosed) {
 			this.settleAll(new KernelClosingError());
 			this.runs.clearToolCalls();
@@ -197,10 +200,21 @@ export class SubprocessKernel {
 		});
 		this.process = process;
 		this.processReady = false;
+		this.startup?.stop();
+		const startup = this.options.startup;
+		this.startup = startup
+			? new SubprocessStartupWatchdog(startup, child.pid, (message) => this.stalled(process, message))
+			: null;
 		this.memory?.processReplaced();
 		try {
+			const thresholds = this.options.memory?.thresholds;
 			process.send(
-				encodeBridgeFrame({ type: "init", sessionId: this.options.sessionId, connection: this.options.connection }),
+				encodeBridgeFrame({
+					type: "init",
+					sessionId: this.options.sessionId,
+					connection: this.options.connection,
+					...(thresholds === undefined ? {} : { memory: thresholds }),
+				}),
 			);
 		} catch (error) {
 			const failure = new KernelStartupError(error instanceof Error ? error.message : String(error));
@@ -221,7 +235,9 @@ export class SubprocessKernel {
 
 	private handleMessage(process: SubprocessProcess, message: KernelToHostMessage): void {
 		if (!this.accepts(process)) return;
+		if (!this.processReady) this.startup?.observe(message);
 		if (message.type === "ready") {
+			this.startup?.stop();
 			this.processReady = true;
 			this.runs.handleMessage(message, this.onMessage);
 			this.pumpRuns();
@@ -247,6 +263,7 @@ export class SubprocessKernel {
 
 	private handleExit(process: SubprocessProcess, code: number | null, signal: NodeJS.Signals | null): void {
 		if (this.process !== process) return;
+		this.startup?.stop();
 		if (process.isRetiring) {
 			this.process = null;
 			this.retirementFailure = null;
@@ -277,6 +294,20 @@ export class SubprocessKernel {
 		onDeath(reason);
 	}
 
+	/** A stalled start is a death: the owner replaces the kernel and the cells that never started run there. */
+	private stalled(process: SubprocessProcess, message: string): void {
+		if (!this.accepts(process)) return;
+		const error = new KernelStartupError(message);
+		const onDeath = this.options.onDeath;
+		if (!onDeath) {
+			this.failClosed(error);
+			return;
+		}
+		process.retire();
+		this.trackRetirement(process, this.terminateOwnedProcess(process));
+		this.die(error, message, onDeath);
+	}
+
 	private accepts(process: SubprocessProcess): boolean {
 		return !this.closed && this.process === process && !process.isRetiring;
 	}
@@ -330,6 +361,7 @@ export class SubprocessKernel {
 	}
 
 	private failClosed(error: Error): void {
+		this.startup?.stop();
 		const process = this.process;
 		this.failure = error;
 		this.closed = true;

package/src/kernels/shared/subprocess-startup.ts

@@ -0,0 +1,90 @@
+import type { KernelToHostMessage } from "../../bridge/protocol.ts";
+
+/**
+ * How long a starting interpreter may stay completely still - no output line, no new startup stage, and
+ * no CPU used by its process group - before startup fails. A cold Julia compiling its prelude prints
+ * nothing for seconds but keeps the CPU busy, so it never trips; only a runner that is silent AND idle
+ * (blocked on a lock, a pipe or a stopped process) does. It restarts on every sign of progress, so it is
+ * not a total startup budget. Where the group's CPU cannot be read it never fires.
+ */
+export const subprocessStartupNoProgressMs = 30_000;
+
+const STDERR_TAIL_CHARS = 2_000;
+const stages = ["interpreter-launch", "stdlib-imports", "runtime-init", "host-init"] as const;
+export type SubprocessStartupStage = (typeof stages)[number];
+
+export interface SubprocessStartupOptions {
+	readonly label: string;
+	readonly noProgressMs?: number;
+	/** CPU time used so far by a process group (any unit that only grows); `undefined` when unreadable. */
+	readonly readGroupCpuTime?: (pgid: number) => bigint | undefined;
+}
+
+export class SubprocessStartupWatchdog {
+	readonly #options: SubprocessStartupOptions;
+	readonly #pid: number | undefined;
+	readonly #onStall: (message: string) => void;
+	readonly #noProgressMs: number;
+	#stageIndex = 0;
+	#stderrTail = "";
+	#lastCpu: bigint | undefined;
+	#timer: ReturnType<typeof setTimeout> | undefined;
+	#stopped = false;
+
+	constructor(options: SubprocessStartupOptions, pid: number | undefined, onStall: (message: string) => void) {
+		this.#options = options;
+		this.#pid = pid;
+		this.#onStall = onStall;
+		this.#noProgressMs = options.noProgressMs ?? subprocessStartupNoProgressMs;
+		this.#lastCpu = this.#readCpu();
+		this.#arm();
+	}
+
+	/** Any message the runner sent before `ready` is progress; a later startup stage also moves the stage. */
+	observe(message: KernelToHostMessage): void {
+		if (this.#stopped) return;
+		if (message.type === "status" && message.event.op === "kernel-startup") {
+			const stage = stages.find((candidate) => candidate === message.event.stage);
+			const next = stage === undefined ? -1 : stages.indexOf(stage);
+			if (next > this.#stageIndex) this.#stageIndex = next;
+		}
+		if (message.type === "text" && message.stream === "stderr") {
+			this.#stderrTail = (this.#stderrTail + message.data).slice(-STDERR_TAIL_CHARS);
+		}
+		this.#arm();
+	}
+
+	stop(): void {
+		this.#stopped = true;
+		clearTimeout(this.#timer);
+		this.#timer = undefined;
+	}
+
+	#arm(): void {
+		clearTimeout(this.#timer);
+		this.#timer = setTimeout(() => this.#expire(), this.#noProgressMs);
+	}
+
+	#expire(): void {
+		if (this.#stopped) return;
+		const cpu = this.#readCpu();
+		// Unreadable CPU means busy and idle look the same: never cut a start off on silence alone.
+		// Any change counts, a drop included: a member of the group exited, which is activity.
+		if (cpu === undefined || cpu !== this.#lastCpu) {
+			this.#lastCpu = cpu;
+			this.#arm();
+			return;
+		}
+		this.stop();
+		const stage = stages[this.#stageIndex] ?? "interpreter-launch";
+		const seconds = Math.round(this.#noProgressMs / 1000);
+		const tail = this.#stderrTail.trim();
+		this.#onStall(
+			`${this.#options.label} kernel stalled at ${stage}: no output, stage change or CPU use for ${seconds} s${tail ? `; stderr: ${tail}` : ""}`,
+		);
+	}
+
+	#readCpu(): bigint | undefined {
+		return this.#pid === undefined ? undefined : this.#options.readGroupCpuTime?.(this.#pid);
+	}
+}

package/src/tool/cell-handler.ts

@@ -14,6 +14,7 @@ import { appendSchemaHint } from "../bridges/schema-hint.ts";
 import type { CompletionRequest, CompletionResult } from "../completion/handler.ts";
 import { handleCompletionToolCall } from "../completion/tool-bridge.ts";
 import type { ResolvedCodemodeSettings } from "../config/settings.ts";
+import type { HandleRegistry } from "../handles/handle-registry.ts";
 import type { KernelToolsCapability } from "../kernels/js/kernel-tools-types.ts";
 import {
 	boundToolCallArgs,
@@ -24,6 +25,7 @@ import {
 	type ToolCallCapture,
 	toolCallResultPreview,
 } from "./call-capture.ts";
+import { completionCallOptions, reservedDispatchContext } from "./cell-reserved-dispatch.ts";
 import { CellResultBuilder, type CellState } from "./cell-runtime.ts";
 import { type EvalImageResizer, marshalToolResult, toolResultIsError } from "./image.ts";
 import { upsertStatusEvent } from "./status-events.ts";
@@ -48,6 +50,10 @@ export interface CellBridgeRuntime {
 	readonly imageResizer?: EvalImageResizer;
 	/** This cell's live kernel-tool capability; only a JS kernel has one (#1754). */
 	readonly kernelTools?: KernelToolsCapability;
+	/** The session generation's handle registry behind `wait()` / `handle()` / completion handles. */
+	readonly handles?: HandleRegistry;
+	/** Absolute wall-clock deadline of this cell; a completion handle it creates is bounded by it. */
+	readonly hardDeadlineMs?: number;
 }
 
 export class CellHandler {
@@ -159,17 +165,12 @@ export class CellHandler {
 			await this.#deliverToolReply(
 				message,
 				async () => ({
-					value: await runReservedTool(message.toolName, {
-						callId: message.callId,
-						args: message.args,
-						executeTool: this.#runtime.executeTool,
-						taskToolName: this.#runtime.settings.taskTools.task,
-						taskOutputToolName: this.#runtime.settings.taskTools.output,
-						listTools: this.#runtime.listTools,
-						signal: this.#state.signal,
-						emitStatus: (event) => this.#recordStatus(event),
-						marshalToolResult,
-					}),
+					value: await runReservedTool(
+						message.toolName,
+						reservedDispatchContext(message, this.#runtime, this.#state.signal, (event) =>
+							this.#recordStatus(event),
+						),
+					),
 					toolCallOk: true,
 				}),
 				capture,
@@ -177,13 +178,15 @@ export class CellHandler {
 			return;
 		}
 		if (message.toolName === "completion" && this.#runtime.complete) {
-			const result = await handleCompletionToolCall({
-				message,
-				kernel: this.#kernel,
-				complete: this.#runtime.complete,
-				ctx: this.#runtime.ctx,
-				isActive: () => this.#state.active,
-			});
+			const result = await handleCompletionToolCall(
+				completionCallOptions(
+					message,
+					this.#kernel,
+					this.#runtime,
+					this.#runtime.complete,
+					() => this.#state.active,
+				),
+			);
 			if (!this.#state.active) return;
 			recordToolCall(this.#state.toolCalls, result.ok, capture, undefined, result.ok ? undefined : result.error);
 			this.#resultBuilder.emitUpdate(false);