From 7eb455840965d8c2d3abb97d887ade7d58c085b8 Mon Sep 17 00:00:00 2001
From: Mykhailo Chalyi <mike@chaliy.name>
Date: Tue, 6 Oct 2026 19:41:06 +0000
Subject: [PATCH] fix(parser): run commands before a later syntax error;
 quote/heredoc-aware $( ) end

Bash reads and runs a script line by line, so commands before a syntax
error execute and the error is reported afterwards (exit 2). Bashkit
rejected the whole script, losing all earlier work. Also find the end of
$(...) with a shared scanner aware of quotes, escapes, backticks,
comments and heredoc bodies; $(cat <<'E' ... ) ... E) and $(echo ")")
were cut at the inner paren.

Claude-Session: https://claude.ai/code/session_019aFikmptPc91Fj4N2iDXQA
---
 crates/bashkit/src/interpreter/mod.rs         |  42 +-
 crates/bashkit/src/lib.rs                     |  38 +-
 crates/bashkit/src/parser/ast.rs              |   7 +
 crates/bashkit/src/parser/budget.rs           |   1 +
 crates/bashkit/src/parser/lexer.rs            | 157 +------
 crates/bashkit/src/parser/mod.rs              | 106 +++--
 crates/bashkit/src/parser/subst_scan.rs       | 382 ++++++++++++++++++
 crates/bashkit/tests/integration/main.rs      |   1 +
 .../tests/integration/partial_parse_tests.rs  |  93 +++++
 .../spec_cases/bash/cmdsub-body-end.test.sh   |  84 ++++
 knowledge/foundations/parser.md               |  17 +
 11 files changed, 750 insertions(+), 178 deletions(-)
 create mode 100644 crates/bashkit/src/parser/subst_scan.rs
 create mode 100644 crates/bashkit/tests/integration/partial_parse_tests.rs
 create mode 100644 crates/bashkit/tests/spec_cases/bash/cmdsub-body-end.test.sh

diff --git a/crates/bashkit/src/interpreter/mod.rs b/crates/bashkit/src/interpreter/mod.rs
index f68c7ce04..2420d5d6a 100644
--- a/crates/bashkit/src/interpreter/mod.rs
+++ b/crates/bashkit/src/interpreter/mod.rs
@@ -640,6 +640,24 @@ fn decode_file_bytes_for_path(_path: &Path, bytes: &[u8]) -> String {
     String::from_utf8_lossy(bytes).into_owned()
 }
 
+/// Child-shell counterpart of `recover_partial_parse` in `lib.rs`: commands
+/// before a syntax error run, then the error is reported (exit 2). `bash -n`
+/// keeps whole-script rejection since it only checks syntax.
+fn nested_partial_parse(
+    (mut script, error): (Script, Option<crate::error::Error>),
+    noexec: bool,
+    shell_name: &str,
+) -> Result<Script> {
+    match error {
+        None => Ok(script),
+        Some(e) if noexec || script.commands.is_empty() => Err(e),
+        Some(e) => {
+            script.trailing_error = Some(format!("{shell_name}: syntax error: {e}\n"));
+            Ok(script)
+        }
+    }
+}
+
 /// Check if a path refers to /dev/null after normalization.
 /// Handles attempts to bypass via paths like `/dev/../dev/null`.
 fn is_dev_null(path: &Path) -> bool {
@@ -2698,6 +2716,7 @@ impl Interpreter {
         let max_stdout = self.limits.max_stdout_bytes;
         let max_stderr = self.limits.max_stderr_bytes;
 
+        let mut stopped = false;
         for command in &script.commands {
             self.check_cancelled()?;
             let emit_before = self.output_emit_count;
@@ -2750,14 +2769,17 @@ impl Interpreter {
                             Some(event) => {
                                 exit_code = event.code;
                                 self.last_exit_code = exit_code;
+                                stopped = true;
                                 break;
                             }
                             None => continue,
                         }
                     } else {
+                        stopped = true;
                         break;
                     }
                 } else {
+                    stopped = true;
                     break;
                 }
             }
@@ -2783,11 +2805,25 @@ impl Interpreter {
                 let suppressed = matches!(command, Command::Pipeline(p) if p.negated)
                     || result.errexit_suppressed;
                 if !suppressed {
+                    stopped = true;
                     break;
                 }
             }
         }
 
+        // Syntax error after the commands that ran: bash reads and runs a
+        // script line by line, so it reports the error only on reaching it.
+        if !stopped && let Some(message) = &script.trailing_error {
+            let emit_before = self.output_emit_count;
+            let err = crate::StreamData::from(message.clone());
+            self.maybe_emit_output(&crate::StreamData::new(), &err, emit_before);
+            if !stderr_truncated {
+                stderr.append(&err);
+            }
+            exit_code = 2;
+            self.last_exit_code = 2;
+        }
+
         // Run EXIT trap if registered (only for top-level execute)
         #[allow(clippy::collapsible_if)]
         if run_exit_trap {
@@ -4737,7 +4773,7 @@ impl Interpreter {
                 Some(parser_timeout),
             )
             .with_execution_budget(self.execution_budget.clone());
-            match parser.parse() {
+            match nested_partial_parse(parser.parse_recovering(), noexec, shell_name) {
                 Ok(s) => s,
                 Err(e) => {
                     return Ok(ExecResult::err(
@@ -4759,12 +4795,12 @@ impl Interpreter {
                     let parser =
                         Parser::with_limits(&script_owned, max_ast_depth, max_parser_operations)
                             .with_execution_budget(execution_budget);
-                    parser.parse()
+                    parser.parse_recovering()
                 })
                 .await
             })
             .await;
-            match parse_result {
+            match parse_result.map(|r| r.map(|p| nested_partial_parse(p, noexec, shell_name))) {
                 Ok(Ok(Ok(s))) => s,
                 Ok(Ok(Err(e))) => {
                     return Ok(ExecResult::err(
diff --git a/crates/bashkit/src/lib.rs b/crates/bashkit/src/lib.rs
index 5b2b7715d..504d31f19 100644
--- a/crates/bashkit/src/lib.rs
+++ b/crates/bashkit/src/lib.rs
@@ -1058,7 +1058,7 @@ impl Bash {
                 Some(parser_timeout),
             )
             .with_execution_budget(self.interpreter.execution_budget().clone());
-            parser.parse()?
+            recover_partial_parse(parser.parse_recovering())?
         };
 
         // On native targets, parse inline for small scripts (avoid threadpool
@@ -1068,7 +1068,7 @@ impl Bash {
         let ast = if input_len <= SPAWN_BLOCKING_THRESHOLD {
             let parser = Parser::with_limits(script, max_ast_depth, max_parser_operations)
                 .with_execution_budget(self.interpreter.execution_budget().clone());
-            match parser.parse() {
+            match recover_partial_parse(parser.parse_recovering()) {
                 Ok(ast) => {
                     #[cfg(feature = "logging")]
                     tracing::debug!(target: "bashkit::parser", "Parse completed (inline)");
@@ -1088,7 +1088,7 @@ impl Bash {
                     let parser =
                         Parser::with_limits(&script_owned, max_ast_depth, max_parser_operations)
                             .with_execution_budget(execution_budget);
-                    parser.parse()
+                    recover_partial_parse(parser.parse_recovering())
                 })
                 .await
             })
@@ -3978,6 +3978,26 @@ pub mod logging_guide {}
 #[doc = include_str!("../docs/hooks.md")]
 pub mod hooks_guide {}
 
+/// Turn a [`parser::Parser::parse_recovering`] result into the script to run.
+///
+/// Decision: like bash, commands on lines before a syntax error still run and
+/// the error is reported afterwards (stderr + exit 2, via
+/// `Script::trailing_error`). With nothing runnable before it, the error stays
+/// a hard `Err` exactly as before, so callers that only validate syntax are
+/// unaffected.
+fn recover_partial_parse(
+    (mut script, error): (parser::Script, Option<Error>),
+) -> Result<parser::Script> {
+    match error {
+        None => Ok(script),
+        Some(e) if script.commands.is_empty() => Err(e),
+        Some(e) => {
+            script.trailing_error = Some(format!("bash: syntax error: {e}\n"));
+            Ok(script)
+        }
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -6923,15 +6943,15 @@ if true; then
 echo missing fi"#,
             )
             .await;
-        // Should fail to parse due to missing 'fi'
-        assert!(result.is_err());
-        let err = result.unwrap_err();
-        let err_msg = format!("{}", err);
+        // Like bash: line 1 runs, then the missing 'fi' is reported (exit 2)
+        let result = result.unwrap();
+        assert_eq!(result.stdout, "ok\n");
+        assert_eq!(result.exit_code, 2);
         // Error should mention line number
         assert!(
-            err_msg.contains("line") || err_msg.contains("parse"),
+            result.stderr.contains("line") && result.stderr.contains("parse"),
             "Error should be a parse error: {}",
-            err_msg
+            result.stderr
         );
     }
 
diff --git a/crates/bashkit/src/parser/ast.rs b/crates/bashkit/src/parser/ast.rs
index 6fea1202d..6d2accb66 100644
--- a/crates/bashkit/src/parser/ast.rs
+++ b/crates/bashkit/src/parser/ast.rs
@@ -14,6 +14,12 @@ pub struct Script {
     pub commands: Vec<Command>,
     /// Source span of the entire script
     pub span: Span,
+    /// Syntax error found after `commands` (see `Parser::parse_recovering`).
+    /// Reported as stderr + exit 2 once every command ran, unless one of
+    /// them stopped the script first (`exit`, `set -e`), matching bash's
+    /// line-by-line read-then-execute model.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub trailing_error: Option<String>,
 }
 
 /// A single command in the script.
@@ -1281,6 +1287,7 @@ mod tests {
         let script = Script {
             commands: vec![],
             span: Span::new(),
+            trailing_error: None,
         };
         assert!(script.commands.is_empty());
     }
diff --git a/crates/bashkit/src/parser/budget.rs b/crates/bashkit/src/parser/budget.rs
index e901ec426..797349fdc 100644
--- a/crates/bashkit/src/parser/budget.rs
+++ b/crates/bashkit/src/parser/budget.rs
@@ -390,6 +390,7 @@ mod tests {
         let ast = Script {
             commands,
             span: Span::new(),
+            trailing_error: None,
         };
         let limits = ExecutionLimits::default();
         let err = validate(&ast, &limits).unwrap_err();
diff --git a/crates/bashkit/src/parser/lexer.rs b/crates/bashkit/src/parser/lexer.rs
index 054eddfdf..4dd126901 100644
--- a/crates/bashkit/src/parser/lexer.rs
+++ b/crates/bashkit/src/parser/lexer.rs
@@ -821,44 +821,10 @@ impl<'a> Lexer<'a> {
                             }
                         }
                     } else {
-                        // THREAT[TM-DOS]: Track substitution nesting depth to
-                        // enforce max_subst_depth consistently in both quoted
-                        // and unquoted contexts (issue #996).
-                        let mut depth = 1;
-                        let mut subst_depth = 1usize;
-                        while let Some(c) = self.peek_char() {
-                            word.push(c);
-                            self.advance();
-                            if c == '$' && self.peek_char() == Some('(') {
-                                subst_depth += 1;
-                                if subst_depth > self.max_subst_depth {
-                                    // Depth limit exceeded — consume remaining
-                                    // parens and stop nesting deeper.
-                                    while let Some(ic) = self.peek_char() {
-                                        word.push(ic);
-                                        self.advance();
-                                        if ic == '(' {
-                                            depth += 1;
-                                        } else if ic == ')' {
-                                            depth -= 1;
-                                            if depth == 0 {
-                                                break;
-                                            }
-                                        }
-                                    }
-                                    break;
-                                }
-                            }
-                            if c == '(' {
-                                depth += 1;
-                            } else if c == ')' {
-                                depth -= 1;
-                                if depth == 0 {
-                                    break;
-                                }
-                            }
-                        }
-                        if depth > 0 {
+                        // Quote/heredoc-aware end of the body (see subst_scan).
+                        // Nesting depth is bounded where bodies are parsed
+                        // (parser max_depth) and run (max_subst_depth).
+                        if !self.read_command_subst_body(&mut word) {
                             return Some(Token::Error(
                                 "unterminated command substitution".to_string(),
                             ));
@@ -1634,112 +1600,25 @@ impl<'a> Lexer<'a> {
         result
     }
 
-    /// Read command substitution content after `$(`, handling nested parens and quotes.
-    /// Appends chars to `content` and adds the closing `)`.
-    /// THREAT[TM-DOS-044]: `subst_depth` tracks nesting to prevent stack overflow.
+    /// Read command substitution content after `$(`, handling nested parens,
+    /// quotes, comments and heredoc bodies (see `subst_scan`). Appends chars
+    /// to `content` and adds the closing `)`.
     fn read_command_subst_into(&mut self, content: &mut String) {
-        self.read_command_subst_into_depth(content, 0);
+        self.read_command_subst_body(content);
     }
 
-    fn read_command_subst_into_depth(&mut self, content: &mut String, subst_depth: usize) {
-        if subst_depth >= self.max_subst_depth {
-            // Depth limit exceeded — consume until matching ')' and emit error token
-            let mut depth = 1;
-            while let Some(c) = self.peek_char() {
-                self.advance();
-                match c {
-                    '(' => depth += 1,
-                    ')' => {
-                        depth -= 1;
-                        if depth == 0 {
-                            content.push(')');
-                            return;
-                        }
-                    }
-                    _ => {}
-                }
-            }
-            return;
-        }
-
-        let mut depth = 1;
-        while let Some(c) = self.peek_char() {
-            match c {
-                '(' => {
-                    depth += 1;
-                    content.push(c);
-                    self.advance();
-                }
-                ')' => {
-                    depth -= 1;
-                    self.advance();
-                    if depth == 0 {
-                        content.push(')');
-                        break;
-                    }
-                    content.push(c);
-                }
-                '"' => {
-                    // Nested double-quoted string inside $()
-                    content.push('"');
-                    self.advance();
-                    while let Some(qc) = self.peek_char() {
-                        match qc {
-                            '"' => {
-                                content.push('"');
-                                self.advance();
-                                break;
-                            }
-                            '\\' => {
-                                content.push('\\');
-                                self.advance();
-                                if let Some(esc) = self.peek_char() {
-                                    content.push(esc);
-                                    self.advance();
-                                }
-                            }
-                            '$' => {
-                                content.push('$');
-                                self.advance();
-                                if self.peek_char() == Some('(') {
-                                    content.push('(');
-                                    self.advance();
-                                    self.read_command_subst_into_depth(content, subst_depth + 1);
-                                }
-                            }
-                            _ => {
-                                content.push(qc);
-                                self.advance();
-                            }
-                        }
-                    }
-                }
-                '\'' => {
-                    // Single-quoted string inside $()
-                    content.push('\'');
-                    self.advance();
-                    while let Some(qc) = self.peek_char() {
-                        content.push(qc);
-                        self.advance();
-                        if qc == '\'' {
-                            break;
-                        }
-                    }
-                }
-                '\\' => {
-                    content.push('\\');
-                    self.advance();
-                    if let Some(esc) = self.peek_char() {
-                        content.push(esc);
-                        self.advance();
-                    }
-                }
-                _ => {
-                    content.push(c);
-                    self.advance();
-                }
+    /// Like `read_command_subst_into`; returns whether the closing `)` was
+    /// found. The scanner is iterative, so deep nesting cannot overflow the
+    /// host stack here (TM-DOS-044).
+    fn read_command_subst_body(&mut self, content: &mut String) -> bool {
+        let mut scanner = super::subst_scan::SubstScanner::new();
+        while let Some(c) = self.advance() {
+            content.push(c);
+            if scanner.feed(c) == super::subst_scan::Step::Close {
+                return true;
             }
         }
+        false
     }
 
     /// Read parameter expansion content after `${`, handling nested braces and quotes.
diff --git a/crates/bashkit/src/parser/mod.rs b/crates/bashkit/src/parser/mod.rs
index 69e7d31fd..676f7d6f6 100644
--- a/crates/bashkit/src/parser/mod.rs
+++ b/crates/bashkit/src/parser/mod.rs
@@ -17,6 +17,7 @@ mod ast;
 pub mod budget;
 mod lexer;
 mod span;
+mod subst_scan;
 mod tokens;
 
 pub use ast::*;
@@ -73,6 +74,12 @@ pub struct Parser<'a> {
     /// when a `$(...)` body fails to parse; `parse_script` converts it into a
     /// hard parse error so the script is rejected the way bash rejects it.
     deferred_error: Cell<Option<Error>>,
+    /// The returned error came from (or coexisted with) a deferred `$(...)`
+    /// error, whose position is unreliable; see [`Parser::parse_recovering`].
+    error_was_deferred: bool,
+    /// Line the top-level command being parsed starts on; on failure, only
+    /// commands that ended on earlier lines are runnable.
+    failed_command_line: usize,
     /// Aggregate request budget shared by every child parser.
     execution_budget: Option<crate::limits::ExecutionBudget>,
 }
@@ -128,6 +135,8 @@ impl<'a> Parser<'a> {
             timeout,
             started_at: Instant::now(),
             deferred_error: Cell::new(None),
+            error_was_deferred: false,
+            failed_command_line: 0,
             execution_budget: None,
         }
     }
@@ -255,16 +264,67 @@ impl<'a> Parser<'a> {
 
     /// Parse the input and return the AST.
     pub fn parse(mut self) -> Result<Script> {
-        self.parse_script()
+        let mut commands = Vec::new();
+        let start_span = self.current_span;
+        self.parse_script_into(&mut commands)?;
+        let end_span = self.current_span;
+        Ok(Script {
+            commands: commands.into_iter().map(|(cmd, _)| cmd).collect(),
+            span: start_span.merge(end_span),
+            trailing_error: None,
+        })
+    }
+
+    /// Parse like bash reads a script: on a syntax error, also return the
+    /// complete commands that ended on lines *before* the line where the
+    /// failing command starts, so the caller can run them first (bash executes
+    /// line by line and only then reports the error, exit 2). Commands sharing
+    /// that line are dropped, as bash parses a whole line before running any
+    /// of it.
+    ///
+    /// Errors deferred from a `$(...)` body carry no reliable position, so
+    /// they keep whole-script semantics: no prefix is returned.
+    pub fn parse_recovering(mut self) -> (Script, Option<Error>) {
+        let mut commands = Vec::new();
+        let start_span = self.current_span;
+        let result = self.parse_script_into(&mut commands);
+        let end_span = self.current_span;
+        let (keep, err) = match result {
+            Ok(()) => (commands.len(), None),
+            Err(e) => {
+                if self.deferred_error.take().is_some() {
+                    self.error_was_deferred = true;
+                }
+                let keep = match &e {
+                    Error::Parse { .. } if !self.error_was_deferred => {
+                        let failed_line = self.failed_command_line;
+                        commands
+                            .iter()
+                            .take_while(|(_, end)| *end < failed_line)
+                            .count()
+                    }
+                    _ => 0,
+                };
+                (keep, Some(e))
+            }
+        };
+        commands.truncate(keep);
+        (
+            Script {
+                commands: commands.into_iter().map(|(cmd, _)| cmd).collect(),
+                span: start_span.merge(end_span),
+                trailing_error: None,
+            },
+            err,
+        )
     }
 
-    fn parse_script(&mut self) -> Result<Script> {
+    /// Top-level command loop. Each command is stored with the line its
+    /// terminator (newline, `;`, `&` or EOF) sits on.
+    fn parse_script_into(&mut self, commands: &mut Vec<(Command, usize)>) -> Result<()> {
         // Check if the very first token is an error
         self.check_error_token()?;
 
-        let start_span = self.current_span;
-        let mut commands = Vec::new();
-
         while self.current_token.is_some() {
             self.tick()?;
             self.skip_newlines()?;
@@ -273,8 +333,9 @@ impl<'a> Parser<'a> {
                 break;
             }
             let start_offset = self.current_span.start.offset;
+            self.failed_command_line = self.current_span.start.line;
             if let Some(cmd) = self.parse_command_list()? {
-                commands.push(cmd);
+                commands.push((cmd, self.current_span.start.line));
             } else if self.current_token.is_some() && self.current_span.start.offset == start_offset
             {
                 return Err(self.error("unexpected token"));
@@ -285,14 +346,10 @@ impl<'a> Parser<'a> {
         // script, exactly as in bash. Surfaced here because `parse_word` cannot
         // return `Result`.
         if let Some(err) = self.deferred_error.take() {
+            self.error_was_deferred = true;
             return Err(err);
         }
-
-        let end_span = self.current_span;
-        Ok(Script {
-            commands,
-            span: start_span.merge(end_span),
-        })
+        Ok(())
     }
 
     fn advance(&mut self) {
@@ -2950,13 +3007,16 @@ impl<'a> Parser<'a> {
                     inner_parser.execution_budget = self.execution_budget.clone();
                     inner_parser.current_depth = self.current_depth + 1;
                     inner_parser.started_at = self.started_at;
-                    let result = inner_parser.parse_script();
+                    let mut commands = Vec::new();
+                    let result = inner_parser
+                        .parse_script_into(&mut commands)
+                        .map(|()| commands.into_iter().map(|(cmd, _)| cmd).collect::<Vec<_>>());
                     (result, inner_parser.fuel)
                 };
                 let (parse_result, remaining_fuel) = inner_result;
                 self.fuel = remaining_fuel;
                 let commands = match parse_result {
-                    Ok(script) => script.commands,
+                    Ok(commands) => commands,
                     Err(err) if Self::is_parser_budget_error(&err) => return Err(err),
                     Err(_) => Vec::new(),
                 };
@@ -3114,22 +3174,14 @@ impl<'a> Parser<'a> {
                         }
                         push_part!(WordPart::ArithmeticExpansion(expr));
                     } else {
-                        // Command substitution $(...)
+                        // Command substitution $(...): quote/heredoc-aware end.
                         let mut cmd_str = String::new();
-                        let mut depth = 1;
+                        let mut scanner = subst_scan::SubstScanner::new();
                         for c in chars.by_ref() {
-                            if c == '(' {
-                                depth += 1;
-                                cmd_str.push(c);
-                            } else if c == ')' {
-                                depth -= 1;
-                                if depth == 0 {
-                                    break;
-                                }
-                                cmd_str.push(c);
-                            } else {
-                                cmd_str.push(c);
+                            if scanner.feed(c) == subst_scan::Step::Close {
+                                break;
                             }
+                            cmd_str.push(c);
                         }
                         // THREAT[TM-DOS-021]: Propagate parent parser limits to child parser
                         // to prevent depth limit bypass via nested command substitution.
diff --git a/crates/bashkit/src/parser/subst_scan.rs b/crates/bashkit/src/parser/subst_scan.rs
new file mode 100644
index 000000000..966385ae5
--- /dev/null
+++ b/crates/bashkit/src/parser/subst_scan.rs
@@ -0,0 +1,382 @@
+//! Finds the `)` that closes a `$(...)` body.
+//!
+//! Decision: one incremental scanner shared by the lexer and `parse_word`, fed
+//! one char at a time, so both agree on where a command substitution ends.
+//! Plain paren counting closed `$(cat <<'E'` at a `)` inside the heredoc body,
+//! and `$(echo ")")` at the quoted `)`. Bash finds the end by parsing; this
+//! tracks the contexts that can hide a `)`: single/double quotes, backslash
+//! escapes, backticks, nested `$(...)`, comments and heredoc bodies.
+//! Known gap: a `case` pattern's bare `)` inside `$(...)` still closes early,
+//! as before this scanner (`$(case x in x) ...esac)`); bash accepts it.
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum Frame {
+    /// Shell code inside `$(` (or `(` nesting within it).
+    Code,
+    Single,
+    Double,
+    Backtick,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+struct Heredoc {
+    delimiter: String,
+    strip_tabs: bool,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+enum Mode {
+    Normal,
+    /// After a backslash: the next char is literal.
+    Escape,
+    /// `#` comment, until newline.
+    Comment,
+    /// Reading the word after `<<` / `<<-`.
+    Delimiter {
+        strip_tabs: bool,
+        word: String,
+        started: bool,
+        quote: Option<char>,
+    },
+    /// Inside heredoc bodies; `line` accumulates the current line.
+    Body {
+        line: String,
+    },
+}
+
+/// Result of feeding one char.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) enum Step {
+    /// Char belongs to the body.
+    Body,
+    /// Char is the closing `)`; it is not part of the body.
+    Close,
+}
+
+/// Incremental scanner for a `$(...)` body. Create it after consuming `$(`.
+#[derive(Debug, Clone)]
+pub(crate) struct SubstScanner {
+    /// Context stack; the bottom `Code` frame is the substitution itself.
+    stack: Vec<Frame>,
+    /// Paren depth per `Code` frame (parallel to Code entries in `stack`).
+    parens: Vec<usize>,
+    mode: Mode,
+    prev: Option<char>,
+    /// `<` chars seen in a row in code context.
+    lt_run: usize,
+    pending_heredocs: Vec<Heredoc>,
+    /// Paren depth at which an arithmetic `((` started in the top code frame;
+    /// `<<` inside it is a shift, not a heredoc.
+    arith_at: Option<usize>,
+}
+
+impl Default for SubstScanner {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl SubstScanner {
+    pub(crate) fn new() -> Self {
+        Self {
+            stack: vec![Frame::Code],
+            parens: vec![0],
+            mode: Mode::Normal,
+            prev: None,
+            lt_run: 0,
+            pending_heredocs: Vec::new(),
+            arith_at: None,
+        }
+    }
+
+    pub(crate) fn feed(&mut self, c: char) -> Step {
+        let step = self.feed_inner(c);
+        self.prev = Some(c);
+        step
+    }
+
+    fn top(&self) -> Frame {
+        *self.stack.last().unwrap_or(&Frame::Code)
+    }
+
+    fn feed_inner(&mut self, c: char) -> Step {
+        match std::mem::replace(&mut self.mode, Mode::Normal) {
+            Mode::Escape => Step::Body,
+            Mode::Comment => {
+                if c == '\n' {
+                    self.on_newline();
+                } else {
+                    self.mode = Mode::Comment;
+                }
+                Step::Body
+            }
+            Mode::Body { mut line } => {
+                if c != '\n' {
+                    line.push(c);
+                    self.mode = Mode::Body { line };
+                    return Step::Body;
+                }
+                let doc = &self.pending_heredocs[0];
+                let candidate = if doc.strip_tabs {
+                    line.trim_start_matches('\t')
+                } else {
+                    line.as_str()
+                };
+                if candidate == doc.delimiter {
+                    self.pending_heredocs.remove(0);
+                }
+                if !self.pending_heredocs.is_empty() {
+                    self.mode = Mode::Body {
+                        line: String::new(),
+                    };
+                }
+                Step::Body
+            }
+            Mode::Delimiter {
+                strip_tabs,
+                mut word,
+                started,
+                quote,
+            } => {
+                if let Some(q) = quote {
+                    if c != q {
+                        word.push(c);
+                    }
+                    let quote = if c == q { None } else { Some(q) };
+                    self.mode = Mode::Delimiter {
+                        strip_tabs,
+                        word,
+                        started: true,
+                        quote,
+                    };
+                    return Step::Body;
+                }
+                if !started && c == '-' && word.is_empty() && !strip_tabs {
+                    self.mode = Mode::Delimiter {
+                        strip_tabs: true,
+                        word,
+                        started: false,
+                        quote: None,
+                    };
+                    return Step::Body;
+                }
+                if !started && (c == ' ' || c == '\t') {
+                    self.mode = Mode::Delimiter {
+                        strip_tabs,
+                        word,
+                        started,
+                        quote: None,
+                    };
+                    return Step::Body;
+                }
+                let ends =
+                    c.is_whitespace() || matches!(c, ';' | '|' | '&' | '(' | ')' | '<' | '>');
+                if ends {
+                    if !word.is_empty() {
+                        self.pending_heredocs.push(Heredoc {
+                            delimiter: word,
+                            strip_tabs,
+                        });
+                    }
+                    // The terminator is ordinary code: reprocess it.
+                    return self.feed_inner(c);
+                }
+                if c == '\'' || c == '"' {
+                    self.mode = Mode::Delimiter {
+                        strip_tabs,
+                        word,
+                        started: true,
+                        quote: Some(c),
+                    };
+                    return Step::Body;
+                }
+                if c != '\\' {
+                    word.push(c);
+                }
+                self.mode = Mode::Delimiter {
+                    strip_tabs,
+                    word,
+                    started: true,
+                    quote: None,
+                };
+                Step::Body
+            }
+            Mode::Normal => self.feed_normal(c),
+        }
+    }
+
+    fn on_newline(&mut self) {
+        if !self.pending_heredocs.is_empty() {
+            self.mode = Mode::Body {
+                line: String::new(),
+            };
+        }
+    }
+
+    fn feed_normal(&mut self, c: char) -> Step {
+        match self.top() {
+            Frame::Single => {
+                if c == '\'' {
+                    self.stack.pop();
+                }
+                Step::Body
+            }
+            Frame::Double => {
+                match c {
+                    '\\' => self.mode = Mode::Escape,
+                    '"' => {
+                        self.stack.pop();
+                    }
+                    '(' if self.prev == Some('$') => self.push_code(),
+                    '`' => self.stack.push(Frame::Backtick),
+                    _ => {}
+                }
+                Step::Body
+            }
+            Frame::Backtick => {
+                match c {
+                    '\\' => self.mode = Mode::Escape,
+                    '`' => {
+                        self.stack.pop();
+                    }
+                    _ => {}
+                }
+                Step::Body
+            }
+            Frame::Code => self.feed_code(c),
+        }
+    }
+
+    fn push_code(&mut self) {
+        self.stack.push(Frame::Code);
+        self.parens.push(0);
+    }
+
+    fn feed_code(&mut self, c: char) -> Step {
+        let lt_run = if c == '<' { self.lt_run + 1 } else { 0 };
+        let heredoc_op = self.lt_run == 2 && c != '<' && self.arith_at.is_none();
+        self.lt_run = lt_run;
+        if heredoc_op {
+            // `<<` followed by something other than a third `<`.
+            self.mode = Mode::Delimiter {
+                strip_tabs: false,
+                word: String::new(),
+                started: false,
+                quote: None,
+            };
+            return self.feed_inner(c);
+        }
+        match c {
+            '\\' => self.mode = Mode::Escape,
+            '\'' => self.stack.push(Frame::Single),
+            '"' => self.stack.push(Frame::Double),
+            '`' => self.stack.push(Frame::Backtick),
+            '#' if self
+                .prev
+                .is_none_or(|p| p.is_whitespace() || matches!(p, ';' | '|' | '&' | '(' | ')')) =>
+            {
+                self.mode = Mode::Comment;
+            }
+            '\n' => self.on_newline(),
+            '(' => {
+                if let Some(depth) = self.parens.last_mut() {
+                    *depth += 1;
+                    if self.prev == Some('(') && self.arith_at.is_none() {
+                        self.arith_at = Some(depth.saturating_sub(2));
+                    }
+                }
+            }
+            ')' => {
+                let depth = self.parens.last_mut().expect("code frame");
+                if *depth > 0 {
+                    *depth -= 1;
+                    if self.arith_at.is_some_and(|at| *depth <= at) {
+                        self.arith_at = None;
+                    }
+                } else {
+                    // Closes this `$(` frame.
+                    self.parens.pop();
+                    self.stack.pop();
+                    if self.stack.is_empty() {
+                        return Step::Close;
+                    }
+                }
+            }
+            _ => {}
+        }
+        Step::Body
+    }
+}
+
+#[cfg(test)]
+/// Split `s` (the text after `$(`) at the matching `)`: returns the body and
+/// the byte offset just past the `)`, or `None` when unterminated.
+fn split_subst_body(s: &str) -> Option<(&str, usize)> {
+    let mut scanner = SubstScanner::new();
+    for (i, c) in s.char_indices() {
+        if scanner.feed(c) == Step::Close {
+            return Some((&s[..i], i + 1));
+        }
+    }
+    None
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn body(s: &str) -> Option<&str> {
+        split_subst_body(s).map(|(b, _)| b)
+    }
+
+    #[test]
+    fn plain_and_nested_parens() {
+        assert_eq!(body("echo hi) rest"), Some("echo hi"));
+        assert_eq!(body("(a) (b)) x"), Some("(a) (b)"));
+        assert_eq!(body("echo $(date)) x"), Some("echo $(date)"));
+    }
+
+    #[test]
+    fn quotes_hide_parens() {
+        assert_eq!(body("echo \")\") x"), Some("echo \")\""));
+        assert_eq!(body("echo ')') x"), Some("echo ')'"));
+        assert_eq!(body("echo \\)) x"), Some("echo \\)"));
+        assert_eq!(
+            body("echo \"$(echo ')')\") x"),
+            Some("echo \"$(echo ')')\"")
+        );
+        assert_eq!(body("echo `echo )`) x"), Some("echo `echo )`"));
+    }
+
+    #[test]
+    fn comments_hide_parens() {
+        assert_eq!(body("echo a # c)\n) x"), Some("echo a # c)\n"));
+        assert_eq!(body("echo a#b) x"), Some("echo a#b"));
+    }
+
+    #[test]
+    fn heredoc_bodies_hide_parens() {
+        assert_eq!(
+            body("cat <<'E'\nhello )\nE\n) x"),
+            Some("cat <<'E'\nhello )\nE\n")
+        );
+        assert_eq!(
+            body("cat <<-EOF\n\t( x\n\tEOF\n) x"),
+            Some("cat <<-EOF\n\t( x\n\tEOF\n")
+        );
+        assert_eq!(
+            body("cat <<A <<\"B\"\n)\nA\n)\nB\n) x"),
+            Some("cat <<A <<\"B\"\n)\nA\n)\nB\n")
+        );
+        // here-string is not a heredoc
+        assert_eq!(body("cat <<< x) y"), Some("cat <<< x"));
+        // arithmetic shift is not a heredoc
+        assert_eq!(body("echo $((1<<2))) y"), Some("echo $((1<<2))"));
+    }
+
+    #[test]
+    fn unterminated() {
+        assert_eq!(body("echo (hi"), None);
+        assert_eq!(body("cat <<E\n)\n"), None);
+    }
+}
diff --git a/crates/bashkit/tests/integration/main.rs b/crates/bashkit/tests/integration/main.rs
index a0821da85..213309aec 100644
--- a/crates/bashkit/tests/integration/main.rs
+++ b/crates/bashkit/tests/integration/main.rs
@@ -100,6 +100,7 @@ pub mod nested_subscript_tests;
 pub mod network_security_tests;
 pub mod output_truncation_tests;
 pub mod parallel_sessions_tests;
+pub mod partial_parse_tests;
 pub mod proptest_differential;
 pub mod python_integration_tests;
 pub mod python_security_tests;
diff --git a/crates/bashkit/tests/integration/partial_parse_tests.rs b/crates/bashkit/tests/integration/partial_parse_tests.rs
new file mode 100644
index 000000000..4656fc369
--- /dev/null
+++ b/crates/bashkit/tests/integration/partial_parse_tests.rs
@@ -0,0 +1,93 @@
+//! Bash reads a script line by line: commands before a syntax error run, then
+//! the error is reported with exit status 2. A syntax error used to discard
+//! the whole script, so agents lost all earlier work in a long heredoc'd
+//! script. Commands on the error's own line never run, as in bash.
+
+use bashkit::Bash;
+
+#[tokio::test]
+async fn commands_before_error_line_run() {
+    let mut bash = Bash::builder().build();
+    let r = bash
+        .exec("echo first\necho second\nif then\necho never")
+        .await
+        .unwrap();
+    assert_eq!(r.stdout, "first\nsecond\n");
+    assert_eq!(r.exit_code, 2);
+    assert!(r.stderr.contains("syntax error"), "stderr: {}", r.stderr);
+}
+
+#[tokio::test]
+async fn same_line_commands_do_not_run() {
+    let mut bash = Bash::builder().build();
+    let err = bash.exec("echo a; if then").await;
+    assert!(err.is_err(), "single-line syntax error stays a hard error");
+}
+
+#[tokio::test]
+async fn unterminated_compound_at_eof() {
+    let mut bash = Bash::builder().build();
+    let r = bash.exec("echo a\nfoo() {\necho x\n").await.unwrap();
+    assert_eq!(r.stdout, "a\n");
+    assert_eq!(r.exit_code, 2);
+}
+
+#[tokio::test]
+async fn side_effects_before_error_persist() {
+    let mut bash = Bash::builder().build();
+    let r = bash
+        .exec("mkdir -p /w && echo data > /w/f\nX=1\nfor x in; do\n")
+        .await
+        .unwrap();
+    assert_eq!(r.exit_code, 2);
+    let r = bash.exec("cat /w/f; echo $X").await.unwrap();
+    assert_eq!(r.stdout, "data\n1\n");
+}
+
+#[tokio::test]
+async fn exit_before_error_wins() {
+    let mut bash = Bash::builder().build();
+    let r = bash.exec("echo a\nexit 3\nif then").await.unwrap();
+    assert_eq!(r.stdout, "a\n");
+    assert_eq!(r.exit_code, 3);
+    assert!(!r.stderr.contains("syntax error"));
+}
+
+#[tokio::test]
+async fn errexit_before_error_wins() {
+    let mut bash = Bash::builder().build();
+    let r = bash.exec("set -e\nfalse\nif then").await.unwrap();
+    assert_eq!(r.exit_code, 1);
+    assert!(!r.stderr.contains("syntax error"));
+}
+
+#[tokio::test]
+async fn exit_trap_runs_after_syntax_error() {
+    let mut bash = Bash::builder().build();
+    let r = bash
+        .exec("trap 'echo bye' EXIT\necho hi\nif then")
+        .await
+        .unwrap();
+    assert_eq!(r.stdout, "hi\nbye\n");
+    assert_eq!(r.exit_code, 2);
+}
+
+#[tokio::test]
+async fn nested_bash_c_runs_prefix() {
+    let mut bash = Bash::builder().build();
+    let r = bash
+        .exec("bash -c $'echo in\\nif then'; echo rc=$?")
+        .await
+        .unwrap();
+    assert_eq!(r.stdout, "in\nrc=2\n");
+}
+
+#[tokio::test]
+async fn bash_n_still_rejects_whole_script() {
+    let mut bash = Bash::builder().build();
+    let r = bash
+        .exec("bash -n -c $'echo in\\nif then'; echo rc=$?")
+        .await
+        .unwrap();
+    assert_eq!(r.stdout, "rc=2\n");
+}
diff --git a/crates/bashkit/tests/spec_cases/bash/cmdsub-body-end.test.sh b/crates/bashkit/tests/spec_cases/bash/cmdsub-body-end.test.sh
new file mode 100644
index 000000000..308315446
--- /dev/null
+++ b/crates/bashkit/tests/spec_cases/bash/cmdsub-body-end.test.sh
@@ -0,0 +1,84 @@
+# The `)` that ends $(...) is found the way bash finds it: parens inside
+# quotes, escapes, comments and heredoc bodies do not close the substitution.
+
+### cmdsub_heredoc_with_paren
+x=$(cat <<'E'
+hello )
+E
+)
+echo "$x"
+### expect
+hello )
+### end
+
+### cmdsub_heredoc_in_double_quotes
+msg="$(cat <<'EOF'
+fix: thing (scope)
+
+body )
+EOF
+)"
+echo "$msg"
+### expect
+fix: thing (scope)
+
+body )
+### end
+
+### cmdsub_dash_heredoc
+x=$(cat <<-EOF
+	a ( b
+	EOF
+)
+echo "$x"
+### expect
+a ( b
+### end
+
+### cmdsub_quoted_paren
+x=$(echo ")"); echo "$x"
+y="$(echo ")")"; echo "$y"
+z=$(echo 'a)'); echo "$z"
+### expect
+)
+)
+a)
+### end
+
+### cmdsub_escaped_paren
+x=$(echo \)); echo "$x"
+### expect
+)
+### end
+
+### cmdsub_comment_with_paren
+x=$(echo a # c)
+)
+echo "$x"
+### expect
+a
+### end
+
+### cmdsub_arith_shift_not_heredoc
+echo $(echo $((1<<3)))
+### expect
+8
+### end
+
+### cmdsub_here_string
+x=$(cat <<< "hi)"); echo "$x"
+### expect
+hi)
+### end
+
+### syntax_error_runs_earlier_lines
+bash -c 'echo first
+echo second
+if then
+echo never' 2>/dev/null
+echo "rc=$?"
+### expect
+first
+second
+rc=2
+### end
diff --git a/knowledge/foundations/parser.md b/knowledge/foundations/parser.md
index 10fc524ee..1c4f9f453 100644
--- a/knowledge/foundations/parser.md
+++ b/knowledge/foundations/parser.md
@@ -87,6 +87,23 @@ TM-ESC-032), and the deferred error rejects the script the way bash does.
 Process substitution keeps its part for the same reason, and hard-errors on
 budget failures (TM-DOS-021).
 
+**Partial execution before a syntax error.** Bash reads and runs a script line
+by line, so `echo a` on line 1 runs before `if then` on line 2 is reported
+(exit 2). `Parser::parse_recovering` returns the complete top-level commands
+that ended on lines *before* the line where the failing command starts, plus
+the error; `Bash::exec` and child `bash`/`sh` run them and then report the
+error via `Script::trailing_error` (stderr + exit 2), unless `exit` or
+`set -e` stopped the script first. With nothing runnable before the error,
+`exec` still returns `Err(Parse)`. `bash -n` keeps whole-script rejection.
+Deferred `$(...)` errors carry no reliable position, so they never run a
+prefix.
+
+**End of `$(...)`.** `parser/subst_scan.rs` is the one scanner the lexer and
+`parse_word` share to find the closing `)`: it tracks quotes, escapes,
+backticks, nested `$(`, comments and heredoc bodies (`<<`, `<<-`, quoted
+delimiters; `<<<` and arithmetic `<<` excluded). Known gap: a bare `case`
+pattern `)` inside `$(...)` still closes early.
+
 ## Alternatives Considered
 
 - PEG (pest, pom): rejected, bash grammar is context-sensitive, here-docs awkward, manual parser gives better errors.