pi-crew 0.9.67 → 0.9.68

package/CHANGELOG.md

@@ -2,6 +2,54 @@
 
 > **Note:** `atomic-write-v2.ts` / `AtomicWriter` mentioned in historical entries below was consolidated into `atomic-write.ts` as of v0.9.42. This changelog is preserved as historical record — the migration was completed (the v2 class was never adopted; v1 won on simplicity + symlink-safety + link+unlink atomicity). See `docs/migration/atomic-write-v2-migration.md` for the decision rationale.
 
+## [0.9.68] — RLM fixes after deep-review verification (2026-08-12)
+
+Fixes from `docs/rlm-deep-review-2026-08-12.md` (verified) +
+`docs/rlm-fixes-implementation-plan.md`. Each code part loop-reviewed (3
+parallel reviewers: security/correctness/tests, read-only) before merge here.
+
+### Fixes
+- **P1 — global shadow poisoning** (`src/runtime/scratchpad/guest.ts`):
+  `PROTECTED_GLOBALS` + `resetProtectedGlobals()` register live Node globals
+  into the namespace/`INTERNAL_BINDINGS`. Closes both poisoning paths: restore
+  (re-install overwrites revived shadow) and in-session (reset at cell start —
+  shadow stays local to the cell that created it). Silent corruption (e.g.
+  `const process='x'` making `process.env` undefined) is gone. 8 regression
+  tests in `test/unit/runtime/scratchpad/guest-global-shadow.test.ts`.
+- **P2 — scratchpad adoption lever** (`src/agents/agent-config.ts`): new
+  `PI_CREW_SCRATCHPAD_DEMOTE_BASH=1` flag. When on + a role has scratchpad
+  enabled, `resolveToolPolicy` removes `bash` (allowlist filter + denylist add)
+  so the model reaches for the `sh()` binding instead — the documented root
+  cause of 0 adoption. Default off (zero behavior change); scoped to
+  scratchpad-armed roles (executor/verifier/test-engineer) via
+  `isScratchpadEnabledForRole` (S-6 read-only gate + F6 kill-switch honored).
+  10 tests in `test/unit/scratchpad-demote-bash.test.ts`.
+- **P4 — host_request protocol doc** (`src/runtime/scratchpad/protocol.ts`):
+  the `host_request` type is now documented as reserved for the future host
+  bridge (§5.2F), not yet wired (no handler).
+- **P5 — version drift** (`package.json`): 4 pi devDeps `^0.83.0` → `^0.84.0`
+  (installed runtime is 0.84.1).
+- **P6 — scratchpad stack-trace sourcemap** (`src/runtime/scratchpad/transform.ts`
+  + `guest.ts`): `transformCell` now returns a `lineMap` (body line → source
+  line) built from esbuild `sourcemap:'inline'` + a hand-rolled VLQ decoder
+  (no dependency) + import pre-rewrite tracking + splice line counting. Guest
+  `remapStackLines` remaps the V8 `<anonymous>:N` frame back to the cell's
+  original source line. Only real `    at ` frames are remapped (a crafted
+  error message containing `<anonymous>:N:C)` is left byte-identical). Known
+  cosmetic limitation: multi-line type annotations map to the esbuild collapse
+  point. 10 tests in `test/unit/runtime/scratchpad/scratchpad-sourcemap.test.ts`.
+
+### Removed
+- **P3 — dead HMAC crypto deleted.** `src/runtime/scratchpad/snapshot-hmac.ts`
+  (167 lines, 11 tests) + its test file removed. The threat it mitigated
+  (v8.deserialize tamper) is double-conditional (0 scratchpad adoption +
+  same-uid store both hold today); wiring (ROADMAP R1-4) was premature and
+  blocked on 3 unresolved design questions. ADR Superseded; design retained
+  for clean re-add if conditions ever hold. ROADMAP R1-4 / R2-2 marked removed.
+
+### Deferred (needs design)
+- *None remaining.* (P6 was the last deferred item; it shipped — see Fixes.)
+
 ## [0.9.67] — RLM/scratchpad adoption batch (I1–I7) (2026-08-11)
 
 First shippable slice of `improvement-plan-2026-08-11.md` — the scratchpad was

package/dist/index.mjs

@@ -11755,10 +11755,19 @@ function uniqueToolMerge(...lists) {
 function resolveToolPolicy(agent, role) {
   const roleConfig = role ? getToolConfig(role) : {};
   const explicitTools = agent.source === "builtin" ? roleConfig.tools ?? agent.tools : agent.tools ?? roleConfig.tools;
-  const tools = agent.loadMode === "lean" && agent.defaultTools?.length ? uniqueToolMerge(explicitTools, agent.defaultTools) : explicitTools;
-  const excludeTools = uniqueToolMerge(roleConfig.excludeTools, agent.disallowedTools);
+  let tools = agent.loadMode === "lean" && agent.defaultTools?.length ? uniqueToolMerge(explicitTools, agent.defaultTools) : explicitTools;
+  let excludeTools = uniqueToolMerge(roleConfig.excludeTools, agent.disallowedTools);
+  if (shouldDemoteBashForScratchpad(role, agent)) {
+    tools = tools ? tools.filter((t2) => t2 !== "bash") : tools;
+    excludeTools = uniqueToolMerge(excludeTools, ["bash"]);
+  }
   return { tools, excludeTools };
 }
+function shouldDemoteBashForScratchpad(role, agent) {
+  if (process.env.PI_CREW_SCRATCHPAD_DEMOTE_BASH !== "1") return false;
+  if (!role) return false;
+  return isScratchpadEnabledForRole(role, { scratchpad: agent.scratchpad });
+}
 var BUILTIN_TOOL_NAMES;
 var init_agent_config = __esm({
   "src/agents/agent-config.ts"() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-crew",
-  "version": "0.9.67",
+  "version": "0.9.68",
   "description": "Pi extension for coordinated AI teams, workflows, worktrees, and async task orchestration",
   "author": "baphuongna",
   "license": "MIT",
@@ -67,7 +67,8 @@
   ],
   "scripts": {
     "check": "npm run ci",
-    "ci": "npm run typecheck && npm run lint && npm run format:check && npm run check:conflict-markers && npm run check:decision-drift && npm run check:event-types && npm run check:lazy-imports && npm run check:bundle-staleness && npm run build:bundle && npm run check:bundle-size && npm run test:bundle && npm test && npm pack --dry-run",
+    "ci": "npm run check:lockfile-sync && npm run typecheck && npm run lint && npm run format:check && npm run check:conflict-markers && npm run check:decision-drift && npm run check:event-types && npm run check:lazy-imports && npm run check:bundle-staleness && npm run build:bundle && npm run check:bundle-size && npm run test:bundle && npm test && npm pack --dry-run",
+    "check:lockfile-sync": "node scripts/check-lockfile-sync.mjs",
     "check:lazy-imports": "node scripts/check-lazy-imports.mjs",
     "check:bundle-staleness": "node scripts/check-bundle-staleness.mjs",
     "check:bundle-size": "node scripts/check-bundle-size.mjs",
@@ -136,10 +137,10 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.5.3",
-    "@earendil-works/pi-agent-core": "^0.83.0",
-    "@earendil-works/pi-ai": "^0.83.0",
-    "@earendil-works/pi-coding-agent": "^0.83.0",
-    "@earendil-works/pi-tui": "^0.83.0",
+    "@earendil-works/pi-agent-core": "^0.84.0",
+    "@earendil-works/pi-ai": "^0.84.0",
+    "@earendil-works/pi-coding-agent": "^0.84.0",
+    "@earendil-works/pi-tui": "^0.84.0",
     "@types/node": "^25.9.5",
     "tsx": "^4.23.0",
     "typescript": "^7.0.2"

package/src/agents/agent-config.ts

@@ -1,5 +1,5 @@
 import type { RoleToolConfig } from "../config/role-tools.ts";
-import { getToolConfig } from "../config/role-tools.ts";
+import { getToolConfig, isScratchpadEnabledForRole } from "../config/role-tools.ts";
 
 /**
  * F1 (v0.7.9): canonical built-in tool name list. Used by `parseToolsField`
@@ -162,24 +162,45 @@ export function resolveToolPolicy(agent: AgentConfig, role?: string): ResolvedTo
 	const roleConfig = role ? getToolConfig(role) : {};
 	// allowlist: source-aware precedence (see doc above).
 	const explicitTools = agent.source === "builtin" ? (roleConfig.tools ?? agent.tools) : (agent.tools ?? roleConfig.tools);
-	// L5: when the agent opts into `loadMode: "lean"` AND provides a
-	// non-empty `defaultTools` list, merge that list into the resolved
-	// allowlist. The merge is additive (union, dedup, order-preserving) so
-	// the existing source-aware precedence is preserved and a lean agent
-	// gets a focused-but-non-empty tool set. Signal flow:
-	//   agent YAML frontmatter (loadMode, defaultTools)
-	//     → parsed into AgentConfig
-	//     → resolveToolPolicy(agent, role) here
-	//     → policy.tools returned to buildPiWorkerArgs
-	//     → `args.push("--tools", policy.tools.join(","))` in pi-args.ts
-	//     → child pi process sees the merged allowlist
-	const tools =
+	let tools =
 		agent.loadMode === "lean" && agent.defaultTools?.length ? uniqueToolMerge(explicitTools, agent.defaultTools) : explicitTools;
 	// denylist: additive merge of role excludeTools + agent disallowedTools.
-	const excludeTools = uniqueToolMerge(roleConfig.excludeTools, agent.disallowedTools);
+	let excludeTools = uniqueToolMerge(roleConfig.excludeTools, agent.disallowedTools);
+	// P2 (scratchpad adoption lever, rlm-deep-review-2026-08-12.md §5.1A):
+	// when scratchpad is armed for this role AND the operator opted in via
+	// PI_CREW_SCRATCHPAD_DEMOTE_BASH=1, remove `bash` from the tool surface so
+	// the model reaches for `sh()` inside scratchpad cells (structured value
+	// reuse) instead of `bash` (which always wins by default — the documented
+	// root cause of 0 scratchpad adoption). Gated behind a flag because it
+	// changes the tool surface the model sees (behavioral risk). The model
+	// keeps read/edit/write/ls/grep/find; shell ops must go via `sh()`.
+	if (shouldDemoteBashForScratchpad(role, agent)) {
+		tools = tools ? tools.filter((t) => t !== "bash") : tools;
+		excludeTools = uniqueToolMerge(excludeTools, ["bash"]);
+	}
 	return { tools, excludeTools };
 }
 
+/**
+ * P2: should `bash` be demoted (removed) for a scratchpad-armed role?
+ *
+ * True only when BOTH hold:
+ *  (a) the role has scratchpad enabled (so the model still has a way to run
+ *      shell commands — via the `sh()` binding inside scratchpad cells);
+ *  (b) the operator opted in via `PI_CREW_SCRATCHPAD_DEMOTE_BASH=1`.
+ *
+ * Default off → zero behavior change (existing adoption stays at 0). On → the
+ * lever to break 0-adoption without full tool collapse. This is read-only
+ * config logic; the actual tool-surface change happens in `resolveToolPolicy`
+ * above and flows to BOTH spawn paths (child-pi `--tools`/`--exclude-tools` and
+ * live-session filterActiveTools) via the unified policy.
+ */
+function shouldDemoteBashForScratchpad(role: string | undefined, agent: AgentConfig): boolean {
+	if (process.env.PI_CREW_SCRATCHPAD_DEMOTE_BASH !== "1") return false;
+	if (!role) return false;
+	return isScratchpadEnabledForRole(role, { scratchpad: agent.scratchpad });
+}
+
 /**
  * Build agent session options including role-based tool restrictions.
  * @param agent - The agent configuration

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 };
 }

package/src/runtime/scratchpad/snapshot-hmac.ts

@@ -1,167 +0,0 @@
-/**
- * Snapshot HMAC helper — opt-in integrity for scratchpad snapshots.
- *
- * ⚠️ NOT WIRED — see ADR 2026-08-10, Phase 2. This module is NOT connected to
- * the snapshot write/read path (`guest.ts` restore uses plain `v8.deserialize`,
- * `snapshotNamespace` writes unsigned payloads). Zero production call sites.
- * The 11 unit tests here are green but exercise the helper in isolation.
- * Wire-or-delete decision: docs/improvement-plan-2026-08-11.md §4 J1.
- *
- * Closes the E.2 gap declared in docs/improvement-plan-2026-08-09.md and
- * src/runtime/scratchpad/README.md:120 ("v8.deserialize of restore content
- * is unauthenticated (no HMAC)"). The threat model — a same-uid attacker
- * plants a crafted V8 blob at the snapshot path to run deserialize gadgets
- * in the guest — does not cross the existing same-uid boundary, but HMAC
- * hardening is required before snapshots ever land in a shared/networked
- * store.
- *
- * Migration window (see docs/decisions/2026-08-10-scratchpad-snapshot-hmac.md):
- *
- *   Phase 1 (this module): HMAC sign-on-write + verify-on-read are OPT-IN
- *     via PI_CREW_SNAPSHOT_HMAC_KEY. When the key is unset, behaviour is
- *     unchanged (snapshots remain unsigned). When the key is set, writes
- *     attach a signature and reads verify it; an unsigned/failed snapshot
- *     is ACCEPTED with a warning so existing snapshots remain readable.
- *   Phase 2 (after one release): unsigned snapshots are REJECTED when the
- *     key is set (configurable via PI_CREW_SNAPSHOT_HMAC_STRICT=1).
- *   Phase 3 (after snapshots move to a shared store): the key becomes
- *     required and unsigned snapshots are always rejected.
- *
- * Wire-up into the actual write/read paths is intentionally deferred to a
- * follow-up that audits the snapshot envelope format (V8 base64 vs raw
- * bytes) and the writeArtifact redaction interaction. See ADR for the plan.
- */
-import { createHmac, timingSafeEqual } from "node:crypto";
-
-/**
- * Env var holding the HMAC secret. When unset, HMAC is disabled (Phase 0
- * behaviour — snapshots unsigned). When set, sign-on-write and
- * verify-on-read are enabled.
- */
-export const SNAPSHOT_HMAC_KEY_ENV = "PI_CREW_SNAPSHOT_HMAC_KEY";
-
-/**
- * Opt-in strict mode (Phase 2): when the key is set AND this is "1",
- * unsigned or signature-mismatched snapshots are REJECTED on read instead
- * of accepted with a warning.
- */
-export const SNAPSHOT_HMAC_STRICT_ENV = "PI_CREW_SNAPSHOT_HMAC_STRICT";
-
-/**
- * Header prefix for an inline signature. When snapshots are signed, the
- * signature is prepended to the blob as `PI_CREW_SIG=<hex>\n` so a single
- * read yields both the signature and the payload. (Sidecar files would
- * require writeArtifact coordination that the envelope format does not
- * currently support.)
- */
-export const SNAPSHOT_SIG_PREFIX = "PI_CREW_SIG=";
-
-export function getSnapshotHmacKey(env: NodeJS.ProcessEnv = process.env): Buffer | undefined {
-	const raw = env[SNAPSHOT_HMAC_KEY_ENV];
-	if (!raw) return undefined;
-	// Accept hex-encoded keys directly; otherwise encode the string as utf8.
-	// A key shorter than 32 bytes is rejected to prevent trivial brute-force.
-	const buf = /^[0-9a-fA-F]+$/.test(raw) && raw.length % 2 === 0 ? Buffer.from(raw, "hex") : Buffer.from(raw, "utf8");
-	if (buf.length < 32) {
-		throw new Error(
-			`${SNAPSHOT_HMAC_KEY_ENV} must be at least 32 bytes (got ${buf.length}); use a longer key or generate one with: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"`,
-		);
-	}
-	return buf;
-}
-
-export function isSnapshotHmacStrict(env: NodeJS.ProcessEnv = process.env): boolean {
-	return env[SNAPSHOT_HMAC_STRICT_ENV] === "1" || env[SNAPSHOT_HMAC_STRICT_ENV] === "true";
-}
-
-/**
- * Compute the HMAC-SHA256 signature of `content` under `key`. Returns a
- * lowercase hex string.
- */
-export function signSnapshot(content: Buffer | string, key: Buffer): string {
-	return createHmac("sha256", key).update(content).digest("hex");
-}
-
-/**
- * Constant-time signature comparison. Both signatures must be lowercase
- * hex of the same length; anything else returns false without throwing.
- */
-export function snapshotSignatureMatches(content: Buffer | string, signature: string, key: Buffer): boolean {
-	const expected = signSnapshot(content, key);
-	const a = Buffer.from(expected);
-	const b = Buffer.from(signature);
-	if (a.length !== b.length) return false;
-	return timingSafeEqual(a, b);
-}
-
-/**
- * Outcome of {@link verifySnapshotPayload}. Callers decide how to react
- * based on the strict-mode flag.
- */
-export type SnapshotVerifyOutcome =
-	| { kind: "unsigned"; strict: boolean }
-	| { kind: "verified" }
-	| { kind: "mismatch"; strict: boolean }
-	| { kind: "hmac-disabled" };
-
-/**
- * Verify a snapshot payload that may or may not carry an inline signature.
- *
- * @param payload The raw bytes read from disk (possibly including the
- *   `PI_CREW_SIG=<hex>\n` prefix).
- * @param key The HMAC key, or `undefined` when HMAC is disabled.
- * @param strict When true, unsigned/mismatched payloads are reported as
- *   rejectable. When false (the Phase 1 default), the caller is expected
- *   to accept the payload with a warning.
- */
-export function verifySnapshotPayload(payload: Buffer, key: Buffer | undefined, strict: boolean): SnapshotVerifyOutcome {
-	if (!key) return { kind: "hmac-disabled" };
-	const prefixStr = SNAPSHOT_SIG_PREFIX;
-	if (payload.length < prefixStr.length + 1 || payload.subarray(0, prefixStr.length).toString("utf8") !== prefixStr) {
-		return { kind: "unsigned", strict };
-	}
-	const newlineIdx = payload.indexOf(0x0a, prefixStr.length);
-	if (newlineIdx < 0) return { kind: "unsigned", strict };
-	const sigHex = payload.subarray(prefixStr.length, newlineIdx).toString("utf8");
-	const body = payload.subarray(newlineIdx + 1);
-	return snapshotSignatureMatches(body, sigHex, key) ? { kind: "verified" } : { kind: "mismatch", strict };
-}
-
-/**
- * Strip the inline signature prefix and return the bare payload. Returns
- * the original buffer when no prefix is present. Used by read paths that
- * have already called {@link verifySnapshotPayload} and decided to accept.
- */
-export function stripSnapshotSignature(payload: Buffer): Buffer {
-	if (payload.length < SNAPSHOT_SIG_PREFIX.length) return payload;
-	if (payload.subarray(0, SNAPSHOT_SIG_PREFIX.length).toString("utf8") !== SNAPSHOT_SIG_PREFIX) return payload;
-	const newlineIdx = payload.indexOf(0x0a, SNAPSHOT_SIG_PREFIX.length);
-	if (newlineIdx < 0) return payload;
-	return payload.subarray(newlineIdx + 1);
-}
-
-/**
- * Attach an inline signature to a payload. Returns a new buffer shaped as
- * `PI_CREW_SIG=<hex>\n<payload>`. Used by write paths that have HMAC
- * enabled.
- */
-export function attachSnapshotSignature(payload: Buffer, key: Buffer): Buffer {
-	const sig = signSnapshot(payload, key);
-	return Buffer.concat([Buffer.from(`${SNAPSHOT_SIG_PREFIX}${sig}\n`, "utf8"), payload]);
-}
-
-/**
- * Should the caller reject the snapshot based on the verify outcome?
- * Centralises the strict-vs-migration decision so callers stay simple.
- */
-export function shouldRejectSnapshot(outcome: SnapshotVerifyOutcome): boolean {
-	switch (outcome.kind) {
-		case "hmac-disabled":
-			return false;
-		case "verified":
-			return false;
-		case "unsigned":
-		case "mismatch":
-			return outcome.strict;
-	}
-}