@code-yeongyu/senpi-codemode 2026.9.5 → 2026.9.7-2

package/src/kernels/py/transport.ts

@@ -8,7 +8,8 @@ import {
 	isKernelToHostMessage,
 	type KernelToHostMessage,
 } from "../../bridge/protocol.ts";
-import { type CodemodeRuntimeAssetEnvironment, resolveCodemodeRuntimeAsset } from "../shared/runtime-asset.ts";
+import { applySessionEnvironment, type SessionEnvironment } from "../session-env.ts";
+import { type CodemodeRuntimeAssetEnvironment, requireCodemodeRuntimeAsset } from "../shared/runtime-asset.ts";
 import {
 	defaultSpawn,
 	hardKill,
@@ -36,6 +37,8 @@ export interface PythonTransportOptions {
 	readonly cwd: string;
 	readonly connection: BridgeConnectionConfig;
 	readonly env?: NodeJS.ProcessEnv;
+	/** Per-session PI_* values merged into the interpreter environment at spawn. */
+	readonly sessionEnv?: SessionEnvironment;
 	readonly startupTimeoutMs: number;
 	readonly onMessage?: (message: KernelToHostMessage) => void;
 	readonly spawnProcess?: KernelSpawnProcess;
@@ -53,7 +56,7 @@ export interface PythonPreludePathOptions extends CodemodeRuntimeAssetEnvironmen
 }
 
 export function resolvePythonPreludePath(options: PythonPreludePathOptions = {}): string {
-	return resolveCodemodeRuntimeAsset(
+	return requireCodemodeRuntimeAsset(
 		options.localPath ?? join(dirname(fileURLToPath(import.meta.url)), "prelude.py"),
 		join("kernels", "py", "prelude.py"),
 		options,
@@ -83,7 +86,12 @@ export class PythonKernelTransport {
 			command: invocation.command,
 			args: [...invocation.args, "-u", scriptPath],
 			cwd: options.cwd,
-			env: { ...process.env, ...options.env, PYTHONUNBUFFERED: "1", PYTHONIOENCODING: "utf-8" },
+			env: {
+				...applySessionEnvironment(process.env, options.sessionEnv),
+				...options.env,
+				PYTHONUNBUFFERED: "1",
+				PYTHONIOENCODING: "utf-8",
+			},
 		};
 		const child = (options.spawnProcess ?? defaultSpawn)(spawnOptions);
 		const transport = new PythonKernelTransport(options, child);

package/src/kernels/rb/kernel.ts

@@ -1,12 +1,15 @@
 import { join } from "node:path";
 import type { BridgeConnectionConfig, KernelToHostMessage } from "../../bridge/protocol.ts";
-import { type CodemodeRuntimeAssetEnvironment, resolveCodemodeRuntimeAsset } from "../shared/runtime-asset.ts";
+import type { SessionEnvironment } from "../session-env.ts";
+import { type CodemodeRuntimeAssetEnvironment, requireCodemodeRuntimeAsset } from "../shared/runtime-asset.ts";
 import { SubprocessKernel, type SubprocessSpawn } from "../shared/subprocess-kernel.ts";
 
 export interface RubyKernelStartOptions {
 	readonly cwd: string;
 	readonly sessionId: string;
 	readonly connection: BridgeConnectionConfig;
+	/** Per-session PI_* values merged into the interpreter environment at spawn. */
+	readonly sessionEnv?: SessionEnvironment;
 	readonly command?: string;
 	readonly spawn?: SubprocessSpawn;
 	readonly onMessage?: (message: KernelToHostMessage) => void;
@@ -17,7 +20,7 @@ export interface RubyRunnerPathOptions extends CodemodeRuntimeAssetEnvironment {
 }
 
 export function resolveRubyRunnerPath(options: RubyRunnerPathOptions = {}): string {
-	return resolveCodemodeRuntimeAsset(
+	return requireCodemodeRuntimeAsset(
 		options.localPath ?? join(import.meta.dirname, "runner.rb"),
 		join("kernels", "rb", "runner.rb"),
 		options,
@@ -31,6 +34,7 @@ export class RubyKernel extends SubprocessKernel {
 			args: [resolveRubyRunnerPath()],
 			cwd: options.cwd,
 			sessionId: options.sessionId,
+			sessionEnv: options.sessionEnv,
 			connection: options.connection,
 			spawn: options.spawn,
 			onMessage: options.onMessage,

package/src/kernels/session-env.ts

@@ -0,0 +1,56 @@
+/**
+ * Session environment exposed to eval kernels and every child they spawn.
+ *
+ * Mirrors the shell-tool session environment contract in the senpi core
+ * (`resolveSpawnContext` in `packages/coding-agent/src/core/tools/bash.ts` and
+ * `docs/environment-variables.md`): the per-session `PI_*` variables are
+ * deleted from the inherited environment first, then set from the active
+ * session, so a stale inherited value never leaks into a kernel child. A child
+ * spawned from an eval cell must see the same session environment a child
+ * spawned from the bash tool sees.
+ */
+export const SESSION_ENVIRONMENT_KEYS = [
+	"PI_SESSION_ID",
+	"PI_SESSION_FILE",
+	"PI_PROVIDER",
+	"PI_MODEL",
+	"PI_REASONING_LEVEL",
+] as const;
+
+/** Resolved per-session values for {@link SESSION_ENVIRONMENT_KEYS}; absent keys stay unset. */
+export type SessionEnvironment = Readonly<Record<string, string>>;
+
+/** Structural slice of `ExtensionContext` the session environment is resolved from. */
+export interface SessionEnvironmentSource {
+	readonly sessionManager: {
+		getSessionId(): string;
+		getSessionFile(): string | undefined;
+	};
+	readonly model?: { readonly provider: string; readonly id: string } | undefined;
+	readonly thinkingLevel?: string | undefined;
+}
+
+export function sessionEnvironmentFrom(source: SessionEnvironmentSource): SessionEnvironment {
+	const env: Record<string, string> = {};
+	env.PI_SESSION_ID = source.sessionManager.getSessionId();
+	const sessionFile = source.sessionManager.getSessionFile();
+	if (sessionFile) env.PI_SESSION_FILE = sessionFile;
+	const model = source.model;
+	if (model) {
+		env.PI_PROVIDER = model.provider;
+		env.PI_MODEL = model.id;
+	}
+	if (source.thinkingLevel) env.PI_REASONING_LEVEL = source.thinkingLevel;
+	return env;
+}
+
+/**
+ * Merges a session environment over a base environment the way the bash tool
+ * does: every {@link SESSION_ENVIRONMENT_KEYS} entry is dropped from `base`
+ * first, then the provided session values are applied.
+ */
+export function applySessionEnvironment(base: NodeJS.ProcessEnv, sessionEnv?: SessionEnvironment): NodeJS.ProcessEnv {
+	const merged: NodeJS.ProcessEnv = { ...base };
+	for (const key of SESSION_ENVIRONMENT_KEYS) delete merged[key];
+	return { ...merged, ...sessionEnv };
+}

package/src/kernels/shared/runtime-asset.ts

@@ -6,26 +6,52 @@ export interface CodemodeRuntimeAssetEnvironment {
 	readonly executablePath?: string;
 }
 
+export class CodemodeRuntimeAssetMissingError extends Error {
+	readonly packageRelativePath: string;
+	readonly localPath: string;
+	readonly sidecarPath: string;
+	readonly executablePath: string;
+
+	constructor(packageRelativePath: string, localPath: string, sidecarPath: string, executablePath: string) {
+		super(
+			`codemode runtime asset ${packageRelativePath} is unavailable: module-relative path ${localPath} is not readable and the codemode sidecar is missing beside the executable ${executablePath} (expected ${sidecarPath}). Ship node_modules/@code-yeongyu/senpi-codemode next to the executable.`,
+		);
+		this.name = "CodemodeRuntimeAssetMissingError";
+		this.packageRelativePath = packageRelativePath;
+		this.localPath = localPath;
+		this.sidecarPath = sidecarPath;
+		this.executablePath = executablePath;
+	}
+}
+
+export function isBunVirtualPath(path: string): boolean {
+	return path.includes("/$bunfs/") || path.includes("~BUN") || path.includes("%7EBUN");
+}
+
+function sidecarPathFor(packageRelativePath: string, executablePath: string): string {
+	return join(dirname(executablePath), "node_modules", "@code-yeongyu", "senpi-codemode", "src", packageRelativePath);
+}
+
+export function requireCodemodeRuntimeAsset(
+	localPath: string,
+	packageRelativePath: string,
+	{ executablePath = process.execPath }: CodemodeRuntimeAssetEnvironment = {},
+): string {
+	const sidecarPath = sidecarPathFor(packageRelativePath, executablePath);
+	if (!isBunVirtualPath(localPath) && existsSync(localPath)) return localPath;
+	if (existsSync(sidecarPath)) return sidecarPath;
+	throw new CodemodeRuntimeAssetMissingError(packageRelativePath, localPath, sidecarPath, executablePath);
+}
+
 export function resolveCodemodeRuntimeAsset(
 	localPath: string,
 	packageRelativePath: string,
 	{ bunVersion = process.versions.bun, executablePath = process.execPath }: CodemodeRuntimeAssetEnvironment = {},
 ): string {
-	if (existsSync(localPath)) {
-		return localPath;
-	}
+	if (existsSync(localPath)) return localPath;
 	if (bunVersion) {
-		const sidecarPath = join(
-			dirname(executablePath),
-			"node_modules",
-			"@code-yeongyu",
-			"senpi-codemode",
-			"src",
-			packageRelativePath,
-		);
-		if (existsSync(sidecarPath)) {
-			return sidecarPath;
-		}
+		const sidecarPath = sidecarPathFor(packageRelativePath, executablePath);
+		if (existsSync(sidecarPath)) return sidecarPath;
 	}
 	return localPath;
 }

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

@@ -1,4 +1,5 @@
 import type { BridgeConnectionConfig, KernelToHostMessage } from "../../bridge/protocol.ts";
+import type { SessionEnvironment } from "../session-env.ts";
 import type { SubprocessSpawn } from "./subprocess-process.ts";
 
 export interface KernelRunInput {
@@ -15,6 +16,8 @@ export interface SubprocessKernelOptions {
 	readonly args: readonly string[];
 	readonly cwd?: string;
 	readonly env?: NodeJS.ProcessEnv;
+	/** Per-session PI_* values merged into the interpreter environment at spawn. */
+	readonly sessionEnv?: SessionEnvironment;
 	readonly sessionId: string;
 	readonly connection: BridgeConnectionConfig;
 	readonly spawn?: SubprocessSpawn;

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

@@ -1,6 +1,7 @@
 import type { HostToKernelMessage, KernelToHostMessage } from "../../bridge/protocol.ts";
 import { decodeBridgeFrame, encodeBridgeFrame, isKernelToHostMessage } from "../../bridge/protocol.ts";
 import type { KernelInterruptHandle } from "../../tool/types.ts";
+import { applySessionEnvironment } from "../session-env.ts";
 import type { KernelResult, KernelRunInput, SubprocessKernelOptions, ToolCallMessage } from "./subprocess-contract.ts";
 import { type SubprocessLike, SubprocessProcess, type SubprocessSpawn, spawnSubprocess } from "./subprocess-process.ts";
 import { SubprocessRunQueue } from "./subprocess-queue.ts";
@@ -133,7 +134,14 @@ export class SubprocessKernel {
 	}
 
 	private spawnProcess(): void {
-		const child = spawnSubprocess(this.options.spawn, this.options);
+		const child = spawnSubprocess(this.options.spawn, {
+			...this.options,
+			env:
+				this.options.env ??
+				(this.options.sessionEnv
+					? applySessionEnvironment(globalThis.process.env, this.options.sessionEnv)
+					: undefined),
+		});
 		const process = new SubprocessProcess(child, {
 			onLine: (source, line) => this.handleLine(source, line),
 			onStderr: (source, data) => this.handleMessage(source, { type: "text", stream: "stderr", data }),

package/src/output/output-meta.ts

@@ -28,12 +28,14 @@ export function resolveSessionArtifactsDir(sessionFile: string | undefined): Ses
 
 export interface TruncationMeta {
 	readonly direction: "head" | "tail" | "middle";
-	readonly truncatedBy: "lines" | "bytes" | "middle";
+	readonly truncatedBy: "lines" | "bytes" | "columns" | "middle";
 	readonly totalLines: number;
 	readonly totalBytes: number;
 	readonly outputLines: number;
 	readonly outputBytes: number;
 	readonly maxBytes?: number;
+	readonly maxColumns?: number;
+	readonly columnTruncatedLines?: number;
 	readonly shownRange?: { readonly start: number; readonly end: number };
 	readonly headRange?: { readonly start: number; readonly end: number };
 	readonly tailRange?: { readonly start: number; readonly end: number };
@@ -72,7 +74,7 @@ export function formatTruncationWarning(meta: TruncationMeta | undefined): strin
 				meta.shownRange !== undefined && meta.shownRange.end >= meta.shownRange.start
 					? `Showing lines ${meta.shownRange.start}-${meta.shownRange.end} of ${meta.totalLines}`
 					: `Showing ${meta.outputLines} of ${meta.totalLines} lines`;
-			if (meta.truncatedBy === "bytes") message += ` (${formatBytes(meta.maxBytes ?? meta.outputBytes)} limit)`;
+			message += formatByteLoss(meta);
 			break;
 		default:
 			return assertNever(meta.direction);
@@ -81,6 +83,28 @@ export function formatTruncationWarning(meta: TruncationMeta | undefined): strin
 	return `[${message}]`;
 }
 
+function formatByteLoss(meta: TruncationMeta): string {
+	const dropped = formatBytes(Math.max(0, meta.totalBytes - meta.outputBytes));
+	switch (meta.truncatedBy) {
+		case "columns": {
+			const clamped = meta.columnTruncatedLines ?? 0;
+			const width = meta.maxColumns === undefined ? "the column cap" : `${meta.maxColumns} columns`;
+			return `; ${clamped} line${clamped === 1 ? "" : "s"} clamped to ${width} (${dropped} dropped)`;
+		}
+		case "bytes":
+			return meta.maxBytes === undefined ? ` (${dropped} dropped)` : ` (${formatBytes(meta.maxBytes)} limit)`;
+		case "lines":
+		case "middle":
+			return "";
+		default:
+			return assertNeverCause(meta.truncatedBy);
+	}
+}
+
+function assertNeverCause(value: never): never {
+	throw new TypeError(`Unhandled truncation cause: ${String(value)}`);
+}
+
 export function stripOutputNotice(text: string, meta: TruncationMeta | undefined): string {
 	const notice = formatTruncationWarning(meta);
 	if (notice === null) return text;

package/src/prompt/eval-prompt.ts

@@ -77,9 +77,9 @@ const EVAL_PROMPT_TEMPLATE = `Run one step of code in a persistent kernel.
 {{#if monitor}}- Start long-running work (build, test run, deploy, or watch) through \`tool.monitor({ command, filter })\`, putting the decisive-line filter inside the same cell, then keep working until its event wakes the turn.{{/if}}
 </eval_first_batching>{{/if}}{{#if styleGpt}}<gpt_eval_dialect>
 GPT eval: compose multi-tool work inside one cell with \`tool.<name>(args)\` and \`parallel(thunks)\`; do not split a planned step into serial tool calls.
-- Long cells detach on timeout and notify on completion; do not poll or re-run them.
+{{#if monitor}}- A wait or a long run (build, test run, deploy, watch) starts through \`tool.monitor({ command, filter })\` in that same cell with the decisive-line filter; its event wakes the turn, so no cell sits on the wait and no child is spawned for it.
+{{/if}}- Long cells detach on timeout and notify on completion; do not poll or re-run them.
 - Filter, join, and aggregate tool results in the cell; return only decision-relevant facts.
-{{#if monitor}}- For long-running build, test run, deploy, or watch work, start \`tool.monitor({ command, filter })\` with the decisive-line filter in the same cell; keep working until its event wakes the turn.{{/if}}
 </gpt_eval_dialect>{{/if}}{{#if styleCodex}}Route multi-call steps through eval: one cell per step, independent lookups dispatched together via \`parallel(thunks)\`; keep work sequential only when one result determines the next action.
 - Loop or comprehend over file sets with \`read()\`/stdlib instead of reading files one call at a time; post-process \`tool.<name>()\` results programmatically — filter, join, aggregate.
 - Wrap failable calls in try/except inside the cell; a failed item degrades only itself. After two distinct failed strategies for the same fact, fall back to direct tool calls.
@@ -102,7 +102,7 @@ Host: {{hostLine}} — cells execute here. Size \`parallel(thunks)\` pools to it
 A cell that outlives the foreground window detaches: it keeps its language kernel busy (another language can continue) and completes as one notification with its value or error and buffered output. Do not re-run a detached cell; read or cancel it with \`eval({ action: "peek", cell_id })\` / \`eval({ action: "stop", cell_id })\`.
 
 {{#if py}}Python runs on a live event loop: use top-level \`await\`; \`asyncio.run(…)\` raises.{{/if}}
-{{#if js}}{{#if jsBun}}JS runs in-process on Bun {{jsVersion}}: top-level \`await\`/\`return\` work; \`Bun.*\` builtins available, including \`new Bun.WebView()\` — a headless browser (navigate/click/evaluate/screenshot) to reach for before \`curl\` or a browser CLI when a page needs JS, a login, or a screenshot.{{#if bunSkillPath}} MUST READ the bun-1-4 skill at {{bunSkillPath}} before your first js cell — its builtins replace the npm packages you would otherwise install.{{/if}}{{else}}JS runs under Node.js worker: top-level \`await\`/\`return\` work; \`fetch\`/\`Buffer\` available.{{/if}}{{/if}}
+{{#if js}}{{#if jsBun}}JS runs in-process on Bun {{jsVersion}}: top-level \`await\`/\`return\` work; \`Bun.*\` builtins available, including \`new Bun.WebView()\` — a headless browser (navigate/click/evaluate/screenshot) to reach for before \`curl\` or a browser CLI when a page needs JS, a login, or a screenshot. Shell out through \`Bun.$\` or \`Bun.spawn\`, never \`Bun.spawnSync\`: a synchronous child blocks the worker, so a stop or timeout then loses every variable.{{#if bunSkillPath}} MUST READ the bun-1-4 skill at {{bunSkillPath}} before your first js cell — its builtins replace the npm packages you would otherwise install.{{/if}}{{else}}JS runs under Node.js worker: top-level \`await\`/\`return\` work; \`fetch\`/\`Buffer\` available.{{/if}}{{/if}}
 {{#if rb}}Ruby: synchronous; helper options are keyword args{{#if spawns}} (e.g. \`output("id", limit: 2)\`){{/if}}; the last expression auto-displays unless it is \`nil\`, an assignment, or a definition (like IRB).{{/if}}
 {{#if jl}}Julia: synchronous; helper options are standard keyword args{{#if spawns}} (e.g. \`output("id", limit=2)\`){{/if}}; the last expression auto-displays unless it is an assignment or a definition (like the Julia REPL).{{/if}}
 On error, fix and re-run only the failing step; a normal error keeps state, while a timeout or stop message says whether the kernel restarted.
@@ -182,7 +182,7 @@ export function buildEvalPrompt(
 		description,
 		promptSnippet: "Run one incremental code cell in a persistent language kernel.",
 		promptGuidelines: [
-			BATCHING_GUIDELINES[style],
+			style === "gpt" && context.monitor === true ? GPT_MONITOR_BATCHING_GUIDELINE : BATCHING_GUIDELINES[style],
 			"Use eval reset only when a language kernel must be wiped; reset is scoped to the selected language.",
 		],
 	};
@@ -191,8 +191,13 @@ export function buildEvalPrompt(
 /**
  * System-prompt guideline per emphasis dialect. The default dialect carries
  * maximum emphasis so unmapped models still batch through eval; the others are
- * tuned to what steers that family reliably.
+ * tuned to what steers that family reliably. The GPT line routes waits to the
+ * subscription when `monitor` is reachable, because a GPT model that reads
+ * "long cells detach" as the way to wait awaits a `--watch` inside a cell.
  */
+const GPT_MONITOR_BATCHING_GUIDELINE =
+	"Use eval to compose tool work in one cell; a wait or a long run starts through `tool.monitor` in that cell, so no cell sits on it and nothing polls.";
+
 const BATCHING_GUIDELINES: Record<EvalEmphasisStyle, string> = {
 	default:
 		"**EVAL FIRST.** Any step needing MORE THAN ONE tool call MUST be ONE eval cell: run independent calls in parallel, wrap risky calls in try/except, and return distilled facts — NEVER a chain of single tool calls.",

package/src/tool/cell-execution.ts

@@ -1,5 +1,5 @@
 import { IdleTimeout, type IdleTimeoutOptions, type TimeoutPauseHandle } from "../timeouts/idle-timeout.ts";
-import type { EvalKernel } from "./types.ts";
+import type { EvalKernel, KernelInterruptHandle } from "./types.ts";
 
 const INTERRUPT_DELIVERY_GRACE_MS = 100;
 
@@ -104,7 +104,8 @@ export class CellExecution {
 		this.#abort(this.#callerSignal.reason);
 	};
 
-	interruptStateRetained: Promise<boolean> | undefined;
+	/** Resolves with the kernel's interrupt handle once the abort reached it; undefined when no kernel was bound. */
+	interruptHandle: Promise<KernelInterruptHandle> | undefined;
 
 	#abort(reason: unknown): void {
 		if (!this.#active) return;
@@ -118,15 +119,12 @@ export class CellExecution {
 			return;
 		}
 		this.#interruptDeadline = setTimeout(() => this.#settleAbort(error), INTERRUPT_DELIVERY_GRACE_MS);
-		void Promise.resolve()
-			.then(async () => {
-				const handle = await kernel.interrupt(error.message);
-				this.interruptStateRetained = handle?.stateRetained;
-			})
-			.then(
-				() => this.#settleAbort(error),
-				(interruptError: unknown) => this.#settleAbort(interruptError),
-			);
+		const handle = Promise.resolve().then(async () => await kernel.interrupt(error.message));
+		this.interruptHandle = handle;
+		void handle.then(
+			() => this.#settleAbort(error),
+			(interruptError: unknown) => this.#settleAbort(interruptError),
+		);
 	}
 
 	#settleAbort(reason: unknown): void {

package/src/tool/detached-cell-contract.ts

@@ -0,0 +1,45 @@
+import type { AgentToolResult } from "@code-yeongyu/senpi";
+import type { WakeSourceState } from "../extension/wake-source-state.ts";
+import type { EvalLanguage, EvalToolDetails } from "./types.ts";
+
+export type EvalDetachedCellState = "running" | "detached" | "completed" | "failed" | "cancelled";
+
+export interface EvalDetachedCellSnapshot {
+	readonly cellId: string;
+	readonly language: EvalLanguage;
+	readonly state: EvalDetachedCellState;
+	readonly outputTail: string;
+	readonly result: AgentToolResult<EvalToolDetails>;
+	readonly stateRetained: boolean | undefined;
+	/** Kernel-supplied detail about the interrupt outcome, e.g. an abandoned blocked worker. */
+	readonly interruptNote?: string;
+	/** Set only when the wall-clock kill deadline ended this cell. */
+	readonly hardLimitSeconds?: number;
+}
+
+export interface EvalDetachedCellNotification {
+	readonly cellId: string;
+	readonly content: string;
+}
+
+export interface EvalDetachedCellNotifier {
+	notify(cells: readonly EvalDetachedCellNotification[]): void;
+}
+
+export interface EvalDetachedCellStatusEntry {
+	readonly cellId: string;
+	readonly language: EvalLanguage;
+	readonly summary?: string;
+	readonly startedAtMs: number;
+}
+
+export interface EvalDetachedCellManagerOptions {
+	readonly artifactsDir?: string;
+	readonly notifier?: EvalDetachedCellNotifier;
+	/** Wall-clock kill deadline in seconds; defaults to the bash-parity 1800s. */
+	readonly hardLimitSeconds?: number;
+	readonly onStatusChange?: (entries: readonly EvalDetachedCellStatusEntry[]) => void;
+	/** Receives a full per-source liveness snapshot on every detached-cell transition; used by the goal builtin. */
+	readonly onWakeSourceState?: (state: WakeSourceState) => void;
+	readonly now?: () => number;
+}

package/src/tool/detached-cell-manager.ts

@@ -1,6 +1,12 @@
 import type { AgentToolResult } from "@code-yeongyu/senpi";
 import { DEFAULT_HARD_LIMIT_SECONDS } from "../config/settings.ts";
-import { SENPI_CODEMODE_WAKE_SOURCE, type WakeSourceState } from "../extension/wake-source-state.ts";
+import type { WakeSourceState } from "../extension/wake-source-state.ts";
+import type {
+	EvalDetachedCellManagerOptions,
+	EvalDetachedCellSnapshot,
+	EvalDetachedCellState,
+	EvalDetachedCellStatusEntry,
+} from "./detached-cell-contract.ts";
 import { detachedNotificationSpillPath } from "./detached-cell-notification.ts";
 import { currentDetachedResult, detachedErrorResult, snapshotDetachedCell } from "./detached-cell-snapshot.ts";
 import {
@@ -8,10 +14,18 @@ import {
 	allowsDetachedCellTransition,
 	detachedCellIsActive,
 } from "./detached-cell-state.ts";
+import { detachedStatusEntries, detachedWakeSourceState } from "./detached-cell-status.ts";
 import { DetachedNotificationQueue } from "./detached-notification-queue.ts";
 import type { EvalKernel, EvalLanguage, EvalToolDetails, EvalToolInput } from "./types.ts";
 
-export type EvalDetachedCellState = "running" | "detached" | "completed" | "failed" | "cancelled";
+export type {
+	EvalDetachedCellManagerOptions,
+	EvalDetachedCellNotification,
+	EvalDetachedCellNotifier,
+	EvalDetachedCellSnapshot,
+	EvalDetachedCellState,
+	EvalDetachedCellStatusEntry,
+} from "./detached-cell-contract.ts";
 
 type LiveResultProvider = () => AgentToolResult<EvalToolDetails>;
 
@@ -26,6 +40,9 @@ type ManagedCell = {
 	wasDetached: boolean;
 	kernel: EvalKernel | undefined;
 	stateRetained: boolean | undefined;
+	interruptNote: string | undefined;
+	/** Holds the completion notification until the interrupt has reported whether kernel state survived. */
+	interruptOutcome: PromiseWithResolvers<void> | undefined;
 	liveResult: LiveResultProvider | undefined;
 	terminalResult: AgentToolResult<EvalToolDetails> | undefined;
 	notificationQueued: boolean;
@@ -35,44 +52,6 @@ type ManagedCell = {
 	onHardLimit: ((error: Error) => void) | undefined;
 };
 
-export interface EvalDetachedCellSnapshot {
-	readonly cellId: string;
-	readonly language: EvalLanguage;
-	readonly state: EvalDetachedCellState;
-	readonly outputTail: string;
-	readonly result: AgentToolResult<EvalToolDetails>;
-	readonly stateRetained: boolean | undefined;
-	/** Set only when the wall-clock kill deadline ended this cell. */
-	readonly hardLimitSeconds?: number;
-}
-
-export interface EvalDetachedCellNotification {
-	readonly cellId: string;
-	readonly content: string;
-}
-
-export interface EvalDetachedCellNotifier {
-	notify(cells: readonly EvalDetachedCellNotification[]): void;
-}
-
-export interface EvalDetachedCellStatusEntry {
-	readonly cellId: string;
-	readonly language: EvalLanguage;
-	readonly summary?: string;
-	readonly startedAtMs: number;
-}
-
-export interface EvalDetachedCellManagerOptions {
-	readonly artifactsDir?: string;
-	readonly notifier?: EvalDetachedCellNotifier;
-	/** Wall-clock kill deadline in seconds; defaults to the bash-parity 1800s. */
-	readonly hardLimitSeconds?: number;
-	readonly onStatusChange?: (entries: readonly EvalDetachedCellStatusEntry[]) => void;
-	/** Receives a full per-source liveness snapshot on every detached-cell transition; used by the goal builtin. */
-	readonly onWakeSourceState?: (state: WakeSourceState) => void;
-	readonly now?: () => number;
-}
-
 export function hardLimitError(cellId: string, hardLimitSeconds: number): Error {
 	const error = new Error(`Eval cell ${cellId} was killed at the ${hardLimitSeconds}s hard limit.`);
 	error.name = "TimeoutError";
@@ -114,6 +93,8 @@ export class EvalDetachedCellManager {
 			wasDetached: false,
 			kernel: undefined,
 			stateRetained: undefined,
+			interruptNote: undefined,
+			interruptOutcome: undefined,
 			liveResult: undefined,
 			terminalResult: undefined,
 			notificationQueued: false,
@@ -162,13 +143,7 @@ export class EvalDetachedCellManager {
 
 	async stop(cellId: string, reason = "Stopped detached eval cell"): Promise<EvalDetachedCellSnapshot> {
 		const cell = this.#get(cellId);
-		if (cell.state === "detached") {
-			const claimed = this.#settle(cell, "cancelled", currentDetachedResult(cell));
-			if (claimed && cell.kernel !== undefined) {
-				const handle = await cell.kernel.interrupt(reason);
-				cell.stateRetained = await handle.stateRetained;
-			}
-		}
+		if (cell.state === "detached") await this.#cancel(cell, reason);
 		return this.#snapshot(cell);
 	}
 
@@ -221,7 +196,10 @@ export class EvalDetachedCellManager {
 			if (!cell.notificationQueued) {
 				cell.notificationQueued = true;
 				this.#notificationQueue.enqueue({
-					snapshot: () => this.#snapshot(cell),
+					snapshot: async () => {
+						await cell.interruptOutcome?.promise;
+						return this.#snapshot(cell);
+					},
 					spillPath: cell.spillPath,
 				});
 			}
@@ -250,40 +228,34 @@ export class EvalDetachedCellManager {
 		const foreground = cell.state === "running" && cell.onHardLimit !== undefined;
 		cell.hardLimited = true;
 		const error = hardLimitError(cell.cellId, cell.hardLimitSeconds);
-		if (!this.#settle(cell, "cancelled", currentDetachedResult(cell))) return;
 		if (foreground) {
-			cell.onHardLimit?.(error);
+			if (this.#settle(cell, "cancelled", currentDetachedResult(cell))) cell.onHardLimit?.(error);
 			return;
 		}
-		if (cell.kernel === undefined) return;
-		const handle = await cell.kernel.interrupt(error.message);
-		cell.stateRetained = await handle.stateRetained;
+		await this.#cancel(cell, error.message);
+	}
+
+	async #cancel(cell: ManagedCell, reason: string): Promise<void> {
+		const outcome = Promise.withResolvers<void>();
+		cell.interruptOutcome = outcome;
+		try {
+			if (!this.#settle(cell, "cancelled", currentDetachedResult(cell)) || cell.kernel === undefined) return;
+			const handle = await cell.kernel.interrupt(reason);
+			cell.interruptNote = handle.note;
+			cell.stateRetained = await handle.stateRetained;
+		} finally {
+			outcome.resolve();
+		}
 	}
 
 	#emitStatus(): void {
 		const liveCells = [...this.#detachedByLanguage.values()];
-		this.#onStatusChange?.(
-			liveCells.map((cell) => ({
-				cellId: cell.cellId,
-				language: cell.input.language,
-				startedAtMs: cell.startedAtMs,
-				...(cell.input.summary === undefined ? {} : { summary: cell.input.summary }),
-			})),
-		);
+		this.#onStatusChange?.(detachedStatusEntries(liveCells));
 		this.#emitWakeSourceState(liveCells);
 	}
 
 	#emitWakeSourceState(liveCells: readonly ManagedCell[]): void {
-		this.#onWakeSourceState?.({
-			source: SENPI_CODEMODE_WAKE_SOURCE,
-			activeCount: liveCells.length,
-			items: liveCells.map((cell) => ({
-				id: cell.cellId,
-				description:
-					cell.input.summary === undefined || cell.input.summary.length === 0 ? cell.cellId : cell.input.summary,
-				startedAtMs: cell.startedAtMs,
-			})),
-		});
+		this.#onWakeSourceState?.(detachedWakeSourceState(liveCells));
 	}
 
 	#snapshot(cell: ManagedCell): EvalDetachedCellSnapshot {

package/src/tool/detached-cell-notification.ts

@@ -1,6 +1,7 @@
 import { mkdir, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import type { EvalDetachedCellNotification, EvalDetachedCellSnapshot } from "./detached-cell-manager.ts";
+import { interruptionStateNote, unknownInterruptionStateNote } from "./interrupt-note.ts";
 
 const NOTIFICATION_TAIL_BYTES = 512;
 
@@ -74,11 +75,9 @@ function outcomeOf(cell: EvalDetachedCellSnapshot): string {
 }
 
 function stateNoteOf(cell: EvalDetachedCellSnapshot): string {
-	if (cell.state === "cancelled" && cell.language === "js")
-		return "JavaScript worker was restarted; VM state was lost.";
-	if (cell.state === "cancelled" && cell.language === "py")
-		return "Python kernel was interrupted; its existing variables are preserved.";
-	return "Kernel state updated - variables are available to the next eval cell.";
+	if (cell.state !== "cancelled") return "Kernel state updated - variables are available to the next eval cell.";
+	const note = interruptionStateNote(cell.language, cell.stateRetained) ?? unknownInterruptionStateNote(cell.language);
+	return cell.interruptNote === undefined ? note : `${note} ${cell.interruptNote.trim()}`;
 }
 
 function safeCellId(cellId: string): string {

package/src/tool/detached-cell-snapshot.ts

@@ -10,6 +10,7 @@ export interface DetachedCellResultSource {
 	state: EvalDetachedCellState;
 	kernel: EvalKernel | undefined;
 	stateRetained: boolean | undefined;
+	interruptNote?: string | undefined;
 	liveResult: (() => AgentToolResult<EvalToolDetails>) | undefined;
 	terminalResult: AgentToolResult<EvalToolDetails> | undefined;
 	hardLimited?: boolean;
@@ -26,6 +27,7 @@ export function snapshotDetachedCell(cell: DetachedCellResultSource, nowMs: numb
 		outputTail: detachedOutputTail(result),
 		result,
 		stateRetained: cell.stateRetained,
+		...(cell.interruptNote === undefined ? {} : { interruptNote: cell.interruptNote }),
 		...(cell.hardLimited === true && cell.hardLimitSeconds !== undefined
 			? { hardLimitSeconds: cell.hardLimitSeconds }
 			: {}),