@gajae-code/coding-agent 0.12.0 → 0.12.1

package/src/skill-state/active-state.ts

@@ -302,6 +302,32 @@ export function isCanonicalGjcWorkflowSkill(skill: string): skill is CanonicalGj
 	return (CANONICAL_GJC_WORKFLOW_SKILLS as readonly string[]).includes(skill);
 }
 
+/**
+ * Nonterminal phases that intentionally await workflow-specific integration
+ * rather than a generic synthetic compaction continuation.
+ */
+const CONTINUATION_INERT_WORKFLOW_PHASES: Readonly<Partial<Record<CanonicalGjcWorkflowSkill, ReadonlySet<string>>>> = {
+	team: new Set(["awaiting_integration"]),
+};
+
+/**
+ * Continuation inertness for compaction auto-continue, derived from each
+ * workflow's manifest contract: manifest-terminal and explicitly inert phases
+ * are inert; unknown skills or phases unknown to the skill's manifest are
+ * conservatively inert so a synthetic continuation never wakes an unrecognized
+ * workflow. Generic Ultragoal `blocked` remains continuation-active because its
+ * blocker may be autonomously resolvable; verified human pauses are represented
+ * by the inline goal's `paused` status instead.
+ */
+export function isWorkflowContinuationInert(skill: string, phase: string): boolean {
+	const normalizedPhase = phase.trim().toLowerCase();
+	if (!isCanonicalGjcWorkflowSkill(skill)) return true;
+	const manifest = getSkillManifest(skill);
+	if (manifest.terminalStates.some(terminal => terminal.toLowerCase() === normalizedPhase)) return true;
+	if (CONTINUATION_INERT_WORKFLOW_PHASES[skill]?.has(normalizedPhase)) return true;
+	return !manifest.states.some(state => state.id.toLowerCase() === normalizedPhase);
+}
+
 export function listActiveSkills(raw: unknown): SkillActiveEntry[] {
 	if (!raw || typeof raw !== "object") return [];
 	const state = raw as SkillActiveState;
@@ -615,6 +641,8 @@ async function mergeVisibleEntries(
 export type VisibleSkillActiveStateCacheTier = "security" | "hud";
 export interface ReadVisibleSkillActiveStateOptions {
 	tier?: VisibleSkillActiveStateCacheTier;
+	/** Bypass all signature/TTL caches for authorization decisions. */
+	bypassCache?: boolean;
 }
 
 interface ActiveStateStatSignature {
@@ -747,6 +775,10 @@ export async function readVisibleSkillActiveState(
 	}
 	const resolvedCwd = path.resolve(cwd);
 	const cacheKey = visibleActiveStateCacheKey(resolvedCwd, resolvedSessionId);
+	if (opts?.bypassCache) {
+		visibleSkillActiveStateCache.delete(cacheKey);
+		return await readVisibleSkillActiveStateUncached(resolvedCwd, resolvedSessionId);
+	}
 	const tier = opts?.tier ?? "security";
 	const now = Date.now();
 	const cached = visibleSkillActiveStateCache.get(cacheKey);

package/src/skill-state/workflow-hud.ts

@@ -29,6 +29,12 @@ interface RalplanHudState extends WorkflowGateHudState {
 	verdict?: string;
 	latestSummary?: string;
 	pendingApproval?: boolean;
+	autoHandoff?: {
+		configuredTarget: string;
+		effectiveTarget: string;
+		degradationReason: string | null;
+	};
+	planningStuck?: boolean;
 	updatedAt?: string;
 }
 
@@ -222,6 +228,16 @@ export function buildRalplanHudSummary(state: RalplanHudState): WorkflowHudSumma
 		}
 		return chip(label, `${passes}/${state.reviewPassBudget}`, priority);
 	};
+	const handoffValue = state.autoHandoff
+		? `${state.autoHandoff.configuredTarget}→${state.autoHandoff.effectiveTarget}${
+				state.autoHandoff.degradationReason ? `:${state.autoHandoff.degradationReason}` : ""
+			}`
+		: undefined;
+	const handoffSeverity = state.planningStuck
+		? "blocked"
+		: state.autoHandoff?.degradationReason
+			? "warning"
+			: undefined;
 	return {
 		version: 1,
 		summary: state.latestSummary,
@@ -241,6 +257,7 @@ export function buildRalplanHudSummary(state: RalplanHudState): WorkflowHudSumma
 			reviewPassChip("arch", state.architectPasses, 36),
 			reviewPassChip("crit", state.criticPasses, 38),
 			chip("verdict", verdict, 40, verdictSeverity),
+			chip("handoff", handoffValue, 45, handoffSeverity),
 		]),
 		...(state.updatedAt ? { updated_at: state.updatedAt } : {}),
 	};

package/src/skill-state/workflow-mutation-guard.ts

@@ -60,6 +60,35 @@ const BASH_DD_OUTPUT_RE = /(?:^|[;&|\n])\s*(?:\w+=[^\s]+\s+)*(?:sudo\s+)?(?:[^\s
 /** Literal `sh|bash|zsh -c '<script>'` payloads whose nested script must also be scanned. */
 const BASH_NESTED_SHELL_RE =
 	/(?:^|[;&|\n])\s*(?:\w+=[^\s]+\s+)*(?:sudo\s+)?(?:[^\s;&|]*\/)?(?:ba|z|da)?sh\s+(?:-[A-Za-z]+\s+)*-[A-Za-z]*c\s+(?:(')([^']*)'|(")([^"]*)")/g;
+/** Heredoc opener (`<<`/`<<-` plus an optionally quoted delimiter); `<<<` here-strings excluded. */
+const BASH_HEREDOC_OPEN_RE = /(?<!<)<<(?!<)(-?)\s*(?:'([^'\s]+)'|"([^"\s]+)"|(\\)?([A-Za-z_][\w.-]*))/g;
+/** Consumers whose stdin is inert data: their heredoc bodies are safe to mask. Anything else stays live. */
+const HEREDOC_DATA_CONSUMERS = new Set([
+	"cat",
+	"tee",
+	"head",
+	"tail",
+	"wc",
+	"sort",
+	"uniq",
+	"tr",
+	"cut",
+	"grep",
+	"column",
+	"nl",
+	"fold",
+	"fmt",
+	"base64",
+	"md5sum",
+	"sha1sum",
+	"sha256sum",
+	"sha512sum",
+	"shasum",
+	"jq",
+	"yq",
+]);
+/** Stdin appliers whose heredoc body mutates files in ways no body scan can model. */
+const HEREDOC_MUTATING_CONSUMERS = new Set(["patch", "ed", "ex", "sqlite3"]);
 
 type ToolWithEditMode = AgentTool & {
 	mode?: unknown;
@@ -418,6 +447,457 @@ function isDeviceSinkPath(value: string): boolean {
 	return DEVICE_SINK_PATHS.has(cleanShellWord(value));
 }
 
+interface HeredocMaskResult {
+	masked: string;
+	/** An unquoted-delimiter heredoc body carried `$(…)`/backtick expansion — live code the scanner cannot model. */
+	opaqueExpansion: boolean;
+	/** The heredoc feeds a stdin applier (patch/ed/ex/sqlite3) whose body mutates files no scan can attribute. */
+	mutatingConsumer: boolean;
+}
+
+/** Quote/substitution state carried ACROSS physical lines so multiline constructs cannot fake heredoc openers. */
+interface ShellQuoteState {
+	inSingle: boolean;
+	inDouble: boolean;
+	/** The open single quote is ANSI-C (`$'…'`): backslash escapes inside it decode at runtime. */
+	inAnsiC: boolean;
+	/**
+	 * Paren stack inside substitutions: `true` for a `$(`/`<(`/`>(` opener
+	 * (its `)` is a word character), `false` for a plain nested paren (its `)`
+	 * is an operator, so a following `#` starts a comment).
+	 */
+	parenStack: boolean[];
+}
+
+/**
+ * Mask one physical line for syntax analysis, carrying `state` across lines:
+ * quoted spans and backslash-escaped characters become spaces (they are data,
+ * never syntax), so a `<<` inside `"…"`/`'…'` — even when the quote opened on a
+ * PREVIOUS line — or an escaped separator like `\|` is never misread. An
+ * unquoted `#` at a word boundary starts a comment: the rest of the line is
+ * blanked without touching quote state, so a stray quote inside a comment
+ * cannot poison later lines. A `)` closing a `$(`/`<(`/`>(` substitution is
+ * part of the current word (`x=$(true)#literal`), not a comment boundary.
+ * `masked` is the same length as the input so match offsets stay aligned.
+ * `dequoted` applies bash-like QUOTE REMOVAL instead — quote/backslash marks
+ * drop, quoted word characters stay, quoted metacharacters neutralize to `_` —
+ * so obfuscated spellings (`e\val`, `'ev'al`) reassemble into their real
+ * command word without quoted data ever forming fake command boundaries. A
+ * leading `$` immediately before `'…'` (ANSI-C) or `"…"` (locale-translated)
+ * is stripped during quote removal too, so `$'eval'`/`$"eval"` dequote to
+ * plain `eval`, matching real bash quote-removal semantics for both forms.
+ * `continued` reports an unescaped trailing backslash outside quotes (logical
+ * line continuation).
+ */
+function maskLineForSyntax(
+	line: string,
+	state: ShellQuoteState,
+): { masked: string; dequoted: string; continued: boolean; ansiCEscape: boolean } {
+	let masked = "";
+	let dequoted = "";
+	let escaped = false;
+	let previous = "";
+	let ansiCEscape = false;
+	// Quoted data keeps word characters (so `'ev'al` reassembles to `eval`) but
+	// neutralizes everything else to `_` so it can never form a command boundary.
+	const dequoteData = (character: string): string => (/[\w./-]/.test(character) ? character : "_");
+	for (const character of line) {
+		if (state.inSingle) {
+			if (character === "'") {
+				state.inSingle = false;
+				state.inAnsiC = false;
+			} else {
+				// ANSI-C escapes (`$'\145val'`) decode at runtime into characters the
+				// dequoted view cannot reproduce — flag them so the caller fails closed.
+				if (state.inAnsiC && character === "\\") ansiCEscape = true;
+				masked += " ";
+				dequoted += dequoteData(character);
+				previous = character;
+				continue;
+			}
+			masked += "'";
+			previous = character;
+			continue;
+		}
+		if (escaped) {
+			escaped = false;
+			masked += " ";
+			dequoted += dequoteData(character);
+			previous = character;
+			continue;
+		}
+		if (character === "\\") {
+			escaped = true;
+			masked += " ";
+			previous = character;
+			continue;
+		}
+		if (state.inDouble) {
+			if (character === '"') state.inDouble = false;
+			else {
+				masked += " ";
+				dequoted += dequoteData(character);
+				previous = character;
+				continue;
+			}
+			masked += '"';
+			previous = character;
+			continue;
+		}
+		if (
+			character === "(" &&
+			(previous === "$" || previous === "<" || previous === ">" || state.parenStack.length > 0)
+		) {
+			// Substitution opener, or any paren nested INSIDE one (e.g. `$((1))`,
+			// `$(f (x))`): both must be balanced before the substitution closes.
+			state.parenStack.push(previous === "$" || previous === "<" || previous === ">");
+			masked += character;
+			dequoted += character;
+			previous = character;
+			continue;
+		}
+		if (character === ")" && state.parenStack.length > 0) {
+			const wasSubstitutionOpener = state.parenStack.pop() === true;
+			masked += character;
+			dequoted += character;
+			// A substitution close binds to the surrounding word (`x=$(true)#lit`);
+			// a nested subshell close is an operator, so `#` after it comments.
+			previous = wasSubstitutionOpener ? "x" : ")";
+			continue;
+		}
+		if (
+			character === "#" &&
+			(previous === "" || previous === " " || previous === "\t" || ";|&()".includes(previous))
+		) {
+			// Comment: blank the remainder without evaluating quotes inside it.
+			masked += " ".repeat(line.length - masked.length);
+			return { masked, dequoted, continued: false, ansiCEscape };
+		}
+		if (character === "'") {
+			state.inSingle = true;
+			masked += "'";
+			// ANSI-C quoting `$'…'`: bash strips the `$` during quote removal, and
+			// escapes inside decode at runtime.
+			if (dequoted.endsWith("$")) {
+				dequoted = dequoted.slice(0, -1);
+				state.inAnsiC = true;
+			}
+			previous = character;
+			continue;
+		}
+		if (character === '"') {
+			state.inDouble = true;
+			masked += '"';
+			// `$"…"` locale-translated strings undergo the same quote removal as
+			// ANSI-C `$'…'`: bash drops the `$`, so `$"eval"` dequotes to `eval`.
+			if (dequoted.endsWith("$")) dequoted = dequoted.slice(0, -1);
+			previous = character;
+			continue;
+		}
+		masked += character;
+		dequoted += character;
+		previous = character;
+	}
+	return { masked, dequoted, continued: escaped, ansiCEscape };
+}
+
+const DATA_CONSUMER_NAMES = new Set(HEREDOC_DATA_CONSUMERS);
+/**
+ * Command-position words that force the fail-closed pass. `eval`/`source`/`.`
+ * can install a shadow from data the syntax view has blanked (quoted strings,
+ * /dev/stdin). `case` introduces pattern `)` terminators that desync the
+ * substitution-depth scanner (`$(case x in x) …;; esac)`), making comment
+ * detection unreliable — masking is disabled rather than guessing.
+ */
+const SHELL_EVALUATED_COMMANDS = new Set(["eval", "source", ".", "case"]);
+
+/** Wrappers whose next word is still the effective command (`builtin eval …`, `command cat …`). */
+const SHELL_COMMAND_WRAPPER_WORDS = new Set(["sudo", "builtin", "command", "exec", "nohup", "nice"]);
+
+/** Reserved words that introduce a nested command position (`if eval …`, `while eval …`). */
+const SHELL_RESERVED_PREFIX_WORDS = new Set([
+	"if",
+	"then",
+	"else",
+	"elif",
+	"while",
+	"until",
+	"do",
+	"time",
+	"coproc",
+	"{",
+	"!",
+]);
+
+/** A redirection token (`</dev/null`, `2>err`, `>out`) — not a command word. */
+const SHELL_REDIRECTION_TOKEN_RE = /^\d*[<>]/;
+
+/** Command-position words of one command-list segment: the first real word plus words after reserved prefixes. */
+function commandPositionWords(segment: string): string[] {
+	const words: string[] = [];
+	let expectCommand = true;
+	let afterWrapper = false;
+	let afterBareRedirection = false;
+	for (const word of segment.trim().split(/\s+/)) {
+		if (!word) continue;
+		// A bare redirection operator (`<`, `2>`) consumes the NEXT word as its target.
+		if (afterBareRedirection) {
+			afterBareRedirection = false;
+			continue;
+		}
+		if (expectCommand) {
+			if (/^\w+=/.test(word)) continue;
+			// Leading redirections precede the command word (`</dev/null eval …`).
+			// A bare operator (`<`, `2>`) additionally consumes its separated target.
+			if (SHELL_REDIRECTION_TOKEN_RE.test(word)) {
+				if (/^\d*[<>]+$/.test(word)) afterBareRedirection = true;
+				continue;
+			}
+			if (SHELL_COMMAND_WRAPPER_WORDS.has(word.toLowerCase())) {
+				// The wrapper's effective command follows, possibly after options/`--`.
+				afterWrapper = true;
+				continue;
+			}
+			if (afterWrapper && (word === "--" || word.startsWith("-"))) {
+				// `command -v`/`-V` only DESCRIBES its operand — the rest is data.
+				if (/^-[a-zA-Z]*[vV]/.test(word)) return words;
+				// Other wrapper options (`command -p`, `builtin --`) precede the real command.
+				continue;
+			}
+			afterWrapper = false;
+			if (SHELL_RESERVED_PREFIX_WORDS.has(word.toLowerCase())) {
+				// Reserved word keeps the NEXT word in command position.
+				continue;
+			}
+			words.push(word.split("/").pop()?.toLowerCase() ?? "");
+			expectCommand = false;
+		}
+		// Argument position: only real list operators (handled by the segment
+		// split) restore command position — reserved-word TEXT here is data.
+	}
+	return words;
+}
+
+/** Command-list segments of a dequoted view (split at `;`, `|`, `&`, `(`, backtick, newline). */
+function commandListSegments(dequotedView: string): string[] {
+	return dequotedView.split(/[;|&(`\n]/);
+}
+
+/**
+ * True when any command-position word of the dequoted syntax view is
+ * eval/source/`.` — including nested positions after reserved words
+ * (`if eval …`). `echo eval` and `find .` never match because their
+ * tokens sit in argument position.
+ */
+function hasShellEvaluatedCommand(dequotedView: string): boolean {
+	return commandListSegments(dequotedView).some(segment =>
+		commandPositionWords(segment).some(word => SHELL_EVALUATED_COMMANDS.has(word)),
+	);
+}
+
+/**
+ * True when live syntax actually DECLARES a shadow of an allowlisted
+ * data-consumer name: `name()` at a command-list start, `function name`,
+ * or `alias name=…` — each in command position, so `echo function cat`
+ * (argument position) never matches.
+ */
+function hasDataConsumerShadow(dequotedView: string): boolean {
+	for (const segment of commandListSegments(dequotedView)) {
+		const words = commandPositionWords(segment);
+		for (let index = 0; index < words.length; index++) {
+			const word = words[index] ?? "";
+			if (word === "function") {
+				// commandPositionWords stops after the first non-reserved word, so
+				// re-inspect the raw segment for the name following `function`.
+				const rawWords = segment.trim().split(/\s+/).filter(Boolean);
+				const at = rawWords.findIndex(raw => raw.toLowerCase() === "function");
+				const name = rawWords[at + 1]?.split("/").pop()?.toLowerCase() ?? "";
+				if (DATA_CONSUMER_NAMES.has(name)) return true;
+			}
+			if (word === "alias") {
+				const rawWords = segment.trim().split(/\s+/).filter(Boolean);
+				if (rawWords.some(raw => DATA_CONSUMER_NAMES.has(raw.split("=")[0]?.toLowerCase() ?? ""))) return true;
+			}
+		}
+	}
+	// `name()` / `name ()` in command position — allow reserved-word prefixes
+	// (`then cat() { … }`) before the name (POSIX function definition).
+	const nameGroup = [...DATA_CONSUMER_NAMES].join("|");
+	const reservedGroup = [...SHELL_RESERVED_PREFIX_WORDS].filter(word => /^\w+$/.test(word)).join("|");
+	return new RegExp(
+		`(?:^|[;|&{(\`\\n])\\s*(?:(?:${reservedGroup}|\\{|!)\\s+)*(?:${nameGroup})\\s*\\(\\s*\\)`,
+		"i",
+	).test(dequotedView);
+}
+
+/** First command word of a pipeline-segment slice of a quote-masked opener line. */
+function firstCommandWord(segment: string): string {
+	return commandPositionWords(segment)[0] ?? "";
+}
+
+/**
+ * Classify the command consuming the heredoc at offset `at` of the comment-cut,
+ * quote-masked opener line — including every DOWNSTREAM pipe stage, because
+ * `cat <<'EOF' | bash` hands the body to the interpreter even though `cat` is
+ * inert. Only a pipeline whose every stage is an explicitly inert data consumer
+ * qualifies for body masking; any stdin applier stage fails closed; anything
+ * else (interpreters, awk, unknown binaries) keeps the body live.
+ */
+function heredocConsumerKind(syntaxLine: string, at: number): "data" | "mutating" | "other" {
+	let start = 0;
+	for (let index = at - 1; index >= 0; index--) {
+		const character = syntaxLine[index] ?? "";
+		if (";|&(`".includes(character) || character === "\n") {
+			start = index + 1;
+			break;
+		}
+	}
+	// The heredoc's own simple command plus every downstream `|` stage until the
+	// command list ends (`;`, `&&`, `||`, `&`, backtick, or subshell close).
+	const segments: string[] = [syntaxLine.slice(start, at)];
+	let cursor = at;
+	while (cursor < syntaxLine.length) {
+		const character = syntaxLine[cursor] ?? "";
+		if (character === ";" || character === "&" || character === "`" || character === ")") break;
+		if (character === "|") {
+			if (syntaxLine[cursor + 1] === "|") break;
+			let stageEnd = cursor + 1;
+			while (stageEnd < syntaxLine.length && !";|&`)".includes(syntaxLine[stageEnd] ?? "")) stageEnd++;
+			segments.push(syntaxLine.slice(cursor + 1, stageEnd));
+			cursor = stageEnd;
+			continue;
+		}
+		cursor++;
+	}
+	let kind: "data" | "mutating" | "other" = "data";
+	for (const segment of segments) {
+		const base = firstCommandWord(segment);
+		if (HEREDOC_MUTATING_CONSUMERS.has(base)) return "mutating";
+		if (!HEREDOC_DATA_CONSUMERS.has(base)) kind = "other";
+	}
+	return kind;
+}
+
+/**
+ * Blank out heredoc BODY lines so document payloads (markdown specs, plans,
+ * fixtures) piped to an explicitly inert data consumer (`cat <<'EOF' >
+ * /tmp/spec.md`) are not misread as shell commands: body text like `a > b` or
+ * stray apostrophes must not register redirection targets or unbalance the
+ * quote masker. Bodies stay UNMASKED (scanned as today) for every other
+ * consumer — interpreters, awk, unknown binaries — because there the body may
+ * be live code. Stdin appliers (patch/ed/ex/sqlite3) flag `mutatingConsumer`
+ * and the caller fails closed. Unquoted-delimiter bodies still expand
+ * `$(…)`/backticks in real shells, so masked ones flag `opaqueExpansion`. A
+ * `<<` inside a comment or a quoted span (including a quote opened on a
+ * previous line) is not an opener; a line-continued opener, a shadowed
+ * data-consumer name (`cat() { … }`), and an unterminated heredoc all keep
+ * their bodies live so the scanner stays fail-closed rather than blind.
+ */
+function maskHeredocBodies(command: string): HeredocMaskResult {
+	if (!command.includes("<<")) return { masked: command, opaqueExpansion: false, mutatingConsumer: false };
+	const first = maskHeredocBodiesPass(command, false);
+	// Fail closed on live-syntax constructs that can install a shadow the syntax
+	// view cannot see: a function/alias definition of an allowlisted consumer
+	// name, or a command-position eval/source/`.` whose argument is blanked
+	// quoted data. Both run against the DEQUOTED view so quoting tricks
+	// (`e\val`, `'ev'al`) cannot hide the word, while heredoc bodies and
+	// comments stay excluded — a spec that merely DOCUMENTS `cat() { … }` or
+	// mentions "eval" in prose stays inert.
+	if (first.ansiCEscape || hasDataConsumerShadow(first.dequotedView) || hasShellEvaluatedCommand(first.dequotedView)) {
+		return maskHeredocBodiesPass(command, true).result;
+	}
+	return first.result;
+}
+
+function maskHeredocBodiesPass(
+	command: string,
+	shadowed: boolean,
+): { result: HeredocMaskResult; dequotedView: string; ansiCEscape: boolean } {
+	const lines = command.split("\n");
+	const out: string[] = [];
+	const dequotedLines: string[] = [];
+	const state: ShellQuoteState = { inSingle: false, inDouble: false, inAnsiC: false, parenStack: [] };
+	let previousContinued = false;
+	let opaqueExpansion = false;
+	let mutatingConsumer = false;
+	let sawAnsiCEscape = false;
+	for (let index = 0; index < lines.length; index++) {
+		const line = lines[index] ?? "";
+		out.push(line);
+		// Cross-line quote masking decides whether a `<<` is real syntax or inert
+		// data — even when the enclosing quote opened on a previous line.
+		const { masked, dequoted, continued, ansiCEscape } = maskLineForSyntax(line, state);
+		if (ansiCEscape) sawAnsiCEscape = true;
+		const syntax = masked;
+		const isContinuationLine = previousContinued;
+		// Bash removes a backslash-newline pair entirely: fold a continuation into
+		// the previous dequoted line so split command words (`e\` + `val`)
+		// reassemble for command/shadow detection.
+		if (isContinuationLine && dequotedLines.length > 0) {
+			let previousDequoted = dequotedLines[dequotedLines.length - 1] ?? "";
+			// A continuation can also split ANSI-C/locale quoting (`$\` + `'eval'` or
+			// `$\` + `"eval"`): the rejoined `$'`/`$"` still drops its `$` during
+			// quote removal.
+			if (previousDequoted.endsWith("$") && (line.startsWith("'") || line.startsWith('"'))) {
+				previousDequoted = previousDequoted.slice(0, -1);
+				// The masker already opened this quote as ordinary (it ran before the
+				// fold), so re-check the rejoined ANSI-C span for runtime-decoding
+				// escapes (`$\` + `'\145val'`) it could not have flagged.
+				if (line.startsWith("'") && /^'[^']*\\/.test(line)) sawAnsiCEscape = true;
+			}
+			dequotedLines[dequotedLines.length - 1] = previousDequoted + dequoted;
+		} else {
+			dequotedLines.push(dequoted);
+		}
+		previousContinued = continued;
+		for (const match of line.matchAll(BASH_HEREDOC_OPEN_RE)) {
+			const at = match.index ?? 0;
+			if (syntax.slice(at, at + 2) !== "<<") continue;
+			const delimiter = match[2] ?? match[3] ?? match[5] ?? "";
+			if (!delimiter) continue;
+			let kind = heredocConsumerKind(syntax, at);
+			// A continued/continuation opener line hides part of the pipeline
+			// (`cat <<'EOF' \` / `| bash`); a shadowed consumer name is untrustworthy.
+			// Both downgrade masking eligibility, never block eligibility.
+			if (kind === "data" && (shadowed || continued || isContinuationLine)) kind = "other";
+			if (kind === "mutating") mutatingConsumer = true;
+			const quoted = match[2] !== undefined || match[3] !== undefined || match[4] !== undefined;
+			const stripTabs = match[1] === "-";
+			let end = -1;
+			for (let scan = index + 1; scan < lines.length; scan++) {
+				const candidate = stripTabs ? (lines[scan] ?? "").replace(/^\t+/, "") : (lines[scan] ?? "");
+				if (candidate === delimiter) {
+					end = scan;
+					break;
+				}
+			}
+			if (end === -1) {
+				return {
+					result: { masked: command, opaqueExpansion, mutatingConsumer },
+					dequotedView: dequotedLines.join("\n"),
+					ansiCEscape: sawAnsiCEscape,
+				};
+			}
+			const maskBody = kind === "data" || kind === "mutating";
+			for (let body = index + 1; body < end; body++) {
+				const bodyLine = lines[body] ?? "";
+				if (maskBody && !quoted && /\$\(|`/.test(bodyLine)) opaqueExpansion = true;
+				out.push(maskBody ? "" : bodyLine);
+			}
+			out.push(lines[end] ?? "");
+			index = end;
+			// Heredoc bodies are data: they never affect the shell quote state or
+			// the syntax view used for shadow detection.
+			previousContinued = false;
+		}
+	}
+	return {
+		result: { masked: out.join("\n"), opaqueExpansion, mutatingConsumer },
+		dequotedView: dequotedLines.join("\n"),
+		ansiCEscape: sawAnsiCEscape,
+	};
+}
+
 function extractBashTargets(args: unknown, depth = 0): ExtractedTargets {
 	const record = getRecord(args);
 	const command = safeString(record?.command);
@@ -440,10 +920,21 @@ function extractBashTargets(args: unknown, depth = 0): ExtractedTargets {
 		if (nested.unknown) targets.unknown = true;
 		if (nested.explicitMutation) targets.explicitMutation = true;
 	}
+	// Heredoc bodies fed to data consumers are inert document payloads; mask them
+	// so spec/plan text cannot fake redirections. Script-consumer bodies survive
+	// the mask and are still scanned as live code below.
+	const heredoc = maskHeredocBodies(command);
+	if (heredoc.opaqueExpansion || heredoc.mutatingConsumer) {
+		targets.explicitMutation = true;
+		targets.unknown = true;
+	}
 	// Nested scripts were read from the raw text above; every scanner below works
 	// on the masked view so quoted argument data cannot look like a redirection.
-	const scanned = maskSingleQuotedSpans(command);
-	if (BASH_OPAQUE_INTERPRETER_WRITE_RE.test(command) || BASH_HEREDOC_OPAQUE_INTERPRETER_WRITE_RE.test(command)) {
+	const scanned = maskSingleQuotedSpans(heredoc.masked);
+	if (
+		BASH_OPAQUE_INTERPRETER_WRITE_RE.test(heredoc.masked) ||
+		BASH_HEREDOC_OPAQUE_INTERPRETER_WRITE_RE.test(heredoc.masked)
+	) {
 		targets.explicitMutation = true;
 		targets.unknown = true;
 	}
@@ -502,6 +993,9 @@ function extractBashTargets(args: unknown, depth = 0): ExtractedTargets {
 		for (const part of targetParts) {
 			const cleaned = cleanShellWord(part);
 			if (!cleaned || cleaned.startsWith("-")) continue;
+			// Redirection/heredoc operator words (`>/dev/null`, `<<'DOC'`, `2>&1`) are
+			// not argument paths; their targets are captured by the redirect scanners.
+			if (/^\d*[<>]/.test(cleaned)) continue;
 			addPath(targets, cleaned);
 		}
 	}