pi-crew 0.9.67 → 0.10.1

package/src/runtime/scheduling/run-coalesced-task-group.ts

@@ -2,7 +2,7 @@ import type { AgentConfig } from "../../agents/agent-config.ts";
 import type { CrewReliabilityConfig, CrewRuntimeConfig } from "../../config/types.ts";
 import { appendEventAsync } from "../../state/event-log/event-log.ts";
 import { writeArtifact } from "../../state/stores/artifact-store.ts";
-import { saveRunTasksAsync, updateRunStatus } from "../../state/stores/state-store.ts";
+import { loadRunManifestById, saveRunTasksAsync, updateRunStatus } from "../../state/stores/state-store.ts";
 import type { TeamRunManifest, TeamTaskState } from "../../state/types.ts";
 import type { WorkflowStep } from "../../workflows/workflow-config.ts";
 import { createWorkerHeartbeat, touchWorkerHeartbeat } from "../heartbeat/worker-heartbeat.ts";
@@ -115,17 +115,12 @@ export async function runCoalescedTaskGroup(input: CoalescedTaskGroupInput): Pro
 			heartbeatInFlight = true;
 			heartbeatPromise = (async () => {
 				try {
-					updatedTasks = updatedTasks.map((t) => {
-						if (!taskIds.includes(t.id)) return t;
-						// FIND-06 belt-and-suspenders: never replace terminal state or its
-						// resultArtifact with a heartbeat-only snapshot.
-						if (t.status === "completed" || t.status === "failed" || t.status === "cancelled") return t;
-						return {
-							...t,
-							heartbeat: touchWorkerHeartbeat(t.heartbeat ?? createWorkerHeartbeat(t.id), { alive: true }),
-						};
-					});
-					await saveRunTasksAsync(manifest, updatedTasks);
+					// R15-3: persist heartbeats for ONLY this group's tasks via a fresh
+					// disk read. The old closure `updatedTasks` is a dispatch-time
+					// snapshot of the FULL task array — a sibling cancelled on disk after
+					// dispatch could be un-cancelled by a late heartbeat save (the map
+					// only mutated group tasks, but the SAVE wrote the whole stale array).
+					await persistGroupHeartbeats(manifest, taskIds);
 				} catch {
 					// Run may have been pruned mid-dispatch — best-effort only.
 				} finally {
@@ -134,9 +129,12 @@ export async function runCoalescedTaskGroup(input: CoalescedTaskGroupInput): Pro
 					// save was in flight, re-write the (now-terminal) updatedTasks so
 					// our late snapshot cannot leave stale pre-terminal state on disk.
 					// Runs after our own save resolves, so it always lands last.
+					// R15-3: the repair now fresh-reads disk and re-applies ONLY the
+					// group's terminal state — the old full-array write could resurrect
+					// a sibling cancelled on disk (same flaw as the heartbeat save).
 					if (finalWriteStarted) {
 						try {
-							await saveRunTasksAsync(manifest, updatedTasks);
+							await repairGroupTerminalWrite(manifest, taskIds, updatedTasks);
 						} catch {
 							// best-effort repair — same swallow policy as the heartbeat.
 						}
@@ -298,6 +296,59 @@ export async function runCoalescedTaskGroup(input: CoalescedTaskGroupInput): Pro
 	return { manifest: updatedManifest, tasks: updatedTasks, taskIds, rawOutput, success };
 }
 
+/**
+ * R15-3: heartbeat save scoped to this coalesced group only.
+ *
+ * Previously the heartbeat wrote the dispatch-time closure `updatedTasks` —
+ * the FULL task array including sibling tasks outside this group. A sibling
+ * cancelled on disk after dispatch (external cancel / reconciler) could be
+ * un-cancelled ("resurrected") by a late heartbeat save, because the map only
+ * mutated group tasks but the SAVE wrote the whole stale array. Fix: fresh
+ * re-read tasks from disk (loadRunManifestById — the established fresh-read
+ * pattern used by team-runner) and write back ONLY the group's own task ids
+ * with heartbeats touched; sibling tasks are preserved untouched from the
+ * fresh disk read. Keeps the FIND-06 'never replace terminal state' guard.
+ */
+async function persistGroupHeartbeats(manifest: TeamRunManifest, taskIds: string[]): Promise<void> {
+	const fresh = loadRunManifestById(manifest.cwd, manifest.runId);
+	if (!fresh) return; // run pruned mid-dispatch — best-effort only.
+	const merged = fresh.tasks.map((t) => {
+		if (!taskIds.includes(t.id)) return t; // sibling tasks: preserved untouched.
+		// FIND-06 belt-and-suspenders: never replace terminal state or its
+		// resultArtifact with a heartbeat-only snapshot.
+		if (t.status === "completed" || t.status === "failed" || t.status === "cancelled") return t;
+		return {
+			...t,
+			heartbeat: touchWorkerHeartbeat(t.heartbeat ?? createWorkerHeartbeat(t.id), { alive: true }),
+		};
+	});
+	await saveRunTasksAsync(manifest, merged);
+}
+
+/**
+ * R15-3: FIND-06 P1 repair — re-apply the group's terminal state after a late
+ * heartbeat save may have landed last. Fresh-reads disk so sibling tasks are
+ * preserved untouched; only the group's own terminal state from `updatedTasks`
+ * is re-applied, and a disk-terminal group task is never flipped (same
+ * belt-and-suspenders guard as the heartbeat).
+ */
+async function repairGroupTerminalWrite(manifest: TeamRunManifest, taskIds: string[], updatedTasks: TeamTaskState[]): Promise<void> {
+	const fresh = loadRunManifestById(manifest.cwd, manifest.runId);
+	if (!fresh) return; // run pruned mid-dispatch — best-effort only.
+	const groupById = new Map(updatedTasks.map((t) => [t.id, t] as const));
+	const merged = fresh.tasks.map((t) => {
+		if (!taskIds.includes(t.id)) return t; // sibling tasks: preserved untouched.
+		if (t.status === "completed" || t.status === "failed" || t.status === "cancelled") return t;
+		return groupById.get(t.id) ?? t;
+	});
+	await saveRunTasksAsync(manifest, merged);
+}
+
+/** @internal 3.5 R15-3 test export — exercise the heartbeat/repair writes directly. */
+export const __test__persistGroupHeartbeats = persistGroupHeartbeats;
+/** @internal 3.5 R15-3 test export — exercise the terminal repair write directly. */
+export const __test__repairGroupTerminalWrite = repairGroupTerminalWrite;
+
 async function buildCoalescedPrompt(
 	manifest: TeamRunManifest,
 	step: WorkflowStep,

package/src/runtime/scheduling/task-graph-scheduler.ts

@@ -48,16 +48,6 @@ export function buildTaskGraphIndex(tasks: TeamTaskState[]): TaskGraphIndex {
 	return fresh;
 }
 
-/** Test/diagnostic helper — invalidate the WeakMap-backed index cache. Not
- *  used by production code paths; the WeakMap self-invalidates when a tasks
- *  array goes out of scope. Provided for parity with `clearStablePrefixCache`. */
-export function clearTaskGraphIndexCache(): void {
-	// WeakMap has no `.clear()`; rely on GC. Exposed as a no-op stub so callers
-	// that import `clearStablePrefixCache` (also a no-op stub for symmetry) can
-	// adopt a parallel API if needed in the future. Documented as no-op rather
-	// than removed so the API stays discoverable.
-}
-
 function taskById(tasks: TeamTaskState[]): Map<string, TeamTaskState> {
 	return new Map(tasks.map((task) => [task.id, task]));
 }

package/src/runtime/scratchpad/README.md

@@ -124,11 +124,16 @@ attempt N+1 worker (scratchpad-lifecycle.ts)
   token), so this does not cross the existing boundary. An HMAC over the payload
   is a Phase 2.5/3 hardening if artifacts ever land in a shared location.
 
-> ⚠️ **NOT WIRED (2026-08-11):** `src/runtime/scratchpad/snapshot-hmac.ts` is an
-> unconnected helper — zero production call sites, 11 green unit tests in
-> isolation. Wire-or-delete decision in `docs/improvement-plan-2026-08-11.md`
-> §4 J1. Until then the note above (v8.deserialize unauthenticated) is exactly
-> how the code behaves.
+> **REMOVED (2026-08-12):** `src/runtime/scratchpad/snapshot-hmac.ts` and its
+> test were deleted. Decision (P3 of `docs/rlm-fixes-implementation-plan.md`):
+> the HMAC threat is double-conditional — it only materializes when scratchpad
+> has adoption (>0 cells; today: 0/83 runs) AND snapshots move to a
+> shared/networked store (today: same-uid dev-machine). Hardening a
+> 0-adoption surface that is itself at risk of removal (decision gate §3.3)
+> is premature. The design is fully recorded in ADR
+> `docs/decisions/2026-08-10-scratchpad-snapshot-hmac.md` (Superseded), so it
+> can be re-added cleanly if/when both conditions hold. Until then the note
+> below (v8.deserialize unauthenticated) remains exactly how the code behaves.
 - **Secret-at-rest under a benign key name** persists as base64 for the run's
   retention (structural redaction is key-name based, best-effort). A sanitized-
   namespace policy is a Phase 2.5 concern.

package/src/runtime/scratchpad/guest.ts

@@ -188,6 +188,49 @@ console.trace = consoleErr;
 
 const INTERNAL_BINDINGS = new Map<string, unknown>();
 
+/**
+ * Protected Node globals — must never be persistently shadowed by a cell.
+ *
+ * Because the scope proxy's `get` trap checks the namespace BEFORE globalThis,
+ * a cell writing `const process = 'poisoned'` (transformed to a namespace
+ * assignment) would otherwise poison EVERY later cell in the same engine
+ * (the namespace is a module-level singleton) AND survive snapshot→restore
+ * (a serializable shadow revives). Result: silent corruption — e.g.
+ * `typeof process.env` becomes 'undefined' with no error.
+ *
+ * We register the LIVE global for each protected name in INTERNAL_BINDINGS +
+ * the namespace, so (a) restore's re-install overwrites any revived shadow,
+ * and (b) each cell starts with the real global. Within-cell shadowing still
+ * works (the cell's own write wins for that cell only); it just cannot leak
+ * to other cells or across restarts. Verified: probe reproduced the bug
+ * pre-fix; see test/unit/runtime/scratchpad/guest-global-shadow.test.ts.
+ */
+const PROTECTED_GLOBALS: ReadonlyArray<string> = [
+	"process",
+	"Buffer",
+	"console",
+	"setTimeout",
+	"clearTimeout",
+	"setInterval",
+	"clearInterval",
+	"setImmediate",
+	"clearImmediate",
+	"queueMicrotask",
+	"structuredClone",
+	"AbortController",
+	"globalThis",
+];
+
+function resetProtectedGlobals(): void {
+	const g = globalThis as Record<string, unknown>;
+	for (const name of PROTECTED_GLOBALS) {
+		const live = g[name];
+		if (live === undefined) continue;
+		INTERNAL_BINDINGS.set(name, live);
+		namespace[name] = live;
+	}
+}
+
 /** Pattern-12 nullish guard: refuse undefined/null BEFORE spawning. */
 function assertShellArgNotNullish(name: string, value: unknown): void {
 	if (value === undefined || value === null) {
@@ -235,6 +278,9 @@ function installBootstrapBindings(): void {
 	// serialization, and so cells can call `sh(...)` directly.
 	INTERNAL_BINDINGS.set("sh", sh);
 	namespace.sh = sh;
+	// Overwrite any protected-global shadow (e.g. a revived `process='x'` from
+	// restore) with the live global — fixes the global shadow poisoning bug.
+	resetProtectedGlobals();
 }
 
 installBootstrapBindings();
@@ -246,14 +292,69 @@ const AsyncFunction = (async () => {}).constructor as new (...args: string[]) =>
 
 const liveCells = new Map<string, CellContext>();
 
+// ── P6: remap transformed error-stack lines back to the cell's source ───────
+// V8 reports a thrown line as `N = bodyLine + 2` (1-based) — the AsyncFunction
+// wrapper adds 2 prefix lines (the anonymous function line + the `with (...)`
+// line) before the cell body. `lineMap` (from transformCell) maps body lines
+// that RECEIVED A REPLACEMENT back to the source line the model wrote. Lines
+// between replacements (unreplaced spans — e.g. a bare `throw`) are identity:
+// sourceLine = entry.sourceLine + (bodyLine - entry.bodyLine), using the
+// nearest replacement entry at or before the body line.
+//
+// SECURITY/robustness (P6 review finding): only lines that look like a real
+// V8 frame (`    at ... <anonymous>:N:C)`) are remapped. The `Error: <message>`
+// line and any cell text containing `<anonymous>:N:C)` (e.g. an error message
+// that echoes code) must be left byte-identical — a crafted message must never
+// get its numbers rewritten.
+function remapStackLines(stack: string, lineMap: { sourceLine: number; bodyLine: number }[]): string[] {
+	const lines = stack.split("\n");
+	const sorted = [...lineMap].sort((a, b) => a.bodyLine - b.bodyLine);
+	return lines.map((line) => {
+		// Real V8 frame only: `    at <anything> <anonymous>:N:C)` — anchored to
+		// the leading frame prefix and a parenthesized trailing position. The
+		// message line (`Error: ...`) does not start with `    at `, so it is
+		// never matched; a crafted message containing `<anonymous>:N:C)` is
+		// likewise safe because it lacks the frame prefix.
+		const m = line.match(/^\s+at .*<anonymous>:(\d+):(\d+)\)/);
+		if (!m) return line;
+		const reported = Number(m[1]);
+		const bodyLine = reported - 2; // wrapper prefix offset (verified by probe)
+		// nearest replacement entry at or before bodyLine (lower bound)
+		let lo = 0;
+		let hi = sorted.length - 1;
+		let entry: { sourceLine: number; bodyLine: number } | undefined;
+		while (lo <= hi) {
+			const mid = (lo + hi) >> 1;
+			if (sorted[mid].bodyLine <= bodyLine) {
+				entry = sorted[mid];
+				lo = mid + 1;
+			} else {
+				hi = mid - 1;
+			}
+		}
+		if (!entry) return line; // before any replacement — leave as-is
+		const sourceLine = entry.sourceLine + (bodyLine - entry.bodyLine);
+		const col = m[2];
+		return line.replace(/<anonymous>:\d+:\d+/, `<anonymous>:${sourceLine}:${col}`);
+	});
+}
+
 async function runCell(cellId: string, code: string): Promise<void> {
 	const ctx = makeCellContext(cellId);
 	activeCell = ctx;
 	liveCells.set(cellId, ctx);
+	// Reset protected globals so a prior cell's shadow (e.g. `const process='x'`)
+	// cannot poison this cell — shadowing stays local to the cell that did it
+	// (the namespace is a module-level singleton shared across cells).
+	resetProtectedGlobals();
 
 	let done: GuestToHostMessage;
+	// P6: lineMap from transformCell is needed in BOTH try (to build the
+	// wrapper) and catch (to remap the error stack), so hoist it here.
+	let lineMap: { sourceLine: number; bodyLine: number }[] = [];
 	try {
-		const { body } = transformCell(code, { ctxName: CTX_NAME });
+		const { body, lineMap: lm } = transformCell(code, { ctxName: CTX_NAME });
+		lineMap = lm;
 		// Sloppy-mode wrapper so `with` is legal (AsyncFunction bodies are always
 		// sloppy, even inside a strict ESM strip-types module); async for
 		// top-level await.
@@ -271,7 +372,7 @@ async function runCell(cellId: string, code: string): Promise<void> {
 			type: "done",
 			cellId,
 			status: ctx.aborted ? "aborted" : "error",
-			error: { name: err.name, message: err.message, stack: (err.stack ?? "").split("\n") },
+			error: { name: err.name, message: err.message, stack: remapStackLines(err.stack ?? "", lineMap) },
 		};
 	} finally {
 		if (activeCell === ctx) activeCell = undefined;

package/src/runtime/scratchpad/protocol.ts

@@ -45,7 +45,19 @@ export interface GuestToHost {
 		error?: { name: string; message: string; stack: string[] };
 	};
 	pong: { type: "pong"; id: string };
-	host_request: { type: "host_request"; id: string; requestType: string; payload: Record<string, unknown> };
+	host_request: {
+		// RESERVED for future host bridge (rlm-deep-review-2026-08-12.md §5.2F /
+		// J2): guest-side cells would request host services (tools.read,
+		// tools.grep) so data enters the namespace WITHOUT crossing the
+		// transcript — pi-rlm's core token-saving value proposition. Declared
+		// here so the protocol type is stable, but NOT YET WIRED: engine.ts and
+		// guest.ts have no host_request dispatcher/handler. Blocked on scratchpad
+		// adoption > 0 (do not add a host execution surface nobody calls).
+		type: "host_request";
+		id: string;
+		requestType: string;
+		payload: Record<string, unknown>;
+	};
 	snapshot_result: {
 		type: "snapshot_result";
 		id: string;

package/src/runtime/scratchpad/transform.ts

@@ -31,6 +31,15 @@ export interface TransformedCell {
 	body: string;
 	/** Top-level names this cell binds into the namespace. */
 	declaredNames: string[];
+	/**
+	 * P6: line-based position map — for each body line (1-based), the
+	 * corresponding SOURCE line (1-based) the model wrote. Used to remap the
+	 * V8-reported error line (relative to `body`) back to the cell's original
+	 * line so stack traces point at the source the user wrote, not the
+	 * transformed body. Built WITHOUT a source-map dependency by tracking
+	 * replacement newline shifts against the source (acorn `locations`).
+	 */
+	lineMap: { sourceLine: number; bodyLine: number }[];
 }
 
 export interface TransformOptions {
@@ -41,8 +50,16 @@ export interface TransformOptions {
 // esbuild's transform strips types but never drops side-effect-free trailing
 // expressions (no DCE in transform mode) — the exact thing we capture as the
 // cell result.
-function stripTypes(code: string): string {
-	return transformSync(code, { loader: "ts" }).code;
+// P6: `sourcemap: 'inline'` so we can map the stripped `js` lines back to the
+// `rewritten` (pre-strip) lines — esbuild does NOT preserve line numbers
+// across type stripping (probe: 7 input lines → 5 output lines). The inline
+// sourcemap is stripped from the output (it would otherwise leak into the cell
+// body as a trailing comment); we only keep the decoded line map.
+function stripTypes(code: string): { code: string; lineMap: number[] } {
+	const out = transformSync(code, { loader: "ts", sourcemap: "inline" });
+	const lineMap = esbuildLineMap(out.code);
+	const codeWithoutMap = out.code.replace(/\/\/# sourceMappingURL=data:application\/json;base64,[A-Za-z0-9+/=]+\s*$/, "");
+	return { code: codeWithoutMap, lineMap };
 }
 
 // ── top-level import extraction ──────────────────────────────────────────────
@@ -271,14 +288,147 @@ function variableReplacement(decl: VariableDeclaration, source: string): string
 	return statements.join(" ");
 }
 
+// ── P6: line-based position map ─────────────────────────────────────────────
+// V8 reports a cell error's line as 1-based relative to the TRANSFORMED `body`.
+// The model wrote `code`; between them sit 3 transforms:
+//   1. import pre-rewrite (acorn)      — collapses multi-line imports to 1 line
+//   2. esbuild strip-types             — collapses type annotations/signatures
+//   3. declaration → assignment + trailing-expr capture — may add/remove lines
+// We build a map { sourceLine (1-based, in `code`) → bodyLine (1-based) } by
+// tracking line deltas across each stage with acorn `locations` + newline
+// counts. No source-map dependency (probe: esbuild strip-types does NOT
+// preserve lines — 7→5 — so a naive single-layer sourcemap would be wrong).
+
+function countNewlines(s: string): number {
+	let n = 0;
+	for (let i = 0; i < s.length; i++) if (s.charCodeAt(i) === 10) n++;
+	return n;
+}
+
+/** 1-based line of `pos` (char offset) in `text`. */
+function lineAt(text: string, pos: number): number {
+	let line = 1;
+	for (let i = 0; i < pos && i < text.length; i++) if (text.charCodeAt(i) === 10) line++;
+	return line;
+}
+
+// ── P6: esbuild inline sourcemap → line map (js → rewritten) ───────────────
+// esbuild `sourcemap: 'inline'` emits a base64 VLQ sourcemap whose `mappings`
+// field encodes, per generated line, segments mapping back to source
+// positions. We only need LINE fidelity (column is overkill for the bug), so
+// we decode each generated line's first segment's source line. VLQ is the
+// standard base64-variable-length encoding (no dependency needed).
+
+const BASE64: string = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+const VLQ: Map<string, number> = new Map([...BASE64].map((c, i) => [c, i]));
+
+function decodeVlqSegment(segment: string): number[] {
+	const values: number[] = [];
+	let shift = 0;
+	let value = 0;
+	for (let i = 0; i < segment.length; i++) {
+		const digit = VLQ.get(segment[i]);
+		if (digit === undefined) break;
+		value |= (digit & 31) << shift;
+		if (digit & 32) {
+			shift += 5;
+		} else {
+			values.push(value & 1 ? -(value >>> 1) : value >>> 1);
+			value = 0;
+			shift = 0;
+		}
+	}
+	return values;
+}
+
+/**
+ * Decode an esbuild inline sourcemap's `mappings` into an array where
+ * `lineMapGenerated[generatedLine-1]` = the source LINE (1-based) that
+ * generated line originates from (first segment per generated line; falls back
+ * to the previous mapped line for continuation lines).
+ */
+function esbuildLineMap(codeWithInlineMap: string): number[] {
+	const m = codeWithInlineMap.match(/\/\/# sourceMappingURL=data:application\/json;base64,([A-Za-z0-9+/=]+)/);
+	if (!m) return [];
+	let sm: { mappings?: string };
+	try {
+		sm = JSON.parse(Buffer.from(m[1], "base64").toString("utf8")) as { mappings?: string };
+	} catch {
+		return [];
+	}
+	if (!sm.mappings) return [];
+	const result: number[] = [];
+	let srcLine = 1;
+	let lastSrcLine = 1;
+	for (const genLine of sm.mappings.split(";")) {
+		const segs = genLine.split(",").filter(Boolean);
+		if (segs.length > 0) {
+			const vals = decodeVlqSegment(segs[0]);
+			// values: [genColDelta, srcIdxDelta, srcLineDelta, srcColDelta, ...]
+			if (vals.length >= 3) {
+				srcLine += vals[2];
+				lastSrcLine = srcLine;
+			}
+		}
+		result.push(lastSrcLine);
+	}
+	return result;
+}
+
+/**
+ * Build a `code`-line → `js`-line map across the import pre-rewrite.
+ * For each import replacement, its `code` span [codeStart, codeEnd] collapses
+ * to `js` lines [jsStart, jsEnd] (usually 1). Lines outside any replacement
+ * are identity-shifted by the cumulative delta.
+ */
+function buildImportLineMap(
+	code: string,
+	rewritten: string,
+	importSpans: { codeStart: number; codeEnd: number; jsStart: number; jsEnd: number }[],
+): (src: number) => number {
+	if (importSpans.length === 0) return (src) => src;
+	// P6 (final): map a `rewritten` (post-import) LINE to the original `code`
+	// line. `rewritten` = code with each import statement replaced by its
+	// (usually 1-line) dynamic-import fragment. We walk both strings tracking
+	// newline counts: between imports the line numbers advance identically;
+	// inside an import span, all its code lines map to the replacement's first
+	// rewritten line (collapsed).
+	const rewrittenLines: string[] = rewritten.split("\n");
+	const codeLines: string[] = code.split("\n");
+	const map = new Map<number, number>(); // rewrittenLine → codeLine (1-based)
+	let codeIdx = 1;
+	let rewIdx = 1;
+	for (const span of importSpans) {
+		// Advance both to the span start, emitting identity mapping for the
+		// untouched lines between the previous span end and this span start.
+		const spanStartCodeLine = lineAt(code, span.codeStart);
+		const spanStartRewLine = lineAt(rewritten, span.jsStart);
+		for (; codeIdx < spanStartCodeLine && rewIdx < spanStartRewLine; codeIdx++, rewIdx++) {
+			map.set(rewIdx, codeIdx);
+		}
+		// Lines inside the import span (in code) collapse to the replacement's
+		// single starting rewritten line.
+		const spanEndCodeLine = lineAt(code, span.codeEnd);
+		for (; codeIdx <= spanEndCodeLine; codeIdx++) {
+			map.set(spanStartRewLine, spanStartCodeLine);
+		}
+		rewIdx = spanStartRewLine + 1;
+	}
+	// Tail: identity from wherever we stopped.
+	for (; rewIdx <= rewrittenLines.length; rewIdx++, codeIdx++) {
+		map.set(rewIdx, Math.min(codeIdx, codeLines.length));
+	}
+	return (rewLine: number) => {
+		const mapped = map.get(rewLine);
+		return mapped ?? Math.min(rewLine, codeLines.length);
+	};
+}
+
 export function transformCell(code: string, options: TransformOptions = {}): TransformedCell {
 	const ctxName = options.ctxName ?? "__ctx";
-
-	// Top-level imports are rewritten into awaited dynamic imports BEFORE type
-	// stripping: esbuild elides unused imports, and the reference behaviour
-	// binds every imported name into the namespace so it persists across cells.
 	let importDeclared: string[] = [];
 	let rewritten = code;
+	const importSpans: { codeStart: number; codeEnd: number; jsStart: number; jsEnd: number }[] = [];
 	try {
 		const tokens = lexTopLevel(code);
 		const imports = findImportStatements(tokens);
@@ -286,11 +436,21 @@ export function transformCell(code: string, options: TransformOptions = {}): Tra
 			importDeclared = [];
 			const pieces: string[] = [];
 			let cursor = 0;
+			let jsCursor = 0;
 			for (const stmt of imports) {
-				pieces.push(rewritten.slice(cursor, stmt.start));
+				const pre = rewritten.slice(cursor, stmt.start);
+				pieces.push(pre);
+				jsCursor += pre.length;
 				const rewrite = rewriteImport(code, stmt, tokens);
 				importDeclared.push(...rewrite.declaredNames);
 				pieces.push(rewrite.replacement);
+				importSpans.push({
+					codeStart: stmt.start,
+					codeEnd: stmt.end,
+					jsStart: jsCursor,
+					jsEnd: jsCursor + rewrite.replacement.length - 1,
+				});
+				jsCursor += rewrite.replacement.length;
 				cursor = stmt.end;
 			}
 			pieces.push(rewritten.slice(cursor));
@@ -301,8 +461,15 @@ export function transformCell(code: string, options: TransformOptions = {}): Tra
 		// the pre-rewrite; type stripping below surfaces the error.
 	}
 
-	const js = stripTypes(rewritten);
-	const program: Program = parse(js, { ecmaVersion: "latest", sourceType: "module", allowAwaitOutsideFunction: true });
+	const { code: js, lineMap: esbLineMap } = stripTypes(rewritten);
+	const rewToCode = buildImportLineMap(code, rewritten, importSpans);
+	const program: Program = parse(js, {
+		ecmaVersion: "latest",
+		sourceType: "module",
+		allowAwaitOutsideFunction: true,
+		// P6: locations needed to know each top-level node's source lines.
+		locations: true,
+	});
 
 	const declaredNames: string[] = [];
 	const replacements: { start: number; end: number; text: string }[] = [];
@@ -353,11 +520,38 @@ export function transformCell(code: string, options: TransformOptions = {}): Tra
 	replacements.sort((a, b) => a.start - b.start);
 	let body = "";
 	let cursor = 0;
+	// P6: build bodyLine → sourceLine map while splicing. `body` is what V8
+	// reports error lines against; `js` is the esbuild-stripped source; the map
+	// composes: bodyLine → jsLine (via newline deltas) → rewrittenLine (via
+	// esbuild inline sourcemap) → codeLine (via import pre-rewrite).
+	const lineMap: { sourceLine: number; bodyLine: number }[] = [];
+	let bodyLine = 1;
+	let jsLine = 1;
+	// jsLineOfBodyStart maps the js line at each body boundary; we track the
+	// cumulative js-line delta as body lines are emitted.
 	for (const replacement of replacements) {
-		body += js.slice(cursor, replacement.start) + replacement.text;
+		const pre = js.slice(cursor, replacement.start);
+		body += pre;
+		bodyLine += countNewlines(pre);
+		jsLine += countNewlines(pre);
+		// The replacement's first body line maps from the js line at its start.
+		const repJsStartLine = lineAt(js, replacement.start);
+		// Source line = compose: js → rewritten (esbuild) → code (imports).
+		const rewLine = esbLineMap.length > 0 ? esbLineMap[Math.min(repJsStartLine - 1, esbLineMap.length - 1)] : repJsStartLine;
+		const srcLine = rewToCode(rewLine);
+		lineMap.push({ sourceLine: srcLine, bodyLine: bodyLine });
+		body += replacement.text;
+		bodyLine += countNewlines(replacement.text);
+		// js line after the replacement: replacements are in js coordinate, so
+		// jsLine advances by the replacement's text newlines too.
+		jsLine += countNewlines(replacement.text);
 		cursor = replacement.end;
 	}
-	body += js.slice(cursor);
+	const tail = js.slice(cursor);
+	body += tail;
+	bodyLine += countNewlines(tail);
+	// Any body line not covered by a replacement maps identity.
+	lineMap.sort((a, b) => a.bodyLine - b.bodyLine);
 
-	return { body, declaredNames: [...new Set([...importDeclared, ...declaredNames])] };
+	return { body, declaredNames: [...new Set([...importDeclared, ...declaredNames])], lineMap };
 }