@gajae-code/coding-agent 0.18.11 → 0.19.0

package/src/eval/py/runner.py

@@ -29,6 +29,7 @@ import asyncio
 import ast
 import base64
 import builtins
+import codecs
 import inspect
 import io
 import json
@@ -49,9 +50,14 @@ from typing import Any, Callable
 # Frame writer
 # ---------------------------------------------------------------------------
 
-_RAW_STDOUT = sys.__stdout__
 _RAW_STDERR = sys.__stderr__
 _OUT_LOCK = threading.Lock()
+_PROTO_FD: int | None = None
+_CAP_LOCK = threading.Lock()
+_FLUSH_EVENT = threading.Event()
+_FLUSH_TOKEN: bytes | None = None
+_CAPTURED = b""
+_CAPTURE_DECODER = codecs.getincrementaldecoder("utf-8")(errors="replace")
 
 
 def _json_default(o: Any) -> Any:
@@ -61,13 +67,141 @@ def _json_default(o: Any) -> Any:
         return f"<unrepr {type(o).__name__}>"
 
 
+def _write_all(fd: int, data: bytes) -> None:
+    view = memoryview(data)
+    while len(view):
+        written = os.write(fd, view)
+        if written <= 0:
+            raise OSError(0, "protocol write returned no bytes")
+        view = view[written:]
+
+
 def _emit(frame: dict) -> None:
     """Serialize a frame and write it to the host as a single NDJSON line."""
-    line = json.dumps(frame, ensure_ascii=False, default=_json_default)
+    payload = (json.dumps(frame, ensure_ascii=False, default=_json_default) + "\n").encode("utf-8")
+    fd = _PROTO_FD if _PROTO_FD is not None else 1
     with _OUT_LOCK:
-        _RAW_STDOUT.write(line)
-        _RAW_STDOUT.write("\n")
-        _RAW_STDOUT.flush()
+        _write_all(fd, payload)
+
+
+def _token_suffix_len(buf: bytes, token: bytes) -> int:
+    max_n = min(len(buf), len(token) - 1)
+    for size in range(max_n, 0, -1):
+        if buf.endswith(token[:size]):
+            return size
+    return 0
+
+
+def _take_captured_locked() -> tuple[list[bytes], bool]:
+    """Split captured fd-1 bytes. A flush token is a delimiter, not output."""
+    global _CAPTURED, _FLUSH_TOKEN
+    pieces: list[bytes] = []
+    flushed = False
+    while True:
+        token = _FLUSH_TOKEN
+        if token is None:
+            if _CAPTURED:
+                pieces.append(_CAPTURED)
+                _CAPTURED = b""
+            return pieces, flushed
+        idx = _CAPTURED.find(token)
+        if idx < 0:
+            keep = _token_suffix_len(_CAPTURED, token)
+            if len(_CAPTURED) > keep:
+                pieces.append(_CAPTURED[: len(_CAPTURED) - keep])
+                _CAPTURED = _CAPTURED[-keep:] if keep else b""
+            return pieces, flushed
+        if idx:
+            pieces.append(_CAPTURED[:idx])
+        _CAPTURED = _CAPTURED[idx + len(token) :]
+        _FLUSH_TOKEN = None
+        flushed = True
+
+
+def _publish_captured(pieces: list[bytes], flushed: bool) -> None:
+    global _CAPTURE_DECODER
+    for piece in pieces:
+        text = _CAPTURE_DECODER.decode(piece)
+        if text:
+            _forward_captured_stdout(text)
+    if not flushed:
+        return
+    tail = _CAPTURE_DECODER.decode(b"", final=True)
+    if tail:
+        _forward_captured_stdout(tail)
+    _CAPTURE_DECODER = codecs.getincrementaldecoder("utf-8")(errors="replace")
+
+
+def _forward_captured_stdout(text: str) -> None:
+    rid = _STATE.current_id
+    if not text:
+        return
+    if rid is None:
+        _RAW_STDERR.write(text)
+        _RAW_STDERR.flush()
+        return
+    _emit({"type": "stdout", "id": rid, "data": text})
+
+
+def _pump_captured_stdout(read_fd: int) -> None:
+    global _CAPTURED
+    while True:
+        try:
+            chunk = os.read(read_fd, 65536)
+        except OSError:
+            return
+        if not chunk:
+            return
+        with _CAP_LOCK:
+            _CAPTURED += chunk
+            pieces, flushed = _take_captured_locked()
+        _publish_captured(pieces, flushed)
+        if flushed:
+            _FLUSH_EVENT.set()
+
+
+def _capture_user_stdout() -> None:
+    """Move the host pipe off fd 1 so raw user writes are cell output."""
+    global _PROTO_FD
+    if _PROTO_FD is not None:
+        return
+    try:
+        sys.__stdout__.flush()
+    except Exception:
+        pass
+    proto = os.dup(1)
+    os.set_inheritable(proto, False)
+    _PROTO_FD = proto
+    read_fd, write_fd = os.pipe()
+    os.set_inheritable(read_fd, False)
+    os.dup2(write_fd, 1, inheritable=True)
+    os.close(write_fd)
+    threading.Thread(
+        target=_pump_captured_stdout,
+        args=(read_fd,),
+        name="gjc-stdout-capture",
+        daemon=True,
+    ).start()
+
+
+def _flush_captured_stdout() -> None:
+    if _PROTO_FD is None:
+        return
+    token = b"\0gjcfd1:" + os.urandom(8).hex().encode("ascii") + b"\0"
+    with _CAP_LOCK:
+        global _FLUSH_TOKEN
+        _FLUSH_EVENT.clear()
+        _FLUSH_TOKEN = token
+    _write_all(1, token)
+    if _FLUSH_EVENT.wait(5):
+        return
+    with _CAP_LOCK:
+        if _FLUSH_TOKEN == token:
+            _FLUSH_TOKEN = None
+            pieces, flushed = _take_captured_locked()
+        else:
+            pieces, flushed = [], False
+    _publish_captured(pieces, flushed)
 
 
 # ---------------------------------------------------------------------------
@@ -902,6 +1036,10 @@ def _handle_request(req: dict) -> None:
             _flush_matplotlib_figures()
         except Exception:
             pass
+        try:
+            _flush_captured_stdout()
+        except Exception:
+            pass
 
     _emit({
         "type": "done",
@@ -930,6 +1068,7 @@ def _emit_error(rid: str, exc: BaseException) -> None:
 
 
 def main() -> None:
+    _capture_user_stdout()
     sys.stdout = _StreamProxy("stdout")
     sys.stderr = _StreamProxy("stderr")
     _install_idle_sigint()

package/src/eval/py/runtime.ts

@@ -7,8 +7,9 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { $env, $which, getPythonEnvDir, WhichCachePolicy } from "@gajae-code/utils";
+import { $env, $which, getPythonEnvDir, relativePathEscapesRoot, WhichCachePolicy } from "@gajae-code/utils";
 import { withFileLock } from "../../config/file-lock";
+import { isProjectControlledPath } from "../../lsp/path-trust";
 
 export const RLM_MANAGED_PYTHON_PACKAGES: readonly string[] = ["numpy", "pandas", "matplotlib", "polars"];
 
@@ -133,6 +134,47 @@ function resolvePythonCandidateInVenv(venvPath: string): { venvPath: string; pyt
 	return { venvPath, pythonPath, binDir };
 }
 
+/**
+ * A workspace `.venv` or `venv` directory is repository content. Use it only when
+ * it is a real virtualenv (`pyvenv.cfg`) whose interpreter file resolves outside
+ * the project. An in-tree script or binary is not an interpreter.
+ *
+ * True when `candidate` is `root` or a descendant after `path.resolve`.
+ * A name such as `..payload` stays inside. Only `..` and a parent segment escape.
+ */
+export function workspacePathContained(root: string, candidate: string): boolean {
+	const normalize = (value: string): string => {
+		const resolved = path.resolve(value);
+		return process.platform === "win32" ? resolved.toLowerCase() : resolved;
+	};
+	return !relativePathEscapesRoot(path.relative(normalize(root), normalize(candidate)));
+}
+
+function isAutoDetectedWorkspaceVenv(candidate: string, cwd: string): boolean {
+	try {
+		if (!fs.statSync(path.join(candidate, "pyvenv.cfg")).isFile()) return false;
+	} catch {
+		return false;
+	}
+	let canonicalPython: string;
+	try {
+		canonicalPython = fs.realpathSync(resolvePythonCandidateInVenv(candidate).pythonPath);
+	} catch {
+		return false;
+	}
+	// HOME stops project-root discovery, so a workspace that is the home directory
+	// is not project-controlled. Refuse an interpreter that still resolves inside
+	// cwd, including a file whose name is `..payload`.
+	let canonicalCwd = path.resolve(cwd);
+	try {
+		canonicalCwd = fs.realpathSync(cwd);
+	} catch {
+		// Missing cwd keeps the resolved path.
+	}
+	if (workspacePathContained(canonicalCwd, canonicalPython)) return false;
+	return !isProjectControlledPath(canonicalPython, cwd);
+}
+
 function resolveManagedPythonCandidate(): { venvPath: string; pythonPath: string; binDir: string } {
 	return resolvePythonCandidateInVenv(resolveGlobalManagedPythonEnv());
 }
@@ -197,9 +239,7 @@ export function resolveVenvPath(cwd: string): string | undefined {
 	if ($env.CONDA_PREFIX) return $env.CONDA_PREFIX;
 	const candidates = [path.join(cwd, ".venv"), path.join(cwd, "venv")];
 	for (const candidate of candidates) {
-		if (fs.existsSync(candidate)) {
-			return candidate;
-		}
+		if (isAutoDetectedWorkspaceVenv(candidate, cwd)) return candidate;
 	}
 	return undefined;
 }

package/src/exec/bash-executor.ts

@@ -12,6 +12,7 @@ import type {
 	ShellRunResult,
 } from "@gajae-code/natives";
 import { postmortem } from "@gajae-code/utils";
+import { projectDeclaredSpawnHookNames, stripProjectSpawnHooks } from "@gajae-code/utils/shell-config";
 import { Settings, type ShellMinimizerSettings } from "../config/settings";
 import { formatCrashDiagnosticNotice, writeCrashReport } from "../debug/crash-diagnostics";
 import {
@@ -93,6 +94,20 @@ export function setShellFactoryForTests(factory: ShellFactory | undefined): void
 	shellFactoryForTests = factory;
 }
 
+function projectHookUnsetEnv(
+	unsetEnv: string[] | undefined,
+	env: Record<string, string> | undefined,
+	sessionEnv: Record<string, string>,
+): string[] | undefined {
+	// Keys present in `sessionEnv` (e.g. the trusted HOME replacement) already
+	// override the ambient import, so only shadow the ones it does not carry.
+	const hooks = projectDeclaredSpawnHookNames().filter(
+		name => !Object.hasOwn(env ?? {}, name) && !Object.hasOwn(sessionEnv, name),
+	);
+	if (hooks.length === 0) return unsetEnv;
+	return [...(unsetEnv ?? []), ...hooks.filter(name => !unsetEnv?.includes(name))];
+}
+
 async function createShell(
 	options?: ShellOptions,
 	onTerminal?: (shell: Shell) => void,
@@ -414,13 +429,67 @@ async function resolveShellCwd(cwd: string | undefined): Promise<string | undefi
 	}
 }
 
+function presentMinimizerString(value: unknown): string | undefined {
+	return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+type ShellMinimizerSource = {
+	getGroup(prefix: "shellMinimizer"): ShellMinimizerSettings;
+	getGlobal?(path: "shellMinimizer.settingsPath" | "shellMinimizer.settingsHash"): unknown;
+	getOverride?(path: "shellMinimizer.settingsPath"): unknown;
+};
+
+/**
+ * A repo `.gjc/settings.json` must not point the minimizer at a TOML file.
+ * The native gate loads that file only when `settingsHash` matches, and the
+ * pin is the user/global value. A user path or a runtime override is still
+ * passed through. A project path is passed only together with that pin.
+ */
+export function resolveTrustedShellMinimizer(settings: ShellMinimizerSource): ShellMinimizerSettings {
+	const group = settings.getGroup("shellMinimizer");
+	const globalPath =
+		typeof settings.getGlobal === "function"
+			? presentMinimizerString(settings.getGlobal("shellMinimizer.settingsPath"))
+			: undefined;
+	const globalHash =
+		typeof settings.getGlobal === "function"
+			? presentMinimizerString(settings.getGlobal("shellMinimizer.settingsHash"))
+			: undefined;
+	const overridePath =
+		typeof settings.getOverride === "function"
+			? presentMinimizerString(settings.getOverride("shellMinimizer.settingsPath"))
+			: undefined;
+	const effectivePath = presentMinimizerString(group.settingsPath);
+
+	let settingsPath: string | undefined;
+	if (overridePath && effectivePath === overridePath) {
+		settingsPath = overridePath;
+	} else if (globalPath) {
+		settingsPath = globalPath;
+	} else if (effectivePath && globalHash) {
+		settingsPath = effectivePath;
+	}
+
+	// A runtime override of a different path is operator input, not the file the
+	// user hash pins. Every other admitted path is checked with that pin.
+	const unpinnedOverride = overridePath !== undefined && settingsPath === overridePath && settingsPath !== globalPath;
+	return {
+		...group,
+		settingsPath,
+		settingsHash: globalHash && settingsPath && !unpinnedOverride ? globalHash : undefined,
+	};
+}
+
 /** Translate `ShellMinimizerSettings` into native `MinimizerOptions`, or `undefined` when disabled. */
 export function buildMinimizerOptions(group: ShellMinimizerSettings): MinimizerOptions | undefined {
 	if (!group.enabled) return undefined;
 	const maxCaptureBytes = Math.min(4 * 1024 * 1024, Math.max(1024, Math.trunc(group.maxCaptureBytes)));
+	const settingsPath = group.settingsPath || undefined;
+	const settingsHash = settingsPath && group.settingsHash ? group.settingsHash : undefined;
 	return {
 		enabled: true,
-		settingsPath: group.settingsPath || undefined,
+		settingsPath,
+		...(settingsHash ? { settingsHash } : {}),
 		only: group.only.length > 0 ? group.only : undefined,
 		except: group.except.length > 0 ? group.except : undefined,
 		maxCaptureBytes,
@@ -429,12 +498,16 @@ export function buildMinimizerOptions(group: ShellMinimizerSettings): MinimizerO
 
 export async function executeBash(command: string, options?: BashExecutorOptions): Promise<BashResult> {
 	const settings = options?.settings ?? (await Settings.init());
-	const { shell, env: shellEnv, prefix } = settings.getShellConfig();
+	const { shell, env: configEnv, prefix } = settings.getShellConfig();
+	// The shell config env is shared with other consumers (Python kernels keep
+	// their own documented allowlist). Only the bash tool's shell must not see
+	// project hook variables such as BASH_ENV or GIT_CONFIG_*.
+	const shellEnv = stripProjectSpawnHooks({ ...configEnv });
 	const configuredPrefix = options?.ignoreShellPrefix ? undefined : prefix;
 	const snapshotPath =
 		!options?.disableShellSnapshot && shell.includes("bash") ? await getOrCreateSnapshot(shell, shellEnv) : null;
 
-	const minimizer = buildMinimizerOptions(settings.getGroup("shellMinimizer"));
+	const minimizer = buildMinimizerOptions(resolveTrustedShellMinimizer(settings));
 
 	const commandCwd = await resolveShellCwd(options?.cwd);
 	const commandEnv = options?.env ? { ...NON_INTERACTIVE_ENV, ...options.env } : NON_INTERACTIVE_ENV;
@@ -580,7 +653,11 @@ export async function executeBash(command: string, options?: BashExecutorOptions
 			command: finalCommand,
 			cwd: commandCwd,
 			env: commandEnv,
-			unsetEnv: options?.unsetEnv,
+			// The native shell imports the host process environment before
+			// `sessionEnv`, and where it runs in-process (Windows) that environment
+			// holds the autoloaded project `.env`. Shadow project hook variables per
+			// run unless this call sets them explicitly.
+			unsetEnv: projectHookUnsetEnv(options?.unsetEnv, options?.env, shellEnv),
 			timeoutMs: executionTimeoutMs,
 			signal: runAbortController.signal,
 		};

package/src/exec/bash-shell-guardian.ts

@@ -8,6 +8,7 @@ import * as path from "node:path";
 import * as readline from "node:readline";
 import type { Process as NativeProcess } from "@gajae-code/natives";
 import { isCompiledBinary } from "@gajae-code/utils/env";
+import { projectSafeSpawnEnv } from "@gajae-code/utils/shell-config";
 import { BASH_SHELL_SUPERVISOR_ARG, type BashShellWorkerRequest } from "./bash-shell-worker-protocol";
 
 type NativeProcessBindings = { Process: typeof NativeProcess };
@@ -401,7 +402,9 @@ export async function runBashShellGuardian(): Promise<void> {
 	const [executable, ...args] = supervisorArgv();
 	const supervisor = childProcess.spawn(executable!, args, {
 		detached: process.platform !== "win32",
-		env: process.env,
+		// This process reloaded the project `.env` on startup; keep project hook
+		// variables out of the supervisor -> runtime -> native shell chain.
+		env: projectSafeSpawnEnv(),
 		stdio: ["pipe", "inherit", "inherit"],
 		windowsHide: true,
 	});

package/src/exec/bash-shell-supervisor.ts

@@ -8,6 +8,7 @@ import * as path from "node:path";
 import * as readline from "node:readline";
 import type { Process as NativeProcess } from "@gajae-code/natives";
 import { isCompiledBinary } from "@gajae-code/utils/env";
+import { projectSafeSpawnEnv } from "@gajae-code/utils/shell-config";
 import { parseLinuxProcParentPid, parseLinuxProcStartTime, parseLinuxProcState } from "../gjc-runtime/linux-proc";
 import { processIncarnation } from "../sdk/broker/process-incarnation";
 import { fatalCatchableSignals, signalExitCode } from "./bash-shell-signals";
@@ -39,9 +40,10 @@ function darwinUniqueProcessId(pid: number, incarnation: string): string | undef
 }
 
 function runtimeArgv(): string[] {
-	return isCompiledBinary()
-		? [process.execPath, BASH_SHELL_RUNTIME_ARG]
-		: [process.execPath, path.join(import.meta.dir, "bash-shell-runtime-entry.ts")];
+	if (isCompiledBinary()) return [process.execPath, BASH_SHELL_RUNTIME_ARG];
+	// The supervisor already sanitized this environment. Do not let the source
+	// runtime reload a cwd `.env` that may have changed since the snapshot.
+	return [process.execPath, "--no-env-file", path.join(import.meta.dir, "bash-shell-runtime-entry.ts")];
 }
 
 function enableLinuxChildSubreaper(): void {
@@ -264,7 +266,9 @@ export async function runBashShellSupervisor(): Promise<void> {
 	const worker = childProcess.spawn(command!, args, {
 		cwd: process.cwd(),
 		detached: false,
-		env: { ...process.env, GJC_ISOLATED_SHELL_RUNTIME: "1" },
+		// This process reloaded the project `.env` on startup; the runtime's native
+		// shell imports its environment wholesale, so drop project hook variables.
+		env: { ...projectSafeSpawnEnv(), GJC_ISOLATED_SHELL_RUNTIME: "1" },
 		stdio: ["pipe", "pipe", "pipe"],
 		windowsHide: true,
 	});

package/src/exec/isolated-shell.ts

@@ -5,6 +5,7 @@ import * as path from "node:path";
 import * as readline from "node:readline";
 import type { ShellRunOptions } from "@gajae-code/natives";
 import { isCompiledBinary } from "@gajae-code/utils/env";
+import { projectSafeSpawnEnv } from "@gajae-code/utils/shell-config";
 import {
 	BASH_SHELL_WORKER_ARG,
 	type BashShellWorkerRequest,
@@ -84,7 +85,10 @@ export class IsolatedShell {
 		this.#child = childProcess.spawn(command!, args, {
 			cwd: process.cwd(),
 			detached: process.platform !== "win32",
-			env: process.env,
+			// The worker chain (guardian -> supervisor -> runtime) inherits this env and
+			// the native shell imports it wholesale, so project hook variables must be
+			// gone here, not only from the per-session overlay.
+			env: projectSafeSpawnEnv(),
 			stdio: ["pipe", "pipe", "pipe"],
 			windowsHide: true,
 		});

package/src/exec/non-interactive-env.ts

@@ -24,7 +24,6 @@ export const NON_INTERACTIVE_ENV: Readonly<Record<string, string>> = {
 	EDITOR: "true",
 	GIT_TERMINAL_PROMPT: "0",
 	SSH_ASKPASS: "/usr/bin/false",
-	CI: "1",
 	// Package manager defaults for unattended execution.
 	npm_config_yes: "true",
 	npm_config_update_notifier: "false",

package/src/export/html/index.ts

@@ -2,7 +2,7 @@ import * as syncFs from "node:fs";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import type { AgentState } from "@gajae-code/agent-core";
-import { APP_NAME, isEnoent } from "@gajae-code/utils";
+import { APP_NAME, isCredentialKey, isEnoent, redactCrashSecrets } from "@gajae-code/utils";
 import { getResolvedThemeColors, getThemeExportColors } from "../../modes/theme/theme";
 import { SessionManager } from "../../session/session-manager";
 // Pre-generated template (created by scripts/generate-template.ts at publish time)
@@ -226,18 +226,18 @@ async function writeSessionHtml(
 	};
 	try {
 		sink.write(themedTemplate.slice(0, markerOffset));
-		writeEncoded(`{"header":${JSON.stringify(sm.getHeader())},"entries":[`);
+		writeEncoded(`{"header":${sessionEmbedJson(sm.getHeader())},"entries":[`);
 		let first = true;
 		sm.visitEntriesForExport(entry => {
-			writeEncoded(`${first ? "" : ","}${JSON.stringify(entry)}`);
+			writeEncoded(`${first ? "" : ","}${sessionEmbedJson(entry)}`);
 			first = false;
 		});
-		writeEncoded(`],"leafId":${JSON.stringify(sm.getLeafId())}`);
+		writeEncoded(`],"leafId":${sessionEmbedJson(sm.getLeafId())}`);
 		if (state?.systemPrompt !== undefined)
-			writeEncoded(`,"systemPrompt":${JSON.stringify(state.systemPrompt.join("\n\n"))}`);
+			writeEncoded(`,"systemPrompt":${sessionEmbedJson(state.systemPrompt.join("\n\n"))}`);
 		if (state?.tools !== undefined)
 			writeEncoded(
-				`,"tools":${JSON.stringify(state.tools.map(tool => ({ name: tool.name, description: tool.description })))}`,
+				`,"tools":${sessionEmbedJson(state.tools.map(tool => ({ name: tool.name, description: tool.description })))}`,
 			);
 		writeEncoded("}");
 		const final = encoder.finish();
@@ -253,6 +253,86 @@ async function writeSessionHtml(
 	}
 }
 
+/**
+ * Own `__proto__` stays a data property; a normal object would turn that assignment into the prototype.
+ * Credential keys mask every JSON value, and string values are scrubbed directly so JSON escaping
+ * cannot turn ordinary quote characters into credential-value delimiters.
+ */
+function redactJsonValue(value: unknown): unknown {
+	if (typeof value === "string") return redactCrashSecrets(value);
+	if (Array.isArray(value)) {
+		const isFlatKeyValueArray =
+			value.length > 0 &&
+			value.length % 2 === 0 &&
+			value.every((item, index) => index % 2 === 1 || typeof item === "string");
+		if (isFlatKeyValueArray) {
+			return value.map((item, index) => {
+				if (index % 2 === 1) {
+					const key = value[index - 1];
+					if (typeof key === "string" && isCredentialKey(key)) return "«redacted»";
+				}
+				return redactJsonValue(item);
+			});
+		}
+		return value.map(item => redactJsonValue(item));
+	}
+	if (value === null || typeof value !== "object") return value;
+	const source = value as Record<string, unknown>;
+	const sourceKeys = Object.keys(source);
+	let hasCredentialHeaderName = false;
+	let hasHeaderValue = false;
+	for (const key of sourceKeys) {
+		const field = key.toLowerCase();
+		if (field === "value" || field === "values") hasHeaderValue = true;
+		if (field !== "name" && field !== "key") continue;
+		const headerName = source[key];
+		if (typeof headerName === "string" && isCredentialKey(headerName)) hasCredentialHeaderName = true;
+	}
+	const redactHeaderValue = hasCredentialHeaderName && hasHeaderValue;
+	const redacted = Object.create(null) as Record<string, unknown>;
+	const nextSuffixByKey = new Map<string, number>();
+	for (const key of sourceKeys) {
+		const redactedKey = uniqueJsonObjectKey(redacted, redactCrashSecrets(key), nextSuffixByKey);
+		const field = key.toLowerCase();
+		if (redactHeaderValue && (field === "value" || field === "values")) {
+			const headerValue = source[key];
+			redacted[redactedKey] =
+				field === "values" && Array.isArray(headerValue) ? headerValue.map(() => "«redacted»") : "«redacted»";
+		} else {
+			redacted[redactedKey] = redactKeyedValue(key, source[key]);
+		}
+	}
+	return redacted;
+}
+
+// Resume after the last collision for this base key rather than rescanning prior suffixes.
+function uniqueJsonObjectKey(
+	target: Record<string, unknown>,
+	key: string,
+	nextSuffixByKey: Map<string, number>,
+): string {
+	if (!Object.hasOwn(target, key)) return key;
+	let suffix = nextSuffixByKey.get(key) ?? 2;
+	let candidate = `${key}#${suffix}`;
+	while (Object.hasOwn(target, candidate)) {
+		suffix += 1;
+		candidate = `${key}#${suffix}`;
+	}
+	nextSuffixByKey.set(key, suffix + 1);
+	return candidate;
+}
+
+function redactKeyedValue(key: string, value: unknown): unknown {
+	// A recognized key is authoritative for every JSON type, including a short
+	// string, a number, an array, or a nested object.
+	if (isCredentialKey(key)) return "«redacted»";
+	return typeof value === "string" ? redactCrashSecrets(value) : redactJsonValue(value);
+}
+
+function sessionEmbedJson(value: unknown): string {
+	return JSON.stringify(redactJsonValue(JSON.parse(JSON.stringify(value))));
+}
+
 /** Export session to HTML using SessionManager and AgentState. */
 export async function exportSessionToHtml(
 	sm: SessionManager,