oh-my-pi/packages/coding-agent/src/secrets/obfuscator.ts

import * as crypto from "node:crypto";
import type { AgentMessage } from "@oh-my-pi/pi-agent-core";
import type { AssistantMessage, Context, ImageContent, Message, TextContent } from "@oh-my-pi/pi-ai";
import type { SessionContext } from "../session/session-context";
import { compileSecretRegex } from "./regex";

// ═══════════════════════════════════════════════════════════════════════════
// Types
// ═══════════════════════════════════════════════════════════════════════════

export interface SecretEntry {
	type: "plain" | "regex";
	content: string;
	mode?: "obfuscate" | "replace";
	replacement?: string;
	flags?: string;
	friendlyName?: string;
}

export type JsonValue = string | number | boolean | null | JsonValue[] | { [key: string]: JsonValue | undefined };
export type JsonRecord = { [key: string]: JsonValue | undefined };

// ═══════════════════════════════════════════════════════════════════════════
// Deterministic replacement generation
// ═══════════════════════════════════════════════════════════════════════════

const REPLACEMENT_CHARS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
const NONMATCHING_REPLACEMENT_CHARS = `${REPLACEMENT_CHARS}!#$%&()*+,-./:;<=>?@[]^_{|}~`;
// Whitespace bytes used to build last-resort redactions for a default replace
// regex that matches every non-whitespace candidate (e.g. `\S{n}`). Only
// `space`/`tab` are used — never a line terminator — so a `.`-style
// match-everything regex (which matches space and tab but not `\n`) still
// exhausts to the sentinel instead of redacting to a newline run.
const WHITESPACE_REPLACEMENT_CHARS = " \t";

/** Generate a deterministic same-length replacement string from a secret value. */
function generateDeterministicReplacement(secret: string): string {
	if (secret.length === 0) return "";
	// Prefix generated chunks with a fixed `ZZ` so re-redacting an already-emitted
	// 1–2 char chunk is a fixed point (the deterministic replacement of a <=2-char
	// value is itself `Z`/`ZZ`), keeping short default-replacement remainders next
	// to a reversible placeholder stable across an obfuscator restart.
	const hash = BigInt(Bun.hash(secret));
	const chars = secret.length === 1 ? ["Z"] : ["Z", "Z"];
	let h = hash;
	for (let i = chars.length; i < secret.length; i++) {
		h = h ^ (BigInt(i + 1) * 0x9e3779b97f4a7c15n);
		const idx = Number((h < 0n ? -h : h) % BigInt(REPLACEMENT_CHARS.length));
		chars.push(REPLACEMENT_CHARS[idx]);
	}
	return chars.join("");
}

/**
 * Force a length-preserving deterministic replacement to differ from the secret
 * it stands in for. `generateDeterministicReplacement` seeds its first 1–2 chars
 * with the `Z`/`ZZ` sentinel, so a whole configured value that is exactly `Z` or
 * `ZZ` (or an astronomically unlikely longer hash collision) would otherwise be
 * emitted unchanged and ship the raw secret to the provider. Flip the first char
 * to a fixed different glyph: same length, still deterministic, guaranteed != the
 * secret. Only safe for a whole CONFIGURED value (a plain secret matches its own
 * literal, so the perturbed output is no longer matched and stays a fixed point);
 * per-chunk remainders must keep the sentinel to remain idempotent across restart.
 */
function ensureDistinctReplacement(replacement: string, secret: string): string {
	if (replacement.length === 0 || replacement !== secret) return replacement;
	const alt = replacement[0] === REPLACEMENT_CHARS[0] ? REPLACEMENT_CHARS[1] : REPLACEMENT_CHARS[0];
	return alt + replacement.slice(1);
}

// How far left of the matched span the re-match scan begins looking for a match
// that overlaps the candidate. This bounds ONLY the match-start search position,
// never the lookbehind/lookahead context: the probe below substitutes the
// candidate into the FULL text, so a regex's lookbehind/lookahead assertions
// always evaluate against complete context regardless of width. The single
// re-match this misses is one that begins more than this many bytes before the
// span and extends into it (a single match longer than the window) — that only
// churns the chosen redaction marker between candidates, never back to the raw
// matched value, so it cannot leak a secret.
const REGEX_REMATCH_BACKSCAN = 512;

interface RegexMatchContext {
	/** Full text the match was found in (positions are offsets into it). */
	text: string;
	/** Start/end of the matched span being replaced. */
	start: number;
	end: number;
}

/**
 * Whether `candidate`, substituted for the matched span in its surrounding text,
 * is re-matched by `regex` at its own position. A replace-mode regex that depends
 * on context (lookbehind/lookahead/`\b`) can match a candidate that does NOT match
 * in isolation: e.g. `(?<=api=)[AZ]` never matches a bare `A`, but `api=A` does, so
 * a candidate `A` chosen by an isolation test is re-redacted on the next obfuscate()
 * pass and can oscillate back to the raw matched value. The probe substitutes the
 * candidate into the FULL text — not a truncated window — so a wide lookbehind or
 * lookahead (e.g. `(?<=A{600})`) still evaluates against the context that makes it
 * match. Truncating that context dropped the assertion's reach and falsely
 * accepted an oscillating, leaky candidate. The scan starts a bounded distance
 * left of the span and stops once a match begins at/after the span's end (matches
 * arrive in order), keeping per-candidate cost independent of total text length.
 */
function regexRematchesInContext(candidate: string, regex: RegExp, ctx: RegexMatchContext): boolean {
	const probe = ctx.text.slice(0, ctx.start) + candidate + ctx.text.slice(ctx.end);
	const spanStart = ctx.start;
	const spanEnd = spanStart + candidate.length;
	regex.lastIndex = Math.max(0, spanStart - REGEX_REMATCH_BACKSCAN);
	for (let m = regex.exec(probe); m !== null; m = regex.exec(probe)) {
		const matchStart = m.index;
		const matchEnd = m.index + m[0].length;
		// Matches arrive in increasing position; once one starts at or past the
		// span's end it cannot cover the candidate, and neither can any later one.
		if (matchStart >= spanEnd) break;
		// A match overlapping the candidate's own bytes means those bytes get
		// re-redacted on a later pass — not a fixed point.
		if (matchEnd > spanStart) return true;
		// Zero-width matches do not advance lastIndex; step past to avoid a loop.
		if (m[0].length === 0) regex.lastIndex++;
	}
	return false;
}

/**
 * Search same-length replacements for one the regex does NOT match, so a default
 * regex secret whose deterministic replacement collides with its own value (the
 * `Z`/`ZZ` sentinel, or an astronomical hash collision) is still redacted to a
 * STABLE nonmatching value instead of shipping the raw secret. A nonmatching
 * candidate is a fixed point under re-obfuscation — the regex never re-matches it,
 * so it cannot re-leak on a later pass. The search stays bounded to O(length *
 * alphabet) regardless of value length: first exhaust every single-position
 * substitution against a deterministic baseline (`AAAA…`, then `!AAA…`, `A!AA…`,
 * …) so any regex that only needs one out-of-class byte — regardless of position —
 * is found in a handful of probes rather than enumerating every combination (which
 * for a 3-byte match-everything config, e.g. `[\s\S]{3}`, would otherwise run
 * 90**3 = 729000 candidates through the regex on every single match, stalling
 * provider requests). Candidates are enumerated deterministically over a stable
 * ASCII alphabet: alphanumerics first (usually enough), then punctuation fallback
 * bytes when the regex covers every alphanumeric candidate. When the regex still
 * matches around a lone perturbed byte (for example `[A-Za-z0-9].*` matching the
 * unperturbed tail), full-width same-byte candidates (`!!!!!`, `_____`, …) are
 * tried next. When the regex covers every non-whitespace candidate (e.g. `\S{n}`),
 * whitespace markers (a full space/tab run, then a single whitespace byte among
 * non-whitespace filler) are tried as a last resort. A genuine match-everything
 * regex (`.`/`[\s\S]`, which also matches space and tab) still exhausts this bounded
 * sweep and returns undefined, letting the caller keep its own fixed-point fallback
 * — bounded search can in principle miss an escape that depends jointly on
 * multiple positions in a way no single-position swap reaches, but no realistic
 * secret-redaction regex (character classes, literal matches, anchored/bounded
 * repeats) has that shape.
 */
function findNonMatchingReplacement(value: string, regex: RegExp, context: RegexMatchContext): string | undefined {
	const len = value.length;
	if (len === 0) return undefined;
	// Exhaust every single-position substitution against the deterministic baseline
	// first (covers the common case cheaply), then fall back to full-width same-byte
	// candidates for a regex that only rejects a lone perturbed byte in context.
	const baseline = NONMATCHING_REPLACEMENT_CHARS[0].repeat(len);
	for (let position = 0; position < len; position++) {
		for (const ch of NONMATCHING_REPLACEMENT_CHARS) {
			const candidate = `${baseline.slice(0, position)}${ch}${baseline.slice(position + 1)}`;
			if (candidate === value) continue;
			if (!regexRematchesInContext(candidate, regex, context)) return candidate;
		}
	}
	// If the regex can still match around a lone punctuation byte (for example
	// `[A-Za-z0-9].*` matching the `AAAA` tail of `!AAAA`), try full-width
	// same-byte fallbacks like `!!!!!`, `_____`, etc. before giving up.
	for (const ch of NONMATCHING_REPLACEMENT_CHARS) {
		const candidate = ch.repeat(len);
		if (candidate === value) continue;
		if (!regexRematchesInContext(candidate, regex, context)) return candidate;
	}
	return findWhitespaceFallbackReplacement(value, regex, context);
}

/**
 * Last-resort fallback for a default replace regex that matches every
 * non-whitespace candidate. Builds same-length whitespace markers the regex
 * cannot match: first a full space/tab run (handles `\S`-class patterns), then a
 * single whitespace byte among non-whitespace filler (` AAAA`, `A AAA`, …). The
 * mixed marker defeats regexes that ALSO match all-space/all-tab runs, e.g.
 * `(?:\S{n}| {n}|\t{n})`, because the lone whitespace byte breaks every
 * fixed-length run. A genuine match-everything regex (`.`/`[\s\S]`) matches the
 * filler and the whitespace alike, so this still returns undefined there, keeping
 * the caller's sentinel as the sole fixed point.
 */
function findWhitespaceFallbackReplacement(
	value: string,
	regex: RegExp,
	context: RegexMatchContext,
): string | undefined {
	const len = value.length;
	const filler = NONMATCHING_REPLACEMENT_CHARS[0];
	for (const ws of WHITESPACE_REPLACEMENT_CHARS) {
		const full = ws.repeat(len);
		if (full !== value) {
			if (!regexRematchesInContext(full, regex, context)) return full;
		}
		for (let pos = 0; pos < len; pos++) {
			const candidate = `${filler.repeat(pos)}${ws}${filler.repeat(len - pos - 1)}`;
			if (candidate === value) continue;
			if (!regexRematchesInContext(candidate, regex, context)) return candidate;
		}
	}
	return undefined;
}

/**
 * Whether a default (no custom `replacement`) replace-mode regex can never
 * safely redact a 1-2 char match: `findNonMatchingReplacement`'s bounded
 * search — the same search `#generateRegexReplacement` runs at match time —
 * finds no candidate the regex fails to re-match. This holds independent of
 * any actual per-install key: the search already exhausts every character in
 * `REPLACEMENT_CHARS` (the alphabet `buildKeyedReplacementRun` draws its
 * fallback marker from) plus punctuation and whitespace, so if none of those
 * escape the regex, no key-derived marker drawn from the same alphabet can
 * either — the marker is guaranteed to re-match too, making every such match
 * unresolvable: the fallback could only ever emit the raw matched text
 * unchanged. Probed with a value (`"\0".repeat(length)`) the bounded search
 * never treats as a real candidate, so the result depends only on the
 * regex's own matching behavior, not on this specific probe.
 */
export function regexHasUnresolvableShortMatchFallback(regex: RegExp): boolean {
	return ([1, 2] as const).some(length => {
		const probe = "\u0000".repeat(length);
		const savedLastIndex = regex.lastIndex;
		try {
			return findNonMatchingReplacement(probe, regex, { text: probe, start: 0, end: length }) === undefined;
		} finally {
			regex.lastIndex = savedLastIndex;
		}
	});
}

// ═══════════════════════════════════════════════════════════════════════════
// Placeholder format
// ═══════════════════════════════════════════════════════════════════════════

const HASH_CHARS = "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
// Base length is sized for ~62 bits of entropy (64 bits of a keyed digest
// rendered as 12 base36 chars) so unrelated secrets do not collide on a shared
// base. A collision would let a persisted placeholder deobfuscate to the wrong
// secret when the configured secret set or its ordering changes across sessions.
const HASH_LEN = 12;
const MAX_FRIENDLY_NAME_LEN = 32;
// Plain/regex obfuscate matches shorter than this are toned down (never placed
// behind a reversible placeholder) to avoid redacting small words/fragments.
export const MIN_OBFUSCATE_SECRET_LEN = 8;

// Per-process fallback key used when a caller does not supply a persisted
// per-install key. It is random (never shipped in source), so model-visible
// placeholders cannot be reversed by dictionary-hashing candidate secrets; it
// only forgoes cross-session token stability, which the persisted key provides.
let ephemeralPlaceholderKey: string | undefined;
function defaultPlaceholderKey(): string {
	ephemeralPlaceholderKey ??= crypto.randomBytes(32).toString("base64url");
	return ephemeralPlaceholderKey;
}

type PlaceholderCaseHint = "U" | "L" | "C" | "M";

/** Normalize a friendly name into the model-visible placeholder prefix. */
export function sanitizeSecretFriendlyName(name: string): string | undefined {
	const sanitized = name
		.replace(/[^A-Za-z0-9]/g, "")
		.toUpperCase()
		.slice(0, MAX_FRIENDLY_NAME_LEN);
	return sanitized.length > 0 ? sanitized : undefined;
}

/**
 * Normalize a secret value into the same alnum-only, uppercased shape a
 * friendly-name label or placeholder prefix is sanitized into, so comparing a
 * raw (possibly lowercase/punctuated) secret value against already-sanitized,
 * model-visible text does not miss a case- or separator-only variant. Unlike
 * `sanitizeSecretFriendlyName` this never truncates and never signals "empty"
 * via `undefined` — callers already guard on `.length > 0` before comparing.
 */
function sanitizeForCollisionCheck(value: string): string {
	return value.replace(/[^A-Za-z0-9]/g, "").toUpperCase();
}

// A label leaks a secret either by containing the whole normalized secret or,
// once it reaches the public display cap, by being the secret's visible prefix.
// Shorter names like "TOKEN" can still be intentional generic labels.
function sanitizedLabelCollidesWithSecret(sanitizedLabel: string, sanitizedSecret: string): boolean {
	if (sanitizedSecret.length === 0) return false;
	if (sanitizedLabel.includes(sanitizedSecret)) return true;
	return sanitizedLabel.length >= MAX_FRIENDLY_NAME_LEN && sanitizedSecret.startsWith(sanitizedLabel);
}

/**
 * Whether an entry needs the persisted placeholder key: either because it can
 * produce a reversible (keyed) obfuscate-mode placeholder, or because a default
 * (no custom `replacement`) replace-mode regex can reach
 * `#generateRegexReplacement`'s key-derived idempotent fallback marker (see
 * `#generateReplacement`) when every same-length candidate re-matches a
 * pathological match-everything config (e.g. `[\s\S]{8}`). That fallback depends
 * on the persisted per-install key — not just length — to stay a fixed point
 * across a process restart; without a persisted key, a fresh install falls back
 * to a process-random key (`defaultPlaceholderKey()`), so the fallback marker
 * would churn across restarts even though the algorithm itself is stable. A
 * regex WITH a custom `replacement` never reaches that fallback (it always emits
 * the literal configured string), and a plain replace secret's replacement is
 * pure content-hash (`#generateSecretReplacement`), so neither needs the key.
 * Short plain obfuscate entries are toned down (never placeheld), so they must
 * NOT force key creation: otherwise a `secret-placeholder.key` file is written
 * and persisted for a config that ends up with no active secrets, leaving the
 * key readable via a tool and reusable for later placeholders.
 */
export function secretEntryNeedsPlaceholderKey(entry: SecretEntry): boolean {
	if ((entry.mode ?? "obfuscate") === "obfuscate") {
		if (entry.type === "regex") return true;
		return entry.content.length >= MIN_OBFUSCATE_SECRET_LEN;
	}
	return entry.type === "regex" && entry.replacement === undefined;
}

/**
 * Whether a plain replace-mode replacement string can contribute a fragment that
 * helps the replace phase reconstruct an obfuscate `content`. During obfuscate()'s
 * replace phase the output is a tiling of passthrough bytes (adversary-controlled
 * provider text) and whole replacement outputs; any contiguous occurrence of
 * `content` in that output is covered by interior replacement tiles (each a
 * substring of `content`) bordered by passthrough at the ends, where the border
 * tile may be a suffix of a replacement (forming `content`'s prefix) or a prefix
 * of a replacement (forming `content`'s suffix). An EMPTY replacement deletes its
 * trigger entirely, joining the passthrough on both sides; with adversary-chosen
 * surrounding bytes that can form any non-empty `content` across the deleted gap.
 * So a replacement can help iff it is empty, is a substring of `content`,
 * contains `content`, or shares such a border overlap.
 */
function replacementCanFormContent(replacement: string, content: string): boolean {
	if (replacement.length === 0) return content.length > 0;
	if (content.includes(replacement) || replacement.includes(content)) return true;
	const maxOverlap = Math.min(replacement.length, content.length);
	for (let k = 1; k <= maxOverlap; k++) {
		// A suffix of the replacement forms the prefix of the content (left border),
		// or a prefix of the replacement forms the suffix of the content (right border).
		if (content.startsWith(replacement.slice(replacement.length - k)) || content.endsWith(replacement.slice(0, k))) {
			return true;
		}
	}
	return false;
}

/**
 * Whether a SET of entries needs the persisted placeholder key. `obfuscate()`
 * applies plain replace-mode mappings before the plain-obfuscate pass, so a plain
 * obfuscate entry only emits a reversible (keyed) placeholder when its content can
 * still appear AFTER the replace phase. When no obfuscate entry can ever produce a
 * placeholder, the persisted key must NOT be required/created — otherwise an
 * effectively replace-only secret set still writes `secret-placeholder.key` and
 * fails startup when the agent config dir is unwritable.
 *
 * The decision models the replace phase as the obfuscator actually runs it:
 * replace mappings are content-keyed (later duplicate wins) and applied in
 * descending content-length order; for a fresh probe (no prior placeholders) that
 * phase is plain sequential substring replacement. A plain obfuscate entry needs
 * the key when its content survives that simulated phase (direct typing) OR when
 * any effective replacement can form the content via tiling — a substring,
 * wholesale superstring, or prefix/suffix border that joins with surrounding
 * passthrough bytes (see `replacementCanFormContent`). This covers direct
 * shadowing (`SECRET -> safe`), reintroduction, duplicate ordering, transitive
 * chains, and context-joined fragments uniformly. Default (omitted) replacements
 * are deterministic, length-preserving, and distinct, so a same-content shadow
 * with no other interacting replacement stays key-free.
 * Replacement outputs are themselves rewritten by every later (shorter-content)
 * replacement before the plain-obfuscate pass sees them, so a fragment that a
 * subsequent replacement erases (`AA -> SEC` then `S -> X` turns every `SEC` into
 * `XEC`) no longer forces the key. Surrounding bytes stay modeled as arbitrary
 * passthrough, so testing the surviving fragment only drops false positives and
 * never under-approximates a real key need.
 */
export function secretEntriesNeedPlaceholderKey(entries: SecretEntry[]): boolean {
	const replaceMap = new Map<string, string>();
	for (const entry of entries) {
		if (entry.type !== "plain" || (entry.mode ?? "obfuscate") !== "replace") continue;
		replaceMap.set(
			entry.content,
			entry.replacement ?? ensureDistinctReplacement(generateDeterministicReplacement(entry.content), entry.content),
		);
	}
	const replacePhase = [...replaceMap].sort((a, b) => b[0].length - a[0].length);
	// Apply the replace phase from `start` onward. The phase runs in descending
	// content-length order, so a replacement output emitted at index i is rewritten
	// only by the later (shorter-content) replacements at i+1…; `start` 0 models a
	// value typed directly into the input.
	const applyReplacePhaseFrom = (text: string, start: number): string => {
		let result = text;
		for (let i = start; i < replacePhase.length; i++) {
			result = result.split(replacePhase[i][0]).join(replacePhase[i][1]);
		}
		return result;
	};
	return entries.some(entry => {
		if (!secretEntryNeedsPlaceholderKey(entry)) return false;
		// Regex obfuscate entries match dynamically; conservatively require the key.
		if (entry.type !== "plain") return true;
		const content = entry.content;
		if (applyReplacePhaseFrom(content, 0).includes(content)) return true;
		// Test each replacement output in the form it SURVIVES the rest of the phase,
		// so a fragment a later replacement erases no longer forces the key. The
		// content it tiles into must also survive those later replacements: if a
		// shorter-content replacement rewrites the surrounding passthrough bytes
		// (e.g. `AA -> SEC` forms `SEC`+`RET12`, then `R -> X` turns the freshly
		// formed `SECRET12` into `SECXET12`), the content can never reach the
		// obfuscate pass, so the key is not needed. Requiring content stability only
		// drops such false positives — a formation that genuinely survives is still
		// caught at the replacement index that produces it.
		return replacePhase.some(
			([, replacement], i) =>
				applyReplacePhaseFrom(content, i + 1) === content &&
				replacementCanFormContent(applyReplacePhaseFrom(replacement, i + 1), content),
		);
	});
}

// Derive the model-visible base from a KEYED digest of the secret. xxHash is
// fast and unkeyed, so a fixed-seed content hash of a low-entropy secret could
// be dictionaried from the transcript; HMAC-SHA256 under a private per-install
// key cannot, since the attacker lacks the key.
function buildHashBase(key: string, value: string): string {
	const digest = new Bun.CryptoHasher("sha256", key).update(value).digest();
	let v = 0n;
	for (let i = 0; i < 8; i++) v = (v << 8n) | BigInt(digest[i]);
	const radix = BigInt(HASH_CHARS.length);
	let tag = "";
	for (let i = 0; i < HASH_LEN; i++) {
		tag += HASH_CHARS[Number(v % radix)];
		v /= radix;
	}
	return tag;
}

// Build a deterministic, key-derived run of REPLACEMENT_CHARS of the given
// length. Used to redact a per-chunk replace remainder to a marker that depends
// only on the per-install key and the remainder length, so a fresh obfuscator
// reproduces the identical marker (idempotent redaction across restarts) while
// the run stays unpredictable without the key (raw sentinel-shaped bytes cannot
// equal the marker, so they are still redacted rather than passed through).
function buildKeyedReplacementRun(key: string, length: number): string {
	if (length <= 0) return "";
	const radix = REPLACEMENT_CHARS.length;
	let out = "";
	for (let block = 0; out.length < length; block++) {
		const digest = new Bun.CryptoHasher("sha256", key).update(`replace-chunk\0${length}\0${block}`).digest();
		for (let i = 0; i < digest.length && out.length < length; i++) {
			out += REPLACEMENT_CHARS[digest[i] % radix];
		}
	}
	return out;
}

function inferCaseHint(secret: string): PlaceholderCaseHint | undefined {
	let hasCased = false;
	let hasUpper = false;
	let hasLower = false;
	let capitalized = true;
	let seenFirstCased = false;

	for (let i = 0; i < secret.length; i++) {
		const code = secret.charCodeAt(i);
		const isUpper = code >= 65 && code <= 90;
		const isLower = code >= 97 && code <= 122;
		if (!isUpper && !isLower) continue;

		hasCased = true;
		if (isUpper) {
			hasUpper = true;
			if (seenFirstCased) capitalized = false;
		} else {
			hasLower = true;
			if (!seenFirstCased) capitalized = false;
		}
		seenFirstCased = true;
	}

	if (!hasCased) return undefined;
	if (hasUpper && !hasLower) return "U";
	if (hasLower && !hasUpper) return "L";
	if (capitalized) return "C";
	return "M";
}

function buildPlaceholder(hint: PlaceholderCaseHint | undefined, base: string, friendlyName?: string): string {
	const prefix = friendlyName ? `${friendlyName}_` : "";
	return hint ? `$$${prefix}${base}:${hint}$$` : `$$${prefix}${base}$$`;
}

/** Regex matching `$$HASH$$`, `$$HASH:U$$`, and `$$FRIENDLY_HASH(:hint)$$` placeholders. */
const PLACEHOLDER_RE = /\$\$(?:[A-Z0-9]+_)?[A-Z0-9]{4,}(?::[ULCM])?\$\$/g;

function resumePlaceholderScanAfterRejectedCandidate(match: RegExpExecArray): void {
	// RegExp#exec does not find overlapping matches. Restart at the rejected
	// candidate's closing delimiter, which can open an immediately adjacent placeholder.
	PLACEHOLDER_RE.lastIndex = match.index + match[0].length - 2;
}

function placeholderWithoutFriendlyName(placeholder: string): string | undefined {
	const match = /^\$\$[A-Z0-9]+_([A-Z0-9]{4,}(?::[ULCM])?)\$\$$/.exec(placeholder);
	return match ? `$$${match[1]}$$` : undefined;
}

function lookupFriendlyPlaceholderAlias(
	deobfuscateMap: ReadonlyMap<string, { secret: string; recursive: boolean }>,
	placeholder: string,
): { secret: string; recursive: boolean } | undefined {
	const direct = deobfuscateMap.get(placeholder);
	if (direct !== undefined) return direct;
	const unprefixed = placeholderWithoutFriendlyName(placeholder);
	return unprefixed !== undefined ? deobfuscateMap.get(unprefixed) : undefined;
}

const PENDING_PLACEHOLDER_SUFFIX_RE = /(?:\$\$(?:[A-Z0-9]+_)?[A-Z0-9]*(?::[ULCM]?)?|\$)$/;

// Withhold a trailing run that could be the start of a placeholder from streamed
// deltas, so a partial token is never emitted before deobfuscation can replace
// it. A lone trailing delimiter character is always buffered because it can open
// a placeholder; the final non-streamed flush re-emits it when no token follows.
export function stripPendingSecretPlaceholderSuffix(text: string): string {
	const pendingPlaceholderStart = text.match(PENDING_PLACEHOLDER_SUFFIX_RE);
	if (pendingPlaceholderStart?.index === undefined) return text;
	return text.slice(0, pendingPlaceholderStart.index);
}

interface RegexScanSegment {
	scanStart: number;
	scanEnd: number;
	textStart: number;
	textEnd: number;
	generatedPlaceholder: boolean;
	recursive: boolean;
}

interface ReplaceRegexScan {
	text: string;
	segments: RegexScanSegment[];
}

// ═══════════════════════════════════════════════════════════════════════════
// SecretObfuscator
// ═══════════════════════════════════════════════════════════════════════════

export class SecretObfuscator {
	/** Plain secrets: secret → index (known at construction) */
	#plainMappings = new Map<string, number>();

	/** Regex entries (patterns compiled at construction) */
	#regexEntries: Array<{ regex: RegExp; mode: "obfuscate" | "replace"; replacement?: string; friendlyName?: string }> =
		[];

	/** All obfuscate-mode mappings: index → { secret, placeholder } */
	#obfuscateMappings = new Map<number, { secret: string; placeholder: string }>();

	/** Replace-mode plain mappings: secret → replacement */
	#replaceMappings = new Map<string, string>();

	/** Reverse lookup for LIVE deobfuscation (provider output, tool-call args):
	 *  keyed placeholder → secret plus recursion policy. Only placeholders this
	 *  obfuscator generated under the per-install key (and their friendly-name-
	 *  independent aliases) live here, so a prompt-injected model cannot synthesize
	 *  one without the key. */
	#deobfuscateMap = new Map<string, { secret: string; recursive: boolean }>();

	/** Exact placeholder tokens generated by this obfuscator revision (no aliases). */
	#generatedPlaceholders = new Set<string>();

	/** Deterministic replace chunks emitted by this obfuscator, used to keep re-obfuscation idempotent. */
	#generatedReplaceChunks = new Set<string>();

	/** Every configured plain-secret literal value (both obfuscate and replace
	 *  mode), collected before any placeholder is minted. A generated placeholder
	 *  must never equal one of these — otherwise a later-processed secret whose
	 *  raw value happens to equal an earlier secret's placeholder would be
	 *  indistinguishable from that placeholder on the NEXT obfuscate() pass (its
	 *  own plain-secret redaction already ran, sorted by length, before the
	 *  placeholder existed) and would survive verbatim in provider-visible text. */
	#configuredSecretValues = new Set<string>();

	/** Regex values seen in the current obfuscate input, used to keep friendly labels from exposing normalized matches that are discovered later in the same pass. */
	#currentRegexSecretValues = new Set<string>();

	/** Placeholder base-key (exact value for :M, case-folded otherwise) → base hash. */
	#placeholderBaseByKey = new Map<string, string>();

	/** Placeholder base hash → owner key, used to avoid ambiguous placeholders. */
	#placeholderBaseOwners = new Map<string, string>();

	/** Next available index for regex match discoveries */
	#nextIndex: number;

	/** Whether any secrets were configured */
	#hasAny: boolean;

	/**
	 * Private per-install (or per-process) key for the keyed placeholder digest.
	 * Resolved lazily when the constructor received a key PROVIDER: the first
	 * placeholder mint or keyed fallback marker triggers resolution, so callers
	 * can defer persisting `secret-placeholder.key` until a dynamic regex entry
	 * actually matches session content.
	 */
	#key: string | undefined;
	#keyProvider: (() => string) | undefined;

	constructor(entries: SecretEntry[], key: string | (() => string) = defaultPlaceholderKey()) {
		if (typeof key === "function") {
			this.#keyProvider = key;
		} else {
			this.#setPlaceholderKey(key);
		}
		// Collect every configured plain-secret literal AND compile every regex
		// entry BEFORE minting any placeholder below, so a placeholder's friendly
		// name (checked against both in `#createPlaceholder`) can never embed a
		// LATER entry's raw value or regex coverage, regardless of entries[]
		// order — same reasoning as the base-collision guard below, extended to
		// the friendly-name collision guard.
		for (const entry of entries) {
			if (entry.type === "plain") {
				this.#configuredSecretValues.add(entry.content);
				continue;
			}
			try {
				const regex = compileSecretRegex(entry.content, entry.flags);
				const mode = entry.mode ?? "obfuscate";
				// A default (no custom `replacement`) replace-mode regex that can
				// never redact a 1-2 char match distinctly from itself (see
				// `regexHasUnresolvableShortMatchFallback`) is dropped rather than
				// risk a real secret round-tripping unredacted; `secrets/index.ts`
				// warns loudly for the `secrets.yml`-loaded path — this is the
				// silent backstop for direct construction.
				if (
					mode === "replace" &&
					entry.replacement === undefined &&
					regexHasUnresolvableShortMatchFallback(regex)
				) {
					continue;
				}
				this.#regexEntries.push({
					regex,
					mode,
					replacement: entry.replacement,
					friendlyName: entry.friendlyName,
				});
			} catch {
				// Invalid regex — skip silently (validation happens at load time)
			}
		}
		let index = 0;
		let hasRealSec = this.#regexEntries.length > 0;
		for (const entry of entries) {
			if (entry.type !== "plain") continue;
			const mode = entry.mode ?? "obfuscate";
			if (mode === "obfuscate") {
				if (entry.content.length < MIN_OBFUSCATE_SECRET_LEN) {
					// Tone down short plain secret obfuscation to avoid false matches on small words like "esp".
					continue;
				}
				const placeholder = this.#createPlaceholder(entry.content, entry.friendlyName);
				this.#plainMappings.set(entry.content, index);
				this.#obfuscateMappings.set(index, { secret: entry.content, placeholder });
				this.#generatedPlaceholders.add(placeholder);
				index++;
				hasRealSec = true;
			} else {
				// replace mode
				const replacement = entry.replacement ?? this.#generateSecretReplacement(entry.content);
				this.#replaceMappings.set(entry.content, replacement);
				hasRealSec = true;
			}
		}

		this.#nextIndex = index;
		this.#hasAny = hasRealSec;
	}

	/**
	 * The keyed-hash key makes obfuscate-mode placeholder bases un-dictionaryable,
	 * but it can be persisted in a user-readable file (`secret-placeholder.key`).
	 * A prompt-injected tool read (read/bash) could otherwise surface it to the
	 * provider verbatim and undo that protection, so redact the key itself from
	 * obfuscated (provider-visible) output as a one-way secret.
	 */
	#setPlaceholderKey(key: string): void {
		this.#key = key;
		this.#replaceMappings.set(key, this.#generateSecretReplacement(key));
		this.#configuredSecretValues.add(key);
	}

	/** Resolve the placeholder key once, minting its self-redaction on first use. */
	#getKey(): string {
		let key = this.#key;
		if (key === undefined) {
			key = this.#keyProvider?.() ?? defaultPlaceholderKey();
			this.#keyProvider = undefined;
			this.#setPlaceholderKey(key);
		}
		return key;
	}

	/** Whether this pass will mint a keyed placeholder from a regex match. */
	#willMintRegexPlaceholder(secretValues: ReadonlySet<string>): boolean {
		for (const entry of this.#regexEntries) {
			if (entry.mode !== "obfuscate") continue;
			for (const value of secretValues) {
				entry.regex.lastIndex = 0;
				const matches = entry.regex.test(value);
				entry.regex.lastIndex = 0;
				if (matches) return true;
			}
		}
		return false;
	}

	hasSecrets(): boolean {
		return this.#hasAny;
	}

	/** Obfuscate all secrets in text. Bidirectional placeholders for obfuscate mode, one-way for replace. */
	obfuscate(text: string, sharedRegexSecretValues?: ReadonlySet<string>): string {
		if (!this.#hasAny) return text;
		this.#currentRegexSecretValues = this.collectRegexSecretValuesForObfuscation(text);
		for (const secretValue of sharedRegexSecretValues ?? []) {
			this.#currentRegexSecretValues.add(secretValue);
		}
		// Resolve a lazy key before the replace phase whenever this pass will mint
		// a regex placeholder. The key registers itself as a replace-mode secret;
		// resolving it later, while processing the regex match, would expose key
		// bytes already present in this same provider-visible input.
		if (this.#keyProvider !== undefined && this.#willMintRegexPlaceholder(this.#currentRegexSecretValues)) {
			this.#getKey();
		}
		let result = text;
		// `origin` runs parallel to `result` (one tag char per result char): "I" for
		// bytes carried from the INPUT (placeholders from a PRIOR obfuscate() call)
		// and "F" for bytes this call freshly inserted. The SDK obfuscates messages
		// in both convertToLlm and transformProviderContext, and prior-turn messages
		// re-enter every turn, so obfuscate() must be a fixed point: a regex must not
		// re-redact around a placeholder that arrived in the input (which would
		// corrupt a prior replacement marker, e.g. REDACTED -> REDACTEDDACTED).
		// Tracking by RANGE (not token value) keeps a fresh placeholder that happens
		// to equal a prior one (same secret seen raw again) eligible for cross-match.
		let origin = "I".repeat(text.length);
		// 1. Process replace-mode plain secrets
		for (const [secret, replacement] of [...this.#replaceMappings].sort((a, b) => b[0].length - a[0].length)) {
			({ text: result, origin } = this.#replaceOutsidePlaceholdersTracked(result, origin, secret, replacement, "I"));
		}
		for (const secretValue of this.#collectRegexSecretValues(result)) {
			this.#currentRegexSecretValues.add(secretValue);
		}
		for (const secretValue of this.#collectRegexSecretValuesAfterRegexReplacements(result, origin)) {
			this.#currentRegexSecretValues.add(secretValue);
		}
		for (const secretValue of sharedRegexSecretValues ?? []) {
			this.#currentRegexSecretValues.add(secretValue);
		}
		({ text: result, origin } = this.#stripUnsafeFriendlyPrefixes(result, origin));

		// 2. Process obfuscate-mode plain secrets
		for (const [secret, index] of [...this.#plainMappings].sort((a, b) => b[0].length - a[0].length)) {
			const mapping = this.#obfuscateMappings.get(index)!;
			({ text: result, origin } = this.#replaceOutsidePlaceholdersTracked(
				result,
				origin,
				secret,
				this.#placeholderForCurrentInput(mapping.placeholder),
				"F",
			));
		}

		// 3. Process regex entries — discover new matches
		for (const entry of this.#regexEntries) {
			entry.regex.lastIndex = 0;
			const matches = this.#collectRegexMatches(result, entry.regex, entry.mode, origin, entry.replacement);

			for (const match of matches) {
				if (entry.mode === "replace") {
					if (match.preserveGeneratedPlaceholders) {
						if (
							match.preserveInputPlaceholders &&
							entry.replacement === undefined &&
							match.inputPlaceholderOutsideChunkCount === 1 &&
							match.inputPlaceholderOutsideStart >= 0 &&
							origin
								.slice(
									match.inputPlaceholderOutsideStart,
									match.inputPlaceholderOutsideStart + match.inputPlaceholderOutside.length,
								)
								.includes("F") &&
							this.#generatedReplaceChunks.has(match.inputPlaceholderOutside)
						) {
							continue;
						}
						// Same greedy-spillover fixed point as the obfuscate branch below: when
						// the match only reached across a prior-call placeholder because the
						// placeholder's own value satisfies the regex, and the surrounding raw
						// bytes do not independently match, re-redacting those bytes drifts the
						// deterministic scramble across passes (e.g. `…#…#ZZJ5sotJ` →
						// `…#…#ZZpvsotJ`), invalidating prompt-cache prefixes despite no new
						// input. Leave the placeholder and its spillover verbatim — a fixed
						// point. Structurally-required bytes (placeholder value alone cannot
						// match) and independently-matching outside chunks still fall through to
						// the redaction below. Only prior-call (`origin "I"`) placeholders set
						// these flags, so first-pass redaction of genuinely new bytes is intact.
						if (
							match.inputPlaceholderInnerIndependentlyMatches &&
							!match.inputPlaceholderOutsideIndependentlyMatches
						) {
							continue;
						}
						let replaceEnd = match.end;
						let span = result.slice(match.start, replaceEnd);
						if (entry.replacement !== undefined) {
							const trailingChunk = trailingOutsidePreservedPlaceholderChunk(span, placeholder =>
								this.#isGeneratedPlaceholder(placeholder),
							);
							if (trailingChunk.length > 0 && entry.replacement.startsWith(trailingChunk)) {
								const trailingSuffix = entry.replacement.slice(trailingChunk.length);
								if (trailingSuffix.length > 0 && result.slice(replaceEnd).startsWith(trailingSuffix)) {
									replaceEnd += trailingSuffix.length;
									span = result.slice(match.start, replaceEnd);
								}
							}
						}
						// A custom replacement is a single redaction marker for the whole
						// match, so emit it once around the preserved placeholder rather
						// than per surrounding chunk (which duplicates it, e.g.
						// `api_key=***#…#api_key=***`). Without one, each surrounding chunk
						// gets its own length-matched fixed-point marker, checked in the
						// expanded scan context so marker bytes cannot re-match beside the
						// preserved placeholder on the next pass. The origin of any placeholder
						// PRESERVED inside `span` must survive verbatim — blanket-tagging the
						// whole redacted span "I" would relabel a same-call-fresh ("F")
						// placeholder as prior-call, wrongly triggering the spillover-skip
						// above for a LATER regex entry over content this call just redacted.
						const spanOrigin = origin.slice(match.start, replaceEnd);
						const redacted =
							entry.replacement !== undefined
								? redactWithFixedReplacementOutsidePlaceholders(
										span,
										spanOrigin,
										entry.replacement,
										placeholder => this.#isGeneratedPlaceholder(placeholder),
									)
								: this.#redactRegexMatchOutsidePlaceholders(span, spanOrigin, entry.regex, match.scanContext);
						result = replaceRange(result, match.start, replaceEnd, redacted.text);
						origin = replaceRange(origin, match.start, replaceEnd, redacted.origin);
					} else {
						const replacement = entry.replacement ?? match.defaultReplacement;
						if (replacement === undefined) {
							throw new Error("regex replace match missing a generated replacement");
						}
						result = replaceRange(result, match.start, match.end, replacement);
						origin = replaceRange(origin, match.start, match.end, "I".repeat(replacement.length));
					}
				} else {
					if (match.scanMatchLength < MIN_OBFUSCATE_SECRET_LEN) {
						// Tone down short regex matches to avoid obfuscating small
						// words/fragments. Measure the regex's own match length in the
						// canonical (placeholder-expanded) scan view, not the rewritten
						// source span, so the threshold reflects how much content the regex
						// actually matched.
						continue;
					}
					if (match.preserveInputPlaceholders) {
						// The match straddled a prior-call placeholder. When the placeholder's
						// own value already satisfies the regex on its own AND the surrounding
						// raw bytes do not independently match, those bytes are greedy spillover
						// (e.g. the trailing `A` in `SECRETUV→#…#A`): obfuscating them mints
						// fresh placeholders on re-obfuscation and drifts the provider-visible
						// history and prompt-cache prefix. Leave the placeholder atomic and the
						// spillover verbatim — a fixed point. Outside bytes are still obfuscated
						// when the placeholder value alone cannot match (they are structurally
						// part of the secret, e.g. an `api_key=` prefix the regex requires) or
						// when they independently match the regex on their own.
						if (
							match.inputPlaceholderInnerIndependentlyMatches &&
							!match.inputPlaceholderOutsideIndependentlyMatches
						) {
							continue;
						}
						const span = result.slice(match.start, match.end);
						const spanOrigin = origin.slice(match.start, match.end);
						const obfuscated = this.#obfuscateOutsidePlaceholdersTracked(span, spanOrigin, entry.friendlyName);
						result = replaceRange(result, match.start, match.end, obfuscated.text);
						origin = replaceRange(origin, match.start, match.end, obfuscated.origin);
						continue;
					}
					// obfuscate mode — get or create stable index
					let index = this.#findObfuscateIndex(match.canonicalValue);
					if (index === undefined) {
						index = this.#nextIndex++;
						const placeholder = this.#createPlaceholder(
							match.canonicalValue,
							entry.friendlyName,
							match.recursive,
						);
						this.#obfuscateMappings.set(index, { secret: match.canonicalValue, placeholder });
						this.#generatedPlaceholders.add(placeholder);
					}
					const mapping = this.#obfuscateMappings.get(index)!;
					const placeholder = this.#placeholderForCurrentInput(mapping.placeholder);
					result = replaceRange(result, match.start, match.end, placeholder);
					origin = replaceRange(origin, match.start, match.end, "F".repeat(placeholder.length));
				}
			}
			if (entry.mode === "replace") {
				for (const secretValue of this.#collectRegexSecretValues(result)) {
					this.#currentRegexSecretValues.add(secretValue);
				}
			}
		}
		({ text: result, origin } = this.#stabilizeReplaceRegexPlaceholderSpillover(result, origin));

		this.#currentRegexSecretValues = new Set();
		return result;
	}

	/** Deobfuscate keyed placeholders for provider output, tool-call arguments, replay, and display. */
	deobfuscate(text: string): string {
		return this.#deobfuscate(text);
	}

	// Reverse-direction counterpart to `#isGeneratedPlaceholder`'s guard: the
	// bare-alias fallback below intentionally accepts ANY prefix so a
	// placeholder minted under a renamed friendly name still deobfuscates
	// (see `#prefixIsSecretShaped`'s docstring for why), but unconditionally
	// stripping and ignoring an attacker-authored prefix would let a forged
	// token like `$$GITHUBPATABC123_<suffix-copied-from-any-real-placeholder>$$`
	// restore to that OTHER secret's raw value with no check at all — worse
	// than the obfuscate-direction leak, since deobfuscation is what feeds
	// tool-call arguments and provider-output restoration. Refuse the
	// fallback (leave the token as opaque, unresolved text) when the prefix
	// is itself secret-shaped; an exact full-token match is unaffected, since
	// that was minted by this instance and carries no forgery risk.
	#lookupLiveAlias(placeholder: string): { secret: string; recursive: boolean } | undefined {
		const direct = this.#deobfuscateMap.get(placeholder);
		if (direct !== undefined) return direct;
		const body = placeholder.slice(2, -2);
		const match = /^([A-Z0-9]+)_([A-Z0-9]{4,}(?::[ULCM])?)$/.exec(body);
		if (match === null || this.#prefixIsSecretShaped(match[1]!)) return undefined;
		return this.#deobfuscateMap.get(`$$${match[2]}$$`);
	}

	#deobfuscate(text: string): string {
		if (!this.#hasAny || !text.includes("$$")) return text;
		let result = text;
		for (;;) {
			let shouldContinue = false;
			const next = result.replace(PLACEHOLDER_RE, match => {
				const mapped = this.#lookupLiveAlias(match);
				if (mapped !== undefined) {
					shouldContinue ||= mapped.recursive;
					return mapped.secret;
				}
				return match;
			});
			if (next === result || !shouldContinue || !next.includes("$$")) return next;
			result = next;
		}
	}

	/** Deep-walk an object, deobfuscating string values for LIVE paths (keyed placeholders only). */
	deobfuscateObject<T>(obj: T): T {
		if (!this.#hasAny) return obj;
		return deepWalkStrings(obj, s => this.deobfuscate(s));
	}

	/** Deep-walk an object, obfuscating all string values. */
	obfuscateObject<T>(obj: T): T {
		if (!this.#hasAny) return obj;
		return deepWalkStrings(obj, s => this.obfuscate(s));
	}

	#generateReplacement(chunk: string): string {
		// Redact a per-chunk remainder to a marker that is a fixed point under
		// re-redaction on ANY obfuscator sharing the key, so persisted obfuscated text
		// — and the provider prompt-cache prefixes it anchors — never drifts across a
		// restart. The marker keeps the `Z`/`ZZ` sentinel prefix (already a fixed point
		// for <=2-char remainders) and, for longer remainders, a key-derived run that
		// depends ONLY on the key and length. A fresh obfuscator reproduces the
		// identical marker (so re-redacting it stays idempotent across restarts, where
		// the content-derived chunk plus the session-local `#generatedReplaceChunks`
		// were not), yet the run is unpredictable without the per-install key, so raw
		// remainder bytes that merely look sentinel-shaped (e.g. `ZZZZ`) cannot equal
		// the marker and are still redacted instead of passed through.
		const replacement =
			chunk.length <= 2
				? "Z".repeat(chunk.length)
				: `ZZ${buildKeyedReplacementRun(this.#getKey(), chunk.length - 2)}`;
		this.#generatedReplaceChunks.add(replacement);
		return replacement;
	}

	/**
	 * Replacement for a whole CONFIGURED secret value (a plain replace-mode entry
	 * or the redacted key). Unlike a per-chunk remainder redaction, the output
	 * must differ from the input so a value equal to the `Z`/`ZZ` sentinel is not
	 * emitted verbatim. A plain secret only matches its own literal, so the
	 * perturbed output stays a fixed point under re-obfuscation.
	 */
	#generateSecretReplacement(secret: string): string {
		const replacement = ensureDistinctReplacement(generateDeterministicReplacement(secret), secret);
		this.#generatedReplaceChunks.add(replacement);
		return replacement;
	}

	/**
	 * Replacement for a default (no custom replacement) regex match. The output must
	 * be a fixed point under re-obfuscation: a regex can re-match its own replacement,
	 * and a later obfuscate() pass would then re-redact it — at best churning the
	 * provider-visible text, at worst oscillating back to the raw matched value. The
	 * deterministic replacement already differs from most values, but it is
	 * all-alphanumeric and a regex may still match it, either directly (a `Z`/`ZZ`
	 * sentinel collision, or a class like `[A-Za-z0-9]+`) or only in context
	 * (lookbehind/lookahead/`\b`, e.g. `(?<=api=)[AZ]`). When it would re-match,
	 * search same-length candidates IN CONTEXT for one the regex does not re-match:
	 * that value is a stable fixed point and cannot re-leak. A single perturbation is
	 * not enough — it may also match (e.g. `B`, not `A`, for `Z|A`) — so the search
	 * tries further candidates before giving up. When no candidate avoids the regex (a
	 * pathological match-everything config such as `.`/`[\s\S]`), the content-hash
	 * deterministic value is NOT usable as a fallback: it will itself be re-matched on
	 * the next pass, and because it is derived from the bytes being replaced, rehashing
	 * those bytes (the marker itself, not the original secret) produces a DIFFERENT
	 * value — churning the redaction, and the provider prompt-cache prefix it anchors,
	 * across every re-obfuscation. Fall back instead to a marker that depends only
	 * on `this.#key` and the value's length, not its content, so re-matching and
	 * re-redacting it reproduces the IDENTICAL marker every time, which the
	 * pathological case requires since no value can escape the regex at all. This
	 * cannot reuse `#generateReplacement`'s own <=2-char branch directly: that
	 * branch is the fixed `Z`/`ZZ` sentinel, which is itself a value this fallback
	 * could be asked to replace (an input of exactly `Z` or `ZZ`), and returning it
	 * unchanged would ship the raw secret to the provider — the exact failure plain
	 * replace-mode secrets avoid via `ensureDistinctReplacement`. Neither
	 * `ensureDistinctReplacement`'s single-char flip NOR a length-changing marker is
	 * usable here: a pathological regex re-matches ANY same-length value, including
	 * a flipped one, so a value-dependent flip oscillates between the two forever;
	 * and a regex with no quantifier (matching one input character per match, e.g.
	 * `.`) re-scans a LONGER marker as several independent same-regex matches on the
	 * next pass, re-expanding each one — unbounded growth, not a fixed point. Use a
	 * SAME-LENGTH keyed run instead of the sentinel for <=2 chars: content-independent
	 * (so it is trivially its own fixed point once emitted) and no longer a public,
	 * install-independent constant, closing the specific guessable collision
	 * (`Z`/`ZZ`) the sentinel had. A same-length, content-independent marker cannot
	 * mathematically rule out equaling some pathological input by construction (the
	 * marker is itself a same-length string a match-everything regex also matches),
	 * but that residual case now requires guessing this install's private key rather
	 * than a universal constant — the same class of accepted risk
	 * `generateDeterministicReplacement`'s hash collision already carries for longer
	 * values.
	 * A regex that is UNCONDITIONALLY pathological for a length <= 2 — matching
	 * literally every candidate in isolation, independent of context, like `.`
	 * or `[\s\S]` — is now rejected at construction/config-load time instead
	 * (see `regexHasUnresolvableShortMatchFallback`), since for that narrow
	 * case the residual risk above is fully avoidable rather than merely
	 * unlikely. This branch, and the residual risk above, still applies to a
	 * length > 2 pathological config and to a length <= 2 pattern that is only
	 * pathological in a SPECIFIC match's surrounding context (the
	 * construction-time check tests the regex in isolation, not every context
	 * it could appear in).
	 */
	#generateRegexReplacement(value: string, regex: RegExp, context: RegexMatchContext): string {
		let replacement = generateDeterministicReplacement(value);
		// Verify in context, not just against the sentinel collision: the
		// deterministic replacement is all-alphanumeric and a context-sensitive regex
		// (lookbehind/lookahead/`\b`) can re-match it even when it differs from the
		// value, so a later pass would re-redact and could oscillate back to the raw
		// secret. Search for a candidate the regex does not re-match in place.
		if (replacement === value || regexRematchesInContext(replacement, regex, context)) {
			const stable = findNonMatchingReplacement(value, regex, context);
			// See docstring above: same-length keyed run for <=2 chars (never the
			// `Z`/`ZZ` sentinel, which a <=2 char value could itself be), otherwise
			// the ordinary keyed-run fallback #generateReplacement already uses.
			replacement =
				stable ??
				(value.length <= 2
					? buildKeyedReplacementRun(this.#getKey(), value.length)
					: this.#generateReplacement(value));
			regex.lastIndex = 0;
		}
		this.#generatedReplaceChunks.add(replacement);
		return replacement;
	}

	#generateRegexChunkReplacement(chunk: string, regex: RegExp, context: RegexMatchContext): string {
		let replacement = this.#generateReplacement(chunk);
		if (regexRematchesInContext(replacement, regex, context)) {
			const stable = findNonMatchingReplacement(chunk, regex, context);
			if (stable !== undefined) {
				replacement = stable;
				this.#generatedReplaceChunks.add(replacement);
			}
			regex.lastIndex = 0;
		}
		return replacement;
	}

	#redactRegexMatchOutsidePlaceholders(
		text: string,
		origin: string,
		regex: RegExp,
		context: RegexMatchContext,
	): { text: string; origin: string } {
		let scanCursor = context.start;
		return transformOutsidePlaceholdersTracked(
			text,
			origin,
			placeholder => this.#isGeneratedPlaceholder(placeholder),
			chunk => {
				const start = scanCursor;
				scanCursor += chunk.length;
				if (chunk.length === 0) return "";
				return this.#generateRegexChunkReplacement(chunk, regex, {
					text: context.text,
					start,
					end: scanCursor,
				});
			},
			placeholder => {
				scanCursor +=
					lookupFriendlyPlaceholderAlias(this.#deobfuscateMap, placeholder)?.secret.length ?? placeholder.length;
				return placeholder;
			},
		);
	}

	#stabilizeReplaceRegexPlaceholderSpillover(text: string, origin: string): { text: string; origin: string } {
		let result = text;
		let currentOrigin = origin;
		for (const entry of this.#regexEntries) {
			if (entry.mode !== "replace" || entry.replacement !== undefined) continue;
			entry.regex.lastIndex = 0;
			const matches = this.#collectRegexMatches(result, entry.regex, entry.mode, currentOrigin, entry.replacement);
			entry.regex.lastIndex = 0;
			for (const match of matches) {
				if (!match.preserveGeneratedPlaceholders) continue;
				if (
					match.preserveInputPlaceholders &&
					entry.replacement === undefined &&
					match.inputPlaceholderOutsideChunkCount === 1 &&
					match.inputPlaceholderOutsideStart >= 0 &&
					currentOrigin
						.slice(
							match.inputPlaceholderOutsideStart,
							match.inputPlaceholderOutsideStart + match.inputPlaceholderOutside.length,
						)
						.includes("F") &&
					this.#generatedReplaceChunks.has(match.inputPlaceholderOutside)
				) {
					continue;
				}
				if (match.inputPlaceholderInnerIndependentlyMatches && !match.inputPlaceholderOutsideIndependentlyMatches) {
					continue;
				}
				const span = result.slice(match.start, match.end);
				const spanOrigin = currentOrigin.slice(match.start, match.end);
				const redacted =
					entry.replacement !== undefined
						? redactWithFixedReplacementOutsidePlaceholders(span, spanOrigin, entry.replacement, placeholder =>
								this.#isGeneratedPlaceholder(placeholder),
							)
						: this.#redactRegexMatchOutsidePlaceholders(span, spanOrigin, entry.regex, match.scanContext);
				if (redacted.text === span) continue;
				result = replaceRange(result, match.start, match.end, redacted.text);
				currentOrigin = replaceRange(currentOrigin, match.start, match.end, redacted.origin);
			}
		}
		return { text: result, origin: currentOrigin };
	}

	/** Find the obfuscate index for a known secret value. */
	#findObfuscateIndex(secret: string): number | undefined {
		// Check plain mappings first
		const plainIndex = this.#plainMappings.get(secret);
		if (plainIndex !== undefined) return plainIndex;

		// Check regex-discovered mappings
		for (const [index, mapping] of this.#obfuscateMappings) {
			if (mapping.secret === secret) return index;
		}
		return undefined;
	}

	#createPlaceholder(secret: string, friendlyName?: string, recursive: boolean = false): string {
		const hint = inferCaseHint(secret);
		// Key the base on the EXACT secret value, never a case-folded form. The
		// case hint is only a model-visible label. If two distinct secrets that
		// differ solely by ASCII case shared one case-folded base, a provider that
		// saw one placeholder could swap the hint to synthesize the sibling
		// secret's keyed token, and live deobfuscation (provider output / tool-call
		// args) would restore a value that was never provider-visible. Exact-value
		// keying gives every secret an independent base, so a sibling token cannot
		// be derived without the per-install key.
		const baseKey = secret;
		// A friendly name that embeds a configured secret's literal (or matches a
		// configured regex pattern) would bake that secret straight into a
		// LEGITIMATE, exact-registered placeholder — later scans recognize the
		// whole token as already-generated on an EXACT match, before the
		// alias-fallback prefix check above ever runs, so the embedded secret
		// would never be scanned. Drop the label for this mint rather than risk
		// it; the secret still gets a bare (unprefixed) placeholder. The collision
		// check runs against the FULL normalized label — `sanitizeForCollisionCheck`,
		// not yet capped at `MAX_FRIENDLY_NAME_LEN` — so a secret longer than the
		// 32-char display cap (or one whose sanitized form exceeds it) still gets
		// caught: a truncated `requestedFriendlyName` can never contain a longer
		// secret's full sanitized form, so checking the truncated label would let
		// the secret's first 32 (post-cap) characters leak as an accepted prefix.
		const requestedFriendlyName = friendlyName ? sanitizeSecretFriendlyName(friendlyName) : undefined;
		const sanitizedFriendlyName =
			requestedFriendlyName !== undefined &&
			friendlyName !== undefined &&
			!this.#friendlyNameCollidesWithSecret(sanitizeForCollisionCheck(friendlyName), friendlyName, secret)
				? requestedFriendlyName
				: undefined;
		const preferredBase = this.#resolvePreferredPlaceholderBase(baseKey);
		const preferredPlaceholder = buildPlaceholder(hint, preferredBase, sanitizedFriendlyName);
		if (!this.#placeholderConflicts(preferredPlaceholder, secret)) {
			this.#registerDeobfuscationAlias(preferredPlaceholder, secret, recursive);
			return preferredPlaceholder;
		}

		for (let attempt = 1; ; attempt++) {
			const fallbackBase = this.#reserveFallbackPlaceholderBase(baseKey, attempt);
			const placeholder = buildPlaceholder(hint, fallbackBase, sanitizedFriendlyName);
			if (!this.#placeholderConflicts(placeholder, secret)) {
				this.#registerDeobfuscationAlias(placeholder, secret, recursive);
				return placeholder;
			}
		}
	}

	#resolvePreferredPlaceholderBase(baseKey: string): string {
		const existing = this.#placeholderBaseByKey.get(baseKey);
		if (existing !== undefined) return existing;

		for (let attempt = 0; ; attempt++) {
			const base =
				attempt === 0
					? buildHashBase(this.#getKey(), baseKey)
					: buildHashBase(this.#getKey(), `${baseKey}\0${attempt}`);
			const owner = this.#placeholderBaseOwners.get(base);
			if (owner !== undefined && owner !== baseKey) continue;
			this.#placeholderBaseOwners.set(base, baseKey);
			this.#placeholderBaseByKey.set(baseKey, base);
			return base;
		}
	}

	#reserveFallbackPlaceholderBase(baseKey: string, startAttempt: number): string {
		for (let attempt = startAttempt; ; attempt++) {
			const owner = `${baseKey}\0collision\0${attempt}`;
			const base = buildHashBase(this.#getKey(), `${baseKey}\0collision\0${attempt}`);
			if (this.#placeholderBaseOwners.has(base)) continue;
			this.#placeholderBaseOwners.set(base, owner);
			return base;
		}
	}

	#placeholderCollides(placeholder: string, secret: string): boolean {
		const existing = this.#deobfuscateMap.get(placeholder);
		return existing !== undefined && existing.secret !== secret;
	}

	// A friendly placeholder is only safe if BOTH its full token and its
	// friendly-name-independent alias are free (or already ours), AND the token
	// itself is not another configured secret's literal value. Without the
	// latter check, a placeholder minted for secret A that happens to equal
	// secret B's raw content passes silently: B's own plain-secret redaction
	// pass (sorted by length, run once per obfuscate() call) already completed
	// before A's placeholder existed in the text, so B is never redacted out of
	// it — A's placeholder becomes a verbatim, provider-visible copy of B.
	#placeholderConflicts(placeholder: string, secret: string): boolean {
		if (this.#placeholderCollides(placeholder, secret)) return true;
		if (this.#configuredSecretValues.has(placeholder) && placeholder !== secret) return true;
		const unprefixed = placeholderWithoutFriendlyName(placeholder);
		if (unprefixed === undefined) return false;
		if (this.#placeholderCollides(unprefixed, secret)) return true;
		return this.#configuredSecretValues.has(unprefixed) && unprefixed !== secret;
	}

	// A sanitized friendly name must not double as a live secret: it becomes a
	// verbatim, model-visible prefix on every placeholder minted for THIS
	// secret, baked in via an exact `#deobfuscateMap` entry rather than the
	// alias fallback — so it needs its own check independent of the scan-skip
	// alias guard in `#isGeneratedPlaceholder`. Reuses `#prefixIsSecretShaped`
	// for the sanitized-vs-sanitized comparisons (configured plain secrets,
	// every regex-discovered secret this instance has ever minted a
	// placeholder for) and the sanitized-label-vs-regex-pattern check, then
	// adds two label-specific checks `#prefixIsSecretShaped` cannot make: the
	// CURRENT secret being minted right now — which, on its first-ever mint,
	// is not yet in `#prefixIsSecretShaped`'s previously-discovered set, since
	// that set is only populated AFTER this call returns — normalized the
	// same way (catches, e.g., `friendlyName: "TOKABC123"` for a regex secret
	// whose literal match is `tok_abc123`, which the sanitized-name-vs-pattern
	// check misses when the pattern is case-sensitive/punctuated); and the RAW
	// (pre-sanitization) label against every configured regex pattern (catches
	// `friendlyName: "tok_abc123"` literally, which the SANITIZED label
	// `"TOKABC123"` could never match against that same case-sensitive
	// pattern). Any of these means the text is meant to be redacted, not
	// stamped unredacted onto every use of this secret.
	#collectRegexSecretValues(text: string): Set<string> {
		const values = new Set<string>();
		for (const entry of this.#regexEntries) {
			entry.regex.lastIndex = 0;
			for (;;) {
				const match = entry.regex.exec(text);
				if (match === null) break;
				if (match[0].length === 0) {
					entry.regex.lastIndex++;
					continue;
				}
				values.add(match[0]);
			}
			entry.regex.lastIndex = 0;
		}
		return values;
	}

	collectRegexSecretValuesForObfuscation(text: string): Set<string> {
		const values = this.#collectRegexSecretValues(text);
		let result = text;
		let origin = "I".repeat(text.length);
		for (const [secret, replacement] of [...this.#replaceMappings].sort((a, b) => b[0].length - a[0].length)) {
			({ text: result, origin } = this.#replaceOutsidePlaceholdersTracked(result, origin, secret, replacement, "I"));
		}
		for (const secretValue of this.#collectRegexSecretValues(result)) {
			values.add(secretValue);
		}
		for (const secretValue of this.#collectRegexSecretValuesAfterRegexReplacements(result, origin)) {
			values.add(secretValue);
		}
		return values;
	}

	#collectRegexSecretValuesAfterRegexReplacements(text: string, origin: string): Set<string> {
		const values = new Set<string>();
		let simulated = text;
		let simulatedOrigin = origin;
		for (const entry of this.#regexEntries) {
			if (entry.mode !== "replace") continue;
			entry.regex.lastIndex = 0;
			const matches = this.#collectRegexMatches(
				simulated,
				entry.regex,
				entry.mode,
				simulatedOrigin,
				entry.replacement,
			);
			entry.regex.lastIndex = 0;
			if (matches.length === 0) continue;
			for (const match of [...matches].sort((a, b) => b.start - a.start)) {
				const replacement = entry.replacement ?? match.defaultReplacement;
				if (replacement === undefined) continue;
				for (const secretValue of this.#collectRegexSecretValues(replacement)) {
					values.add(secretValue);
				}
				simulated = replaceRange(simulated, match.start, match.end, replacement);
				simulatedOrigin = replaceRange(simulatedOrigin, match.start, match.end, "I".repeat(replacement.length));
			}
			for (const secretValue of this.#collectRegexSecretValues(simulated)) {
				values.add(secretValue);
			}
		}
		return values;
	}

	#friendlyNameCollidesWithSecret(sanitizedName: string, rawName: string, secret: string): boolean {
		if (this.#prefixIsSecretShaped(sanitizedName)) return true;
		const sanitizedSecretValue = sanitizeForCollisionCheck(secret);
		if (sanitizedLabelCollidesWithSecret(sanitizedName, sanitizedSecretValue)) return true;
		for (const entry of this.#regexEntries) {
			entry.regex.lastIndex = 0;
			const matches = entry.regex.test(rawName);
			entry.regex.lastIndex = 0;
			if (matches) return true;
		}
		return false;
	}

	#placeholderForCurrentInput(placeholder: string): string {
		const unprefixed = placeholderWithoutFriendlyName(placeholder);
		if (unprefixed === undefined) return placeholder;
		const match = /^([A-Z0-9]+)_/.exec(placeholder.slice(2, -2));
		if (match === null || !this.#prefixIsSecretShaped(match[1]!)) return placeholder;
		return unprefixed;
	}

	#stripUnsafeFriendlyPrefixes(text: string, origin: string): { text: string; origin: string } {
		PLACEHOLDER_RE.lastIndex = 0;
		let result = "";
		let resultOrigin = "";
		let cursor = 0;
		for (;;) {
			const match = PLACEHOLDER_RE.exec(text);
			if (match === null) break;
			const placeholder = match[0];
			const unprefixed = placeholderWithoutFriendlyName(placeholder);
			const replacement = unprefixed !== undefined ? this.#placeholderForCurrentInput(placeholder) : placeholder;
			if (replacement === placeholder) {
				resumePlaceholderScanAfterRejectedCandidate(match);
				continue;
			}
			result += text.slice(cursor, match.index);
			resultOrigin += origin.slice(cursor, match.index);
			result += replacement;
			resultOrigin += origin[match.index]?.repeat(replacement.length) ?? "";
			cursor = match.index + placeholder.length;
		}
		result += text.slice(cursor);
		resultOrigin += origin.slice(cursor);
		return { text: result, origin: resultOrigin };
	}

	stripUnsafeFriendlyPlaceholderPrefixes(text: string, sharedRegexSecretValues: ReadonlySet<string>): string {
		const previousRegexSecretValues = this.#currentRegexSecretValues;
		this.#currentRegexSecretValues = new Set(sharedRegexSecretValues);
		try {
			return this.#stripUnsafeFriendlyPrefixes(text, "I".repeat(text.length)).text;
		} finally {
			this.#currentRegexSecretValues = previousRegexSecretValues;
		}
	}

	#registerDeobfuscationAlias(placeholder: string, secret: string, recursive: boolean): void {
		const existing = this.#deobfuscateMap.get(placeholder);
		if (existing === undefined || existing.secret === secret) {
			this.#deobfuscateMap.set(placeholder, { secret, recursive });
		}
		const unprefixed = placeholderWithoutFriendlyName(placeholder);
		if (unprefixed !== undefined) {
			const existingUnprefixed = this.#deobfuscateMap.get(unprefixed);
			if (existingUnprefixed === undefined || existingUnprefixed.secret === secret) {
				this.#deobfuscateMap.set(unprefixed, { secret, recursive });
			}
		}
	}

	// Whether an alnum-only, uppercase friendly-name-shaped prefix dropped from
	// a candidate placeholder token is itself something that should have been
	// redacted, rather than an arbitrary label: a sanitized form of a
	// configured plain secret's value, a sanitized form of any regex-
	// discovered secret's value this instance has ever minted a placeholder
	// for, or text a configured regex pattern matches directly. Shared by the
	// obfuscate-direction guard below and the deobfuscate-direction bare-alias
	// guard in `#deobfuscate` — both fall back to a friendly-name-independent
	// alias keyed only by the hash suffix, so both need the same defense
	// against a forged/attacker-chosen prefix.
	#prefixIsSecretShaped(prefix: string): boolean {
		for (const secretValue of this.#configuredSecretValues) {
			const sanitizedSecret = sanitizeForCollisionCheck(secretValue);
			if (sanitizedLabelCollidesWithSecret(prefix, sanitizedSecret)) return true;
		}
		for (const secretValue of this.#currentRegexSecretValues) {
			const sanitizedSecret = sanitizeForCollisionCheck(secretValue);
			if (sanitizedLabelCollidesWithSecret(prefix, sanitizedSecret)) return true;
		}
		for (const { secret } of this.#obfuscateMappings.values()) {
			const sanitizedSecret = sanitizeForCollisionCheck(secret);
			if (sanitizedLabelCollidesWithSecret(prefix, sanitizedSecret)) return true;
		}
		for (const entry of this.#regexEntries) {
			entry.regex.lastIndex = 0;
			const matches = entry.regex.test(prefix);
			entry.regex.lastIndex = 0;
			if (matches) return true;
		}
		return false;
	}

	// A placeholder is an exact match, or the friendly-name-independent bare
	// alias: needed so a placeholder minted under a NOW-renamed friendly name
	// (same secret, same key, different `secrets.yml` label) still round-trips
	// when older provider-visible text is re-scanned by a renamed-config
	// instance — the hash suffix is a keyed digest of the secret VALUE alone,
	// so a same-key instance recomputes it identically regardless of the
	// label. The dropped prefix is otherwise unconstrained text, though: an
	// attacker who has observed ANY live placeholder's hash suffix elsewhere
	// in the transcript could wrap it around a DIFFERENT real secret's
	// plaintext (or a normalized rendering of one) to make the whole token
	// look pre-redacted and smuggle that secret through untouched.
	// `#prefixIsSecretShaped` above guards against that, shared with the
	// deobfuscate-direction check in `#deobfuscate`.
	#isGeneratedPlaceholder(placeholder: string): boolean {
		if (this.#deobfuscateMap.has(placeholder)) return true;
		const match = /^([A-Z0-9]+)_([A-Z0-9]{4,}(?::[ULCM])?)$/.exec(placeholder.slice(2, -2));
		if (match === null) return false;
		if (this.#prefixIsSecretShaped(match[1]!)) return false;
		return this.#deobfuscateMap.has(`$$${match[2]}$$`);
	}

	// Replace `search` with `replacement` outside known generated placeholders while
	// maintaining a parallel `origin` tag string (one char per result char): kept
	// bytes keep their tag, inserted `replacement` bytes get `tag`, and preserved
	// placeholder spans keep their original tags. Lets later passes tell prior-call
	// placeholders ("I") from ones freshly inserted this call ("F") by RANGE.
	#replaceOutsidePlaceholdersTracked(
		text: string,
		origin: string,
		search: string,
		replacement: string,
		tag: string,
	): { text: string; origin: string } {
		if (search.length === 0) return { text, origin };
		PLACEHOLDER_RE.lastIndex = 0;
		let outText = "";
		let outOrigin = "";
		let pending = 0;
		const emitChunk = (from: number, to: number): void => {
			let last = from;
			let idx = text.indexOf(search, from);
			while (idx !== -1 && idx + search.length <= to) {
				outText += text.slice(last, idx) + replacement;
				outOrigin += origin.slice(last, idx) + tag.repeat(replacement.length);
				last = idx + search.length;
				idx = text.indexOf(search, last);
			}
			outText += text.slice(last, to);
			outOrigin += origin.slice(last, to);
		};
		for (;;) {
			const match = PLACEHOLDER_RE.exec(text);
			if (match === null) break;
			if (!(this.#isGeneratedPlaceholder(match[0]) && match[0] !== search)) {
				resumePlaceholderScanAfterRejectedCandidate(match);
				continue;
			}
			emitChunk(pending, match.index);
			outText += match[0];
			outOrigin += origin.slice(match.index, match.index + match[0].length);
			pending = match.index + match[0].length;
		}
		emitChunk(pending, text.length);
		return { text: outText, origin: outOrigin };
	}

	#placeholderForRegexChunk(secret: string, friendlyName: string | undefined): string {
		let index = this.#findObfuscateIndex(secret);
		if (index === undefined) {
			index = this.#nextIndex++;
			const placeholder = this.#createPlaceholder(secret, friendlyName);
			this.#obfuscateMappings.set(index, { secret, placeholder });
			this.#generatedPlaceholders.add(placeholder);
		}
		return this.#placeholderForCurrentInput(this.#obfuscateMappings.get(index)!.placeholder);
	}

	#obfuscateOutsidePlaceholdersTracked(
		text: string,
		origin: string,
		friendlyName: string | undefined,
	): { text: string; origin: string } {
		PLACEHOLDER_RE.lastIndex = 0;
		let outText = "";
		let outOrigin = "";
		let pending = 0;
		const emitChunk = (from: number, to: number): void => {
			if (from >= to) return;
			const placeholder = this.#placeholderForRegexChunk(text.slice(from, to), friendlyName);
			outText += placeholder;
			outOrigin += "F".repeat(placeholder.length);
		};
		for (;;) {
			const match = PLACEHOLDER_RE.exec(text);
			if (match === null) break;
			if (!this.#isGeneratedPlaceholder(match[0])) {
				resumePlaceholderScanAfterRejectedCandidate(match);
				continue;
			}
			emitChunk(pending, match.index);
			outText += match[0];
			outOrigin += origin.slice(match.index, match.index + match[0].length);
			pending = match.index + match[0].length;
		}
		emitChunk(pending, text.length);
		return { text: outText, origin: outOrigin };
	}

	#knownPlaceholderRanges(text: string): Array<{ start: number; end: number }> {
		PLACEHOLDER_RE.lastIndex = 0;
		const ranges: Array<{ start: number; end: number }> = [];
		for (;;) {
			const match = PLACEHOLDER_RE.exec(text);
			if (match === null) break;
			if (this.#isGeneratedPlaceholder(match[0])) {
				ranges.push({ start: match.index, end: match.index + match[0].length });
			} else {
				resumePlaceholderScanAfterRejectedCandidate(match);
			}
		}
		return ranges;
	}

	#collectRegexMatches(
		text: string,
		regex: RegExp,
		mode: "obfuscate" | "replace",
		origin: string,
		replacement: string | undefined,
	): Array<{
		start: number;
		end: number;
		value: string;
		canonicalValue: string;
		scanMatchLength: number;
		recursive: boolean;
		preserveGeneratedPlaceholders: boolean;
		preserveInputPlaceholders: boolean;
		inputPlaceholderOutside: string;
		inputPlaceholderOutsideIndependentlyMatches: boolean;
		inputPlaceholderOutsideStart: number;
		inputPlaceholderOutsideChunkCount: number;
		inputPlaceholderInnerIndependentlyMatches: boolean;
		defaultReplacement: string | undefined;
		scanContext: RegexMatchContext;
	}> {
		const knownPlaceholderRanges = this.#knownPlaceholderRanges(text);
		const regexScan = buildReplaceRegexScan(text, knownPlaceholderRanges, this.#deobfuscateMap);
		const scanText = regexScan.text;
		regex.lastIndex = 0;
		const matches: Array<{
			start: number;
			end: number;
			value: string;
			canonicalValue: string;
			scanMatchLength: number;
			recursive: boolean;
			preserveGeneratedPlaceholders: boolean;
			preserveInputPlaceholders: boolean;
			inputPlaceholderOutside: string;
			inputPlaceholderOutsideIndependentlyMatches: boolean;
			inputPlaceholderOutsideStart: number;
			inputPlaceholderOutsideChunkCount: number;
			inputPlaceholderInnerIndependentlyMatches: boolean;
			defaultReplacement: string | undefined;
			scanContext: RegexMatchContext;
		}> = [];
		for (;;) {
			const match = regex.exec(scanText);
			if (match === null) break;
			if (match[0].length === 0) {
				regex.lastIndex++;
				continue;
			}
			let start = match.index;
			let end = match.index + match[0].length;
			let scanMatchLength = match[0].length;
			let scanMatchValue = match[0];
			let canonicalValue = "";
			let recursive = false;
			let preserveGeneratedPlaceholders = false;
			let preserveInputPlaceholders = false;
			let inputPlaceholderOutside = "";
			let inputPlaceholderOutsideIndependentlyMatches = false;
			let inputPlaceholderOutsideStart = -1;
			let inputPlaceholderOutsideChunkCount = 0;
			let inputPlaceholderInnerIndependentlyMatches = false;

			let mapped = mapReplaceRegexMatch(regexScan.segments, start, end);
			if (mapped.partialPlaceholderCut) {
				// The match straddles a generated placeholder (its boundary falls inside
				// the secret's expanded value). Rewriting across the token drops bytes
				// (obfuscate) or drifts the redaction across re-obfuscation passes
				// (replace), so the cut secret must stay as its existing placeholder.
				// But wholly-outside bytes on either side of the placeholder are still
				// provider-visible content covered by the regex. Probe the prefix against
				// the full expanded scan text so right-hand context supplied by the
				// placeholder still satisfies lookahead/alternatives, then clamp the
				// accepted match to the prefix boundary. If no prefix is available, redact
				// the outside suffix that was covered by the full-context match. Every
				// resume point computed below is chained through
				// `extendPastAdjacentPlaceholders`: a resume position that lands exactly on
				// the START of ANOTHER placeholder must skip that one too before a fresh
				// `regex.exec` attempt runs there, so a run of adjacent placeholders resolves
				// identically whether its LEADING member is raw text this call is about to
				// placeholder or is already a placeholder from a prior call/pass (see that
				// helper's doc for the cross-call drift this prevents).
				const cutResumeIndex = mapped.cutResumeIndex;
				const prefixScanEnd = mapped.firstPlaceholderScanStart;
				let handledOutside = false;
				if (prefixScanEnd > match.index) {
					regex.lastIndex = match.index;
					const prefixMatch = regex.exec(scanText);
					if (prefixMatch !== null && prefixMatch[0].length > 0 && prefixMatch.index < prefixScanEnd) {
						const prefixStart = prefixMatch.index;
						const prefixEnd = Math.min(prefixMatch.index + prefixMatch[0].length, prefixScanEnd);
						const prefixMapped = mapReplaceRegexMatch(regexScan.segments, prefixStart, prefixEnd);
						if (!prefixMapped.partialPlaceholderCut && prefixEnd > prefixStart) {
							start = prefixStart;
							end = prefixEnd;
							scanMatchValue = scanText.slice(prefixStart, prefixEnd);
							// Keep the full match length in the expanded scan view (not the
							// clamped prefix length) — the short-match guard below measures the
							// regex's own match length, so a full-size match with a short
							// outside-prefix remainder must not be undercounted as too short,
							// matching the suffix-clamp branch below.
							scanMatchLength = match[0].length;
							mapped = prefixMapped;
							regex.lastIndex = extendPastAdjacentPlaceholders(regexScan.segments, prefixEnd);
							handledOutside = true;
						}
					}
				}
				if (!handledOutside && cutResumeIndex < end) {
					const suffixStart = cutResumeIndex;
					const suffixEnd = end;
					const suffixMapped = mapReplaceRegexMatch(regexScan.segments, suffixStart, suffixEnd);
					if (!suffixMapped.partialPlaceholderCut) {
						start = suffixStart;
						end = suffixEnd;
						scanMatchValue = scanText.slice(suffixStart, suffixEnd);
						scanMatchLength = match[0].length;
						mapped = suffixMapped;
						regex.lastIndex = extendPastAdjacentPlaceholders(regexScan.segments, suffixEnd);
						handledOutside = true;
					}
				}
				if (!handledOutside) {
					regex.lastIndex = extendPastAdjacentPlaceholders(regexScan.segments, cutResumeIndex);
					continue;
				}
			}
			// Scan-space coordinates of the match (placeholders expanded). The default
			// redaction's fixed-point check must run against this expanded view — the
			// view re-obfuscation actually scans — not the literal `#…#` text, or a
			// redaction adjacent to a placeholder (e.g. an outside prefix before a cut
			// secret) could drift when the placeholder expands and connects to it.
			const scanMatchStart = start;
			const scanMatchEnd = end;
			let defaultReplacement: string | undefined;
			start = mapped.start;
			end = mapped.end;
			preserveGeneratedPlaceholders = mapped.preserveGeneratedPlaceholders;
			// A match overlapping a placeholder that arrived in the INPUT (origin tag
			// "I" — generated by a PRIOR obfuscate() call) must preserve that
			// placeholder atomically so repeated obfuscation stays a fixed point. If
			// raw bytes surround it, they still need redaction; branch-specific
			// replacement below keeps prior placeholders while covering the
			// non-placeholder chunks.
			const overlapsInputPlaceholder = knownPlaceholderRanges.some(
				range => start < range.end && end > range.start && origin[range.start] === "I",
			);
			preserveInputPlaceholders = overlapsInputPlaceholder;
			if (overlapsInputPlaceholder) {
				const firstOutside = firstOutsidePlaceholderRange(start, end, knownPlaceholderRanges);
				if (
					mode === "replace" &&
					replacement !== undefined &&
					firstOutside !== undefined &&
					text.slice(firstOutside.start, firstOutside.start + replacement.length) === replacement
				) {
					const expandedEnd = firstOutside.start + replacement.length;
					if (expandedEnd > end) {
						regex.lastIndex = Math.max(regex.lastIndex, match.index + match[0].length + expandedEnd - end);
						end = expandedEnd;
					}
				}
				inputPlaceholderOutside = textOutsidePlaceholderRanges(text, start, end, knownPlaceholderRanges);
				inputPlaceholderOutsideStart =
					firstOutsidePlaceholderRange(start, end, knownPlaceholderRanges)?.start ?? -1;
				inputPlaceholderOutsideChunkCount = countOutsidePlaceholderRanges(start, end, knownPlaceholderRanges);
				if (inputPlaceholderOutside.length === 0) continue;
				const resumeIndex = regex.lastIndex;
				// Test each outside chunk in isolation rather than the concatenation of
				// all of them: concatenating chunks that sit on either side of the
				// placeholder erases the `#…#` token boundary between them (e.g. a
				// prefix "ABCDEFGH" that independently matches `\b[A-Z]{8}\b` next to a
				// placeholder, followed by a raw "I" suffix, concatenates to "ABCDEFGHI"
				// — which does NOT match, since the boundary the placeholder provided is
				// gone). That false negative would leave a genuinely independent,
				// secret-shaped chunk unredacted. Each chunk is tested in BOTH its real
				// literal-token context (where the token's own non-word boundary can
				// complete a boundary-sensitive pattern) and the EXPANDED scan context —
				// the same view re-obfuscation's own regex scan runs against — so a
				// lookbehind/lookahead that only resolves once the neighboring
				// placeholder is expanded (e.g. `(?<=ABCDEFGH)SECRET` beside a
				// placeholder for `ABCDEFGH`) also counts as an independent match.
				inputPlaceholderOutsideIndependentlyMatches = outsidePlaceholderRangesAnyIndependentlyMatch(
					text,
					scanText,
					regexScan.segments,
					start,
					end,
					knownPlaceholderRanges,
					regex,
				);
				// Whether the placeholder's own (deobfuscated) value satisfies the regex
				// with the surrounding raw bytes dropped. When it does, those raw bytes
				// are greedy spillover the match never needed (e.g. the trailing `A` in
				// `SECRETUV→#…#A`); obfuscating them on re-obfuscation drifts the
				// provider-visible history and prompt-cache prefix. When it does NOT
				// (e.g. `api_key=` literal that the placeholder value alone cannot match),
				// the outside bytes are structurally required and must be obfuscated.
				const innerText = placeholderInnerText(text, start, end, knownPlaceholderRanges, this.#deobfuscateMap);
				regex.lastIndex = 0;
				inputPlaceholderInnerIndependentlyMatches = innerText.length > 0 && regex.test(innerText);
				regex.lastIndex = resumeIndex;
			}
			if (mode === "replace") {
				canonicalValue = scanMatchValue;
				recursive = mapped.recursive;
			} else {
				const overlappingRanges = knownPlaceholderRanges.filter(range => start < range.end && end > range.start);
				const containedByPlaceholder = overlappingRanges.some(range => start >= range.start && end <= range.end);
				if (containedByPlaceholder) {
					continue;
				}
				const canonical = deobfuscateGeneratedPlaceholderRanges(
					text,
					start,
					end,
					knownPlaceholderRanges,
					this.#deobfuscateMap,
				);
				canonicalValue = canonical.text;
				recursive = canonical.recursive;
			}

			const scanContext = {
				text: scanText,
				start: scanMatchStart,
				end: scanMatchEnd,
			};
			if (mode === "replace" && replacement === undefined && !preserveGeneratedPlaceholders) {
				const savedLastIndex = regex.lastIndex;
				defaultReplacement = this.#generateRegexReplacement(scanMatchValue, regex, scanContext);
				regex.lastIndex = savedLastIndex;
			}
			matches.push({
				start,
				end,
				value: text.slice(start, end),
				defaultReplacement,
				canonicalValue,
				scanMatchLength,
				recursive,
				preserveGeneratedPlaceholders,
				preserveInputPlaceholders,
				inputPlaceholderOutside,
				inputPlaceholderOutsideIndependentlyMatches,
				inputPlaceholderOutsideStart,
				inputPlaceholderOutsideChunkCount,
				inputPlaceholderInnerIndependentlyMatches,
				scanContext,
			});
		}
		return matches.reverse();
	}
}

// ═══════════════════════════════════════════════════════════════════════════
// Display restore (inbound, persisted/provider → local display)
// ═══════════════════════════════════════════════════════════════════════════

/**
 * Restore secret placeholders for local display. Only message kinds the model
 * itself authored from obfuscated context carry placeholders — assistant
 * content and the LLM-written branch/compaction summaries. User, developer, and
 * tool-result messages are persisted with their literal text, so operator-authored
 * placeholder-shaped text must survive untouched; those roles are never walked.
 */
export function deobfuscateSessionContext(
	sessionContext: SessionContext,
	obfuscator: SecretObfuscator | undefined,
): SessionContext {
	if (!obfuscator?.hasSecrets()) return sessionContext;
	const messages = deobfuscateAgentMessages(obfuscator, sessionContext.messages);
	return messages === sessionContext.messages ? sessionContext : { ...sessionContext, messages };
}

export function deobfuscateAgentMessages(obfuscator: SecretObfuscator, messages: AgentMessage[]): AgentMessage[] {
	const deob = (text: string): string => obfuscator.deobfuscate(text);
	let changed = false;
	const result = messages.map((message): AgentMessage => {
		switch (message.role) {
			case "assistant": {
				const content = deobfuscateAssistantContent(obfuscator, message.content);
				if (content === message.content) return message;
				changed = true;
				return { ...message, content };
			}
			case "branchSummary": {
				const summary = deob(message.summary);
				if (summary === message.summary) return message;
				changed = true;
				return { ...message, summary };
			}
			case "compactionSummary": {
				const summary = deob(message.summary);
				const shortSummary = message.shortSummary === undefined ? undefined : deob(message.shortSummary);
				const blocks = message.blocks === undefined ? undefined : deobfuscateTextBlocks(obfuscator, message.blocks);
				if (summary === message.summary && shortSummary === message.shortSummary && blocks === message.blocks) {
					return message;
				}
				changed = true;
				return { ...message, summary, shortSummary, blocks };
			}
			default:
				return message;
		}
	});
	return changed ? result : messages;
}

/**
 * Restore placeholders in assistant content: visible text and tool-call
 * arguments/intent/rawBlock. Thinking and signatures are opaque
 * provider-replay/hidden-reasoning data and pass through byte-identical.
 */
export function deobfuscateAssistantContent(
	obfuscator: SecretObfuscator,
	content: AssistantMessage["content"],
): AssistantMessage["content"] {
	if (!obfuscator.hasSecrets()) return content;
	const deob = (text: string): string => obfuscator.deobfuscate(text);
	let changed = false;
	const result = content.map((block): AssistantMessage["content"][number] => {
		if (block.type === "text") {
			const text = deob(block.text);
			if (text === block.text) return block;
			changed = true;
			return { ...block, text };
		}

		if (block.type === "toolCall") {
			const args = deobfuscateToolArguments(obfuscator, block.arguments);
			const intent = block.intent === undefined ? undefined : deob(block.intent);
			const rawBlock = block.rawBlock === undefined ? undefined : deob(block.rawBlock);
			if (args === block.arguments && intent === block.intent && rawBlock === block.rawBlock) return block;
			changed = true;
			return { ...block, arguments: args, intent, rawBlock };
		}
		return block;
	});
	return changed ? result : content;
}

/**
 * Restore placeholders inside a tool call's arguments. Arguments are arbitrary
 * model-authored JSON, so tool-call arguments are the ONLY place a recursive
 * JSON walk runs.
 */
export function deobfuscateToolArguments(
	obfuscator: SecretObfuscator,
	args: Record<string, unknown>,
): Record<string, unknown> {
	if (!obfuscator.hasSecrets()) return args;
	return mapJsonStrings(args as JsonValue, s => obfuscator.deobfuscate(s)) as Record<string, unknown>;
}

/** Redact secrets inside a tool call's arguments (same JSON-walk exception as {@link deobfuscateToolArguments}). */
export function obfuscateToolArguments(
	obfuscator: SecretObfuscator,
	args: Record<string, unknown>,
	sharedRegexSecretValues?: ReadonlySet<string>,
): Record<string, unknown> {
	if (!obfuscator.hasSecrets()) return args;
	const regexSecretValues = sharedRegexSecretValues ?? collectJsonRegexSecretValues(obfuscator, args as JsonValue);
	return mapJsonStrings(args as JsonValue, s => obfuscator.obfuscate(s, regexSecretValues)) as Record<string, unknown>;
}

// ═══════════════════════════════════════════════════════════════════════════
// Outbound obfuscation (local → provider)
// ═══════════════════════════════════════════════════════════════════════════

type UserFacingMessage = Extract<Message, { role: "user" | "developer" | "toolResult" }>;

/** Obfuscate `text` blocks of a content array; image and other blocks pass through. */
function obfuscateTextBlocks(
	obfuscator: SecretObfuscator,
	content: (TextContent | ImageContent)[],
	sharedRegexSecretValues?: ReadonlySet<string>,
): (TextContent | ImageContent)[] {
	let changed = false;
	const result = content.map((block): TextContent | ImageContent => {
		if (block.type !== "text") return block;
		const text = obfuscator.obfuscate(block.text, sharedRegexSecretValues);
		if (text === block.text) return block;
		changed = true;
		return { ...block, text };
	});
	return changed ? result : content;
}

/** Restore placeholders in `text` blocks of a content array; image and other blocks pass through. */
function deobfuscateTextBlocks(
	obfuscator: SecretObfuscator,
	content: (TextContent | ImageContent)[],
): (TextContent | ImageContent)[] {
	let changed = false;
	const result = content.map((block): TextContent | ImageContent => {
		if (block.type !== "text") return block;
		const text = obfuscator.deobfuscate(block.text);
		if (text === block.text) return block;
		changed = true;
		return { ...block, text };
	});
	return changed ? result : content;
}

/**
 * Re-obfuscate assistant content before it returns to a provider after session
 * restoration, removing friendly prefixes made unsafe by this batch. A changed
 * thinking block loses its byte-bound replay signature.
 */
function obfuscateAssistantContentForReplay(
	obfuscator: SecretObfuscator,
	content: AssistantMessage["content"],
	sharedRegexSecretValues: ReadonlySet<string>,
): AssistantMessage["content"] {
	const obfuscate = (text: string): string =>
		obfuscator.stripUnsafeFriendlyPlaceholderPrefixes(
			obfuscator.obfuscate(text, sharedRegexSecretValues),
			sharedRegexSecretValues,
		);
	let changed = false;
	const result = content.map((block): AssistantMessage["content"][number] => {
		if (block.type === "text") {
			const text = obfuscate(block.text);
			if (text === block.text) return block;
			changed = true;
			return { ...block, text };
		}
		if (block.type === "thinking") {
			const thinking = obfuscate(block.thinking);
			if (thinking === block.thinking) return block;
			changed = true;
			return { ...block, thinking, thinkingSignature: undefined };
		}
		if (block.type === "toolCall") {
			const args = mapJsonStrings(block.arguments as JsonValue, obfuscate) as Record<string, unknown>;
			const intent = block.intent === undefined ? undefined : obfuscate(block.intent);
			const rawBlock = block.rawBlock === undefined ? undefined : obfuscate(block.rawBlock);
			if (args === block.arguments && intent === block.intent && rawBlock === block.rawBlock) return block;
			changed = true;
			return { ...block, arguments: args, intent, rawBlock };
		}
		return block;
	});
	return changed ? result : content;
}

function collectMessageRegexSecretValues(obfuscator: SecretObfuscator, messages: Message[]): Set<string> {
	const values = new Set<string>();
	const addText = (text: string | undefined): void => {
		if (text === undefined) return;
		for (const value of obfuscator.collectRegexSecretValuesForObfuscation(text)) {
			values.add(value);
		}
	};
	for (const message of messages) {
		if (message.role === "assistant") {
			for (const block of message.content) {
				if (block.type === "text") addText(block.text);
				else if (block.type === "thinking") addText(block.thinking);
				else if (block.type === "toolCall") {
					for (const value of collectJsonRegexSecretValues(obfuscator, block.arguments as JsonValue)) {
						values.add(value);
					}
					addText(block.intent);
					addText(block.rawBlock);
				}
			}
			continue;
		}
		if (
			message.role !== "user" &&
			message.role !== "toolResult" &&
			!(message.role === "developer" && message.attribution === "user")
		) {
			continue;
		}
		const target = message as UserFacingMessage;
		if (typeof target.content === "string") {
			addText(target.content);
			continue;
		}
		for (const block of target.content) {
			if (block.type === "text") addText(block.text);
		}
	}
	return values;
}

/**
 * Redact secrets from outbound messages. User messages, tool results, and
 * user-authored developer messages (e.g. `@file` mentions) are obfuscated.
 * Assistant replay content is re-obfuscated too, because session restoration
 * expands keyed placeholders locally before the next provider request. Inline
 * image bytes are never walked.
 */
export function obfuscateMessages(obfuscator: SecretObfuscator, messages: Message[]): Message[] {
	if (!obfuscator.hasSecrets()) return messages;
	const sharedRegexSecretValues = collectMessageRegexSecretValues(obfuscator, messages);
	let changed = false;
	const result = messages.map((message): Message => {
		if (
			message.role !== "user" &&
			message.role !== "toolResult" &&
			!(message.role === "developer" && message.attribution === "user")
		) {
			if (message.role !== "assistant") return message;
			const content = obfuscateAssistantContentForReplay(obfuscator, message.content, sharedRegexSecretValues);
			if (content === message.content) return message;
			changed = true;
			return { ...message, content };
		}
		const target = message as UserFacingMessage;
		if (typeof target.content === "string") {
			const content = obfuscator.obfuscate(target.content, sharedRegexSecretValues);
			if (content === target.content) return message;
			changed = true;
			return { ...target, content } as Message;
		}
		const content = obfuscateTextBlocks(obfuscator, target.content, sharedRegexSecretValues);
		if (content === target.content) return message;
		changed = true;
		return { ...target, content } as Message;
	});
	return changed ? result : messages;
}

/**
 * Redact outbound provider context. Only conversation messages are rewritten;
 * the static system prompt and tool schemas pass through unchanged.
 */
export function obfuscateProviderContext(obfuscator: SecretObfuscator | undefined, context: Context): Context {
	if (!obfuscator?.hasSecrets()) return context;
	const messages = obfuscateMessages(obfuscator, context.messages);
	return messages === context.messages ? context : { ...context, messages };
}

// ═══════════════════════════════════════════════════════════════════════════
// Helpers
// ═══════════════════════════════════════════════════════════════════════════

// Like the untracked walk, but threads a parallel `origin` tag string through:
// preserved placeholder spans keep their existing origin tag (so a
// same-call-fresh "F" placeholder is never relabeled prior-call "I", and vice
// versa), while `transform`'s output — always freshly generated or redacted
// content in both callers below — is tagged "I" (it must not be re-matched as
// though it arrived in the input, mirroring plain-secret replacement tagging).
function transformOutsidePlaceholdersTracked(
	text: string,
	origin: string,
	shouldSkipPlaceholder: (placeholder: string) => boolean,
	transform: (chunk: string) => string,
	preservePlaceholder?: (placeholder: string) => string,
): { text: string; origin: string } {
	PLACEHOLDER_RE.lastIndex = 0;
	let result = "";
	let resultOrigin = "";
	let pendingIndex = 0;
	for (;;) {
		const match = PLACEHOLDER_RE.exec(text);
		if (match === null) break;
		if (!shouldSkipPlaceholder(match[0])) {
			resumePlaceholderScanAfterRejectedCandidate(match);
			continue;
		}
		const transformed = transform(text.slice(pendingIndex, match.index));
		result += transformed;
		resultOrigin += "I".repeat(transformed.length);
		const preserved = preservePlaceholder ? preservePlaceholder(match[0]) : match[0];
		result += preserved;
		resultOrigin += origin.slice(match.index, match.index + match[0].length);
		pendingIndex = match.index + match[0].length;
	}
	const trailing = transform(text.slice(pendingIndex));
	result += trailing;
	resultOrigin += "I".repeat(trailing.length);
	return { text: result, origin: resultOrigin };
}

function trailingOutsidePreservedPlaceholderChunk(
	text: string,
	shouldPreservePlaceholder: (placeholder: string) => boolean,
): string {
	PLACEHOLDER_RE.lastIndex = 0;
	let pendingIndex = 0;
	let sawPlaceholder = false;
	for (;;) {
		const match = PLACEHOLDER_RE.exec(text);
		if (match === null) break;
		if (!shouldPreservePlaceholder(match[0])) {
			resumePlaceholderScanAfterRejectedCandidate(match);
			continue;
		}
		sawPlaceholder = true;
		pendingIndex = match.index + match[0].length;
	}
	return sawPlaceholder ? text.slice(pendingIndex) : "";
}

function buildReplaceRegexScan(
	text: string,
	ranges: ReadonlyArray<{ start: number; end: number }>,
	deobfuscateMap: ReadonlyMap<string, { secret: string; recursive: boolean }>,
): ReplaceRegexScan {
	let scanText = "";
	let cursor = 0;
	const segments: RegexScanSegment[] = [];
	const appendSegment = (
		value: string,
		textStart: number,
		textEnd: number,
		generatedPlaceholder: boolean,
		recursive: boolean,
	) => {
		if (value.length === 0) return;
		const scanStart = scanText.length;
		scanText += value;
		segments.push({
			scanStart,
			scanEnd: scanStart + value.length,
			textStart,
			textEnd,
			generatedPlaceholder,
			recursive,
		});
	};

	for (const range of ranges) {
		appendSegment(text.slice(cursor, range.start), cursor, range.start, false, false);
		const placeholder = text.slice(range.start, range.end);
		const mapping = lookupFriendlyPlaceholderAlias(deobfuscateMap, placeholder);
		appendSegment(mapping?.secret ?? placeholder, range.start, range.end, true, mapping?.recursive ?? false);
		cursor = range.end;
	}
	appendSegment(text.slice(cursor), cursor, text.length, false, false);

	return { text: scanText, segments };
}

function mapReplaceRegexMatch(
	segments: ReadonlyArray<RegexScanSegment>,
	scanStart: number,
	scanEnd: number,
): {
	start: number;
	end: number;
	recursive: boolean;
	preserveGeneratedPlaceholders: boolean;
	partialPlaceholderCut: boolean;
	cutResumeIndex: number;
	firstPlaceholderScanStart: number;
} {
	const startSegment = findScanSegment(segments, scanStart);
	const endSegment = findScanSegment(segments, scanEnd - 1);
	const start = startSegment.generatedPlaceholder
		? startSegment.textStart
		: startSegment.textStart + (scanStart - startSegment.scanStart);
	const end = endSegment.generatedPlaceholder
		? endSegment.textEnd
		: endSegment.textStart + (scanEnd - endSegment.scanStart);
	// A match boundary that falls strictly inside a generated placeholder's
	// expanded value cuts the underlying secret: the snap above pulls the span out
	// to the whole `#…#` token, so the obfuscate path can leave it alone instead of
	// consuming a partial placeholder expansion.
	const partialPlaceholderCut =
		(startSegment.generatedPlaceholder && scanStart > startSegment.scanStart) ||
		(endSegment.generatedPlaceholder && scanEnd < endSegment.scanEnd);
	let recursive = false;
	let preserveGeneratedPlaceholders = false;
	// When the match straddles a placeholder, resume scanning just past the last
	// overlapping placeholder so trailing wholly-outside content (e.g. an 8-char
	// run after the secret) still gets matched instead of being consumed by the
	// straddling span. `firstPlaceholderScanStart` marks where the leading
	// wholly-outside prefix ends, so a prefix that independently matches can be
	// redacted on its own rather than skipped along with the cut span.
	let cutResumeIndex = scanStart;
	let firstPlaceholderScanStart = -1;
	for (const segment of segments) {
		if (segment.scanStart >= scanEnd || segment.scanEnd <= scanStart) continue;
		recursive ||= segment.recursive;
		preserveGeneratedPlaceholders ||= segment.generatedPlaceholder;
		if (segment.generatedPlaceholder) {
			if (firstPlaceholderScanStart === -1) firstPlaceholderScanStart = segment.scanStart;
			if (segment.scanEnd > cutResumeIndex) cutResumeIndex = segment.scanEnd;
		}
	}
	return {
		start,
		end,
		recursive,
		preserveGeneratedPlaceholders,
		partialPlaceholderCut,
		cutResumeIndex,
		firstPlaceholderScanStart,
	};
}

function findScanSegment(segments: ReadonlyArray<RegexScanSegment>, scanIndex: number): RegexScanSegment {
	for (const segment of segments) {
		if (scanIndex >= segment.scanStart && scanIndex < segment.scanEnd) return segment;
	}
	throw new Error("regex match did not map to source text");
}

/**
 * Extend a scan-space resume position past a consecutive run of generated
 * placeholder segments starting exactly at it, with no raw gap in between. A
 * cut-resolution resume point that happens to land precisely on the START of
 * ANOTHER placeholder must not stop there and hand it to a fresh `regex.exec`
 * attempt — the same content, scanned as an opaque adjacent placeholder run,
 * must resolve identically whether the run's LEADING member is still raw text
 * (this call is about to placeholder it) or is ALREADY a placeholder from a
 * prior call or an earlier pass of this same call. Without this, a bounded
 * regex whose reach spans two adjacent secrets plus trailing spillover bytes
 * (e.g. `[A-Z]{9}` over `ABCDEFGH` + `SECRETUV` + `A`) resolves the leading
 * secret as its own independent redaction on the FIRST obfuscate() call (a
 * genuinely raw prefix gets its own match, then the discard for the rest
 * resumes right after it), but on a LATER call — once that prefix is itself a
 * placeholder — the very first match attempt starts already inside the
 * placeholder run, cannot be prefix-narrowed at all, and its discard resume
 * point lands mid-run instead of past it, exposing a shorter tail (`SECRETUV`
 * + `A`) to a clean, un-cut match the first call never attempted. Chaining the
 * resume point through every immediately-adjacent placeholder makes both
 * calls land on the exact same next scan position.
 */
function extendPastAdjacentPlaceholders(segments: ReadonlyArray<RegexScanSegment>, index: number): number {
	let cursor = index;
	for (;;) {
		const segment = segments.find(candidate => candidate.scanStart === cursor && candidate.generatedPlaceholder);
		if (!segment) return cursor;
		cursor = segment.scanEnd;
	}
}

// Apply a fixed custom replacement across a matched span while preserving any
// inner generated placeholders. Usually the replacement is the user's single
// redaction marker for the whole match, so emit it for the first non-empty
// surrounding chunk and drop later chunks. But bounded regexes can cut through
// an already-emitted marker on the trailing side (`X#…#RED` from
// `XSECRETUVREDACTED`), where dropping the later prefix would leave raw bytes
// (`ACTED`) to be consumed on the next pass. Promote later chunks that are a
// prefix of the replacement to the FULL marker so the first pass is already a
// fixed point. The reversible placeholder stays intact in its relative
// position.
function redactWithFixedReplacementOutsidePlaceholders(
	text: string,
	origin: string,
	replacement: string,
	shouldPreservePlaceholder: (placeholder: string) => boolean,
): { text: string; origin: string } {
	let emitted = false;
	return transformOutsidePlaceholdersTracked(
		text,
		origin,
		shouldPreservePlaceholder,
		chunk => {
			if (chunk.length === 0) return "";
			if (!emitted) {
				emitted = true;
				return replacement;
			}
			return replacement.startsWith(chunk) ? replacement : "";
		},
		placeholder => placeholder,
	);
}

function deobfuscateGeneratedPlaceholderRanges(
	text: string,
	start: number,
	end: number,
	ranges: ReadonlyArray<{ start: number; end: number }>,
	deobfuscateMap: ReadonlyMap<string, { secret: string; recursive: boolean }>,
): { text: string; recursive: boolean } {
	let result = "";
	let cursor = start;
	let recursive = false;
	for (const range of ranges) {
		if (range.end <= start || range.start >= end) continue;
		const overlapStart = Math.max(range.start, start);
		const overlapEnd = Math.min(range.end, end);
		result += text.slice(cursor, overlapStart);
		const placeholder = text.slice(overlapStart, overlapEnd);
		const mapping = lookupFriendlyPlaceholderAlias(deobfuscateMap, placeholder);
		result += mapping?.secret ?? placeholder;
		recursive ||= mapping?.recursive ?? false;
		cursor = overlapEnd;
	}
	result += text.slice(cursor, end);
	return { text: result, recursive };
}

// Concatenate ONLY the deobfuscated placeholder ranges within [start, end),
// dropping the bytes that lie outside them. Used to test whether a regex match
// that straddles a prior-call placeholder would still match on the placeholder's
// own (expanded) secret value alone — i.e. the surrounding raw bytes are greedy
// spillover the match does not need, rather than content the match depends on.
function placeholderInnerText(
	text: string,
	start: number,
	end: number,
	ranges: ReadonlyArray<{ start: number; end: number }>,
	deobfuscateMap: ReadonlyMap<string, { secret: string; recursive: boolean }>,
): string {
	let result = "";
	for (const range of ranges) {
		if (range.end <= start || range.start >= end) continue;
		const overlapStart = Math.max(range.start, start);
		const overlapEnd = Math.min(range.end, end);
		const placeholder = text.slice(overlapStart, overlapEnd);
		const mapping = lookupFriendlyPlaceholderAlias(deobfuscateMap, placeholder);
		result += mapping?.secret ?? placeholder;
	}
	return result;
}

// Concatenate the bytes of [start, end) that lie OUTSIDE the given (ascending,
// non-overlapping) placeholder ranges. Used to test whether a regex match that
// straddles a prior-call placeholder would still match on its surrounding bytes
// alone — i.e. those bytes are genuinely new content to redact rather than a
// match that only exists because the deobfuscated placeholder bridges them.
function textOutsidePlaceholderRanges(
	text: string,
	start: number,
	end: number,
	ranges: ReadonlyArray<{ start: number; end: number }>,
): string {
	let result = "";
	let cursor = start;
	for (const range of ranges) {
		if (range.end <= start || range.start >= end) continue;
		const overlapStart = Math.max(range.start, start);
		const overlapEnd = Math.min(range.end, end);
		result += text.slice(cursor, overlapStart);
		cursor = overlapEnd;
	}
	result += text.slice(cursor, end);
	return result;
}

// Like `textOutsidePlaceholderRanges`, but tests each outside chunk against
// `regex` in its REAL context instead of on an isolated slice — tried in BOTH
// the literal `#…#` placeholder-token text AND the EXPANDED scan context
// (placeholder resolved to its secret value), since either can be the reason a
// chunk independently requires redaction:
//  - Literal-token context matters when the placeholder TOKEN's own non-word
//    boundary is what completes a boundary-sensitive pattern, e.g. a prefix
//    "ABCDEFGH" next to a placeholder token matches `\b[A-Z]{8}\b` because the
//    token's leading `#` is a non-word byte — but that boundary disappears
//    once the placeholder expands into more `[A-Z]` bytes with no separator.
//  - Expanded scan context matters when a lookbehind/lookahead only resolves
//    once the neighboring placeholder is expanded, e.g. a prior plain
//    placeholder for `ABCDEFGH` next to raw `SECRET`, matched by
//    `(?<=ABCDEFGH)SECRET`: the literal placeholder token before `SECRET`
//    never satisfies the lookbehind, so literal-context alone wrongly reports
//    no independent match.
// A match only counts when it lies ENTIRELY within one outside chunk (in
// whichever context it was tested); a match that reaches into the
// placeholder itself is not evidence the outside chunk independently
// requires redaction.
function outsidePlaceholderRangesAnyIndependentlyMatch(
	text: string,
	scanText: string,
	segments: ReadonlyArray<RegexScanSegment>,
	start: number,
	end: number,
	ranges: ReadonlyArray<{ start: number; end: number }>,
	regex: RegExp,
): boolean {
	// A text-space outside chunk lies entirely within one non-placeholder scan
	// segment (placeholder ranges are exactly the gaps between such segments),
	// so its scan-space span is a fixed offset from its text-space span.
	const toScanSpace = (chunkStart: number, chunkEnd: number): [number, number] | undefined => {
		for (const segment of segments) {
			if (segment.generatedPlaceholder || segment.textStart > chunkStart || segment.textEnd < chunkEnd) continue;
			const offset = segment.scanStart - segment.textStart;
			return [chunkStart + offset, chunkEnd + offset];
		}
		return undefined;
	};
	const chunkIndependentlyMatches = (chunkStart: number, chunkEnd: number): boolean => {
		if (chunkMatchesInSourceContext(text, chunkStart, chunkEnd, regex)) return true;
		const scanSpan = toScanSpace(chunkStart, chunkEnd);
		return scanSpan !== undefined && chunkMatchesInSourceContext(scanText, scanSpan[0], scanSpan[1], regex);
	};
	let cursor = start;
	for (const range of ranges) {
		if (range.end <= start || range.start >= end) continue;
		const overlapStart = Math.max(range.start, start);
		const overlapEnd = Math.min(range.end, end);
		if (cursor < overlapStart && chunkIndependentlyMatches(cursor, overlapStart)) return true;
		cursor = overlapEnd;
	}
	return cursor < end && chunkIndependentlyMatches(cursor, end);
}

// Whether `regex` (global) has a match fully contained in [chunkStart, chunkEnd)
// when run against the full `text` — so lookbehind/lookahead see the actual
// surrounding bytes rather than an isolated slice's edges.
function chunkMatchesInSourceContext(text: string, chunkStart: number, chunkEnd: number, regex: RegExp): boolean {
	regex.lastIndex = chunkStart;
	for (;;) {
		const found = regex.exec(text);
		if (found === null || found.index >= chunkEnd) return false;
		const matchEnd = found.index + found[0].length;
		if (matchEnd <= chunkEnd) return true;
		regex.lastIndex = found[0].length === 0 ? found.index + 1 : matchEnd;
	}
}

function firstOutsidePlaceholderRange(
	start: number,
	end: number,
	ranges: ReadonlyArray<{ start: number; end: number }>,
): { start: number; end: number } | undefined {
	let cursor = start;
	for (const range of ranges) {
		if (range.end <= start || range.start >= end) continue;
		const overlapStart = Math.max(range.start, start);
		const overlapEnd = Math.min(range.end, end);
		if (cursor < overlapStart) return { start: cursor, end: overlapStart };
		cursor = overlapEnd;
	}
	return cursor < end ? { start: cursor, end } : undefined;
}

function countOutsidePlaceholderRanges(
	start: number,
	end: number,
	ranges: ReadonlyArray<{ start: number; end: number }>,
): number {
	let count = 0;
	let cursor = start;
	for (const range of ranges) {
		if (range.end <= start || range.start >= end) continue;
		const overlapStart = Math.max(range.start, start);
		const overlapEnd = Math.min(range.end, end);
		if (cursor < overlapStart) count++;
		cursor = overlapEnd;
	}
	if (cursor < end) count++;
	return count;
}

function replaceRange(text: string, start: number, end: number, replacement: string): string {
	return text.slice(0, start) + replacement + text.slice(end);
}

/** Deep-walk an object, transforming all string values. */
function deepWalkStrings<T>(obj: T, transform: (s: string) => string): T {
	if (typeof obj === "string") {
		return transform(obj) as unknown as T;
	}
	if (Array.isArray(obj)) {
		let changed = false;
		const result = obj.map(item => {
			const transformed = deepWalkStrings(item, transform);
			if (transformed !== item) changed = true;
			return transformed;
		});
		return (changed ? result : obj) as unknown as T;
	}
	if (obj !== null && typeof obj === "object" && isPlainRecord(obj)) {
		let changed = false;
		const result: Record<string, unknown> = {};
		for (const key of Object.keys(obj)) {
			const value = (obj as Record<string, unknown>)[key];
			const transformed = deepWalkStrings(value, transform);
			if (transformed !== value) changed = true;
			result[key] = transformed;
		}
		return (changed ? result : obj) as T;
	}
	return obj;
}

function isPlainRecord(obj: object): obj is Record<string, unknown> {
	const prototype = Object.getPrototypeOf(obj);
	return prototype === Object.prototype || prototype === null;
}

function collectJsonRegexSecretValues(obfuscator: SecretObfuscator, value: JsonValue): Set<string> {
	const values = new Set<string>();
	const collect = (item: JsonValue): void => {
		if (typeof item === "string") {
			for (const secretValue of obfuscator.collectRegexSecretValuesForObfuscation(item)) {
				values.add(secretValue);
			}
			return;
		}
		if (Array.isArray(item)) {
			for (const child of item) collect(child);
			return;
		}
		if (item !== null && typeof item === "object") {
			for (const child of Object.values(item)) {
				if (child !== undefined) collect(child);
			}
		}
	};
	collect(value);
	return values;
}

/**
 * Map every string in arbitrary JSON. Used ONLY for tool-call arguments, whose
 * shape is model-authored and not known ahead of time. No other caller may walk
 * untyped data: every message/content path is handled by a typed transformer.
 */
function mapJsonStrings(value: JsonValue, fn: (s: string) => string): JsonValue {
	if (typeof value === "string") return fn(value);
	if (Array.isArray(value)) {
		let changed = false;
		const out = value.map(item => {
			const next = mapJsonStrings(item, fn);
			if (next !== item) changed = true;
			return next;
		});
		return changed ? out : value;
	}
	if (value !== null && typeof value === "object") {
		let changed = false;
		const out: JsonRecord = {};
		for (const key of Object.keys(value)) {
			const item = value[key];
			if (item === undefined) continue;
			const next = mapJsonStrings(item, fn);
			if (next !== item) changed = true;
			out[key] = next;
		}
		return changed ? out : value;
	}
	return value;
}