From a5c33f1f4db01877447ba67c0810a6d0381f3ec0 Mon Sep 17 00:00:00 2001
From: Mykhailo Chalyi <mike@chaliy.name>
Date: Sat, 10 Oct 2026 23:55:14 -0500
Subject: [PATCH 1/8] fix(tar): budget files-from storage before allocation

---
 crates/bashkit/docs/threat-model.md           |   2 +-
 crates/bashkit/src/builtins/archive.rs        | 100 +++++++--
 crates/bashkit/tests/integration/main.rs      |   1 +
 .../tar_files_from_budget_tests.rs            | 199 ++++++++++++++++++
 .../tests/tar_files_from_allocation_tests.rs  |  76 +++++++
 5 files changed, 356 insertions(+), 22 deletions(-)
 create mode 100644 crates/bashkit/tests/integration/tar_files_from_budget_tests.rs
 create mode 100644 crates/bashkit/tests/tar_files_from_allocation_tests.rs

diff --git a/crates/bashkit/docs/threat-model.md b/crates/bashkit/docs/threat-model.md
index bf8c23d3e..7bb773642 100644
--- a/crates/bashkit/docs/threat-model.md
+++ b/crates/bashkit/docs/threat-model.md
@@ -190,7 +190,7 @@ let bash = Bash::builder()
 | jq control normalization amplification (TM-DOS-100) | Literal controls expand sixfold as `\u00XX` | Charge single-pass work and lease live bytes before allocation growth | MITIGATED |
 | yq structured-data amplification (TM-DOS-101) | Deep/multi-document YAML or JSON, runaway filters, expanded output | Parser depth and 4096-document caps, aggregate budgets, shared jaq work/deadline/output limits, final render cap | MITIGATED |
 | Archive decoder pre-allocation (TM-DOS-102) | Compressed output grows before memory checks | Validate and charge each decoder chunk before reserve/copy | MITIGATED |
-| Post-allocation charging (TM-DOS-103) | Archive/compression buffers grow before their live-byte check | Owning budget-aware string/vector/byte builders charge before reserve, roll back errors, and release on drop | MITIGATED |
+| Post-allocation charging (TM-DOS-103) | Archive/compression buffers or tar file-list names grow before their live-byte check | Owning budget-aware string/vector/byte builders charge before reserve, roll back errors, and release on drop; tar file lists also lease raw reads and charge per-line work | MITIGATED |
 | Pipeline stderr aggregation (TM-DOS-104) | Many stderr-producing pipeline stages accumulate past the output cap | Stop appending at `max_stderr_bytes` and propagate the truncation flag to the result | MITIGATED |
 | Zip creation pre-allocation (TM-DOS-106) | Recursive inputs and encoded output allocate before live-memory checks | Collect paths only, lease file sizes before VFS reads, and encode through a budget-aware byte buffer | MITIGATED |
 | Analysis command-name validation (TM-DOS-107) | A huge comment before thousands of commands makes validation rescan the source per command | Index source character positions once, then binary-search each name | MITIGATED |
diff --git a/crates/bashkit/src/builtins/archive.rs b/crates/bashkit/src/builtins/archive.rs
index 5f74d6c44..955cdf75c 100644
--- a/crates/bashkit/src/builtins/archive.rs
+++ b/crates/bashkit/src/builtins/archive.rs
@@ -10,6 +10,9 @@
 //! normalize it to the regular short-option path instead of maintaining a
 //! second parser.
 //!
+//! File lists retain budget-owned names, never an eager `Vec<String>`; raw
+//! reads are admitted by metadata size and every line checks shared work.
+//!
 //! bzip2 0.6 uses the maintained pure-Rust libbz2-rs backend by default. Its
 //! fixed codec state plus bounded, pre-charged output avoids native-library
 //! deployment differences while retaining standard bzip2 CRC validation.
@@ -77,6 +80,29 @@ fn budgeted_vec<T>(ctx: &Context<'_>) -> Result<BudgetedVec<T>> {
     with_execution_budget(ctx, |budget| BudgetedVec::new(budget).map_err(Into::into))
 }
 
+// THREAT[TM-DOS-103]: Decode directly into admitted storage, including UTF-8
+// replacement expansion. `from_utf8_lossy(...).into_owned()` allocates first.
+fn tar_list_name(ctx: &Context<'_>, mut bytes: &[u8]) -> Result<BudgetedString> {
+    let mut name = budgeted_string(ctx)?;
+    while !bytes.is_empty() {
+        ctx.consume_budget_work(1)?;
+        match std::str::from_utf8(bytes) {
+            Ok(text) => {
+                name.try_push_str(text)?;
+                break;
+            }
+            Err(error) => {
+                let valid = error.valid_up_to();
+                name.try_push_str(std::str::from_utf8(&bytes[..valid]).unwrap())?;
+                name.try_push('\u{fffd}')?;
+                let invalid = error.error_len().unwrap_or(bytes.len() - valid);
+                bytes = &bytes[valid + invalid..];
+            }
+        }
+    }
+    Ok(name)
+}
+
 #[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
 enum ArchiveCompression {
     #[default]
@@ -397,34 +423,66 @@ impl Builtin for Tar {
 
         // `-T FILE` / `--files-from=FILE`: one member name per line, blank
         // lines skipped, `-` reads stdin.
-        let mut listed_names: Vec<String> = Vec::new();
+        // THREAT[TM-DOS-103]: Both name capacity and vector slots must be
+        // charged before allocation, even when the members do not exist.
+        let mut listed_names = budgeted_vec(&ctx)?;
         for list in &files_from {
+            let missing_list = || {
+                ExecResult::err(
+                    format!(
+                        "tar: {list}: Cannot stat: No such file or directory\ntar: Error is not recoverable: exiting now\n"
+                    ),
+                    2,
+                )
+            };
+            let bytes;
+            let _read_lease;
+            let _extra_lease;
             let content = if list == "-" {
-                String::from_utf8_lossy(ctx.stdin_bytes().unwrap_or_default()).into_owned()
+                let input = ctx.stdin_bytes().unwrap_or_default();
+                ctx.consume_budget_input(input.len())?;
+                input
             } else {
                 let path = resolve_path(ctx.cwd, list);
-                match ctx.fs.read_file(&path).await {
-                    Ok(bytes) => String::from_utf8_lossy(&bytes).into_owned(),
-                    Err(_) => {
-                        return Ok(ExecResult::err(
-                            format!(
-                                "tar: {list}: Cannot stat: No such file or directory\ntar: Error is not recoverable: exiting now\n"
-                            ),
-                            2,
-                        ));
+                let metadata = match ctx.fs.stat(&path).await {
+                    Ok(metadata) => metadata,
+                    Err(error @ (crate::Error::ResourceLimit(_) | crate::Error::Cancelled)) => {
+                        return Err(error);
                     }
-                }
+                    Err(_) => return Ok(missing_list()),
+                };
+                let size = usize::try_from(metadata.size).unwrap_or(usize::MAX);
+                ctx.consume_budget_input(size)?;
+                _read_lease = ctx.lease_budget_bytes(size)?;
+                bytes = match ctx.fs.read_file(&path).await {
+                    Ok(bytes) => bytes,
+                    Err(error @ (crate::Error::ResourceLimit(_) | crate::Error::Cancelled)) => {
+                        return Err(error);
+                    }
+                    Err(_) => return Ok(missing_list()),
+                };
+                // Host-backed files may grow between stat/read; the backend
+                // owns read-allocation admission, as for other VFS consumers.
+                ctx.consume_budget_input(bytes.len().saturating_sub(size))?;
+                _extra_lease = ctx.lease_budget_bytes(bytes.capacity().saturating_sub(size))?;
+                bytes.as_slice()
             };
-            ctx.consume_budget_input(content.len())?;
-            listed_names.extend(
-                content
-                    .lines()
-                    .filter(|l| !l.is_empty())
-                    .map(str::to_string),
-            );
+            ctx.consume_budget_work(u64::try_from(content.len().div_ceil(64)).unwrap_or(u64::MAX))?;
+            for line in content.split_inclusive(|byte| *byte == b'\n') {
+                ctx.consume_budget_work(1)?;
+                // Match str::lines(): strip CR only as part of CRLF.
+                let line = if let Some(line) = line.strip_suffix(b"\n") {
+                    line.strip_suffix(b"\r").unwrap_or(line)
+                } else {
+                    line
+                };
+                if !line.is_empty() {
+                    listed_names.try_push(tar_list_name(&ctx, line)?)?;
+                }
+            }
         }
-        for name in &listed_names {
-            files.try_push(name.as_str())?;
+        for name in &*listed_names {
+            files.try_push(&**name)?;
         }
 
         // Check for exactly one of -c, -x, -t
diff --git a/crates/bashkit/tests/integration/main.rs b/crates/bashkit/tests/integration/main.rs
index 28019d11d..43f973d15 100644
--- a/crates/bashkit/tests/integration/main.rs
+++ b/crates/bashkit/tests/integration/main.rs
@@ -53,6 +53,7 @@ pub mod custom_fs_tests;
 pub mod function_metadata_security_tests;
 pub mod interactive_builtins_tests;
 pub mod memory_growth_security_tests;
+pub mod tar_files_from_budget_tests;
 // Both assert named-IANA-zone behavior, which only exists with `tzdata`.
 // `date_timezone_no_tzdata_tests` covers the closed-to-UTC side.
 pub mod cpython_capability_tests;
diff --git a/crates/bashkit/tests/integration/tar_files_from_budget_tests.rs b/crates/bashkit/tests/integration/tar_files_from_budget_tests.rs
new file mode 100644
index 000000000..4f07596c2
--- /dev/null
+++ b/crates/bashkit/tests/integration/tar_files_from_budget_tests.rs
@@ -0,0 +1,199 @@
+use bashkit::{
+    Bash, Error, ExecOptions, ExecutionBudgetExceeded, ExecutionLimits, LimitExceeded, StreamData,
+};
+use std::path::Path;
+
+#[tokio::test]
+async fn tar_files_from_large_content_obeys_live_budget() {
+    for content in [vec![b'x'; 20_000], vec![0xff; 4000]] {
+        let mut bash = Bash::builder()
+            .limits(ExecutionLimits::new().max_live_intermediate_bytes(8192))
+            .build();
+        bash.fs()
+            .write_file(Path::new("/list"), &content)
+            .await
+            .unwrap();
+        let result = bash.exec("tar -cf /out.tar -T /list").await;
+        assert!(
+            matches!(
+                result,
+                Err(Error::ResourceLimit(LimitExceeded::ExecutionBudget(
+                    ExecutionBudgetExceeded::LiveBytes { .. }
+                )))
+            ),
+            "expected budget rejection"
+        );
+        assert_eq!(
+            bash.exec("echo recovered").await.unwrap().stdout,
+            "recovered\n"
+        );
+    }
+}
+
+#[tokio::test]
+async fn tar_files_from_dense_lines_obey_work_budget() {
+    for content in ["x\n".repeat(2000), "\n".repeat(2000), "x".repeat(20_000)] {
+        let mut bash = Bash::builder()
+            .limits(ExecutionLimits::new().max_work_units(100))
+            .build();
+        bash.fs()
+            .write_file(Path::new("/list"), content.as_bytes())
+            .await
+            .unwrap();
+        let result = bash.exec("tar -cf /out.tar -T /list").await;
+        assert!(
+            matches!(
+                result,
+                Err(Error::ResourceLimit(LimitExceeded::ExecutionBudget(
+                    ExecutionBudgetExceeded::WorkUnits { .. }
+                )))
+            ),
+            "expected budget rejection"
+        );
+        assert_eq!(
+            bash.exec("echo recovered").await.unwrap().stdout,
+            "recovered\n"
+        );
+    }
+}
+
+#[tokio::test]
+async fn tar_files_from_stdin_and_repeated_lists_obey_live_budget() {
+    for (script, content) in [
+        ("tar -cf /out.tar -T -".to_string(), "x".repeat(20_000)),
+        (
+            format!("tar -cf /out.tar {}", "-T /list ".repeat(40)),
+            format!("{}\n", "x".repeat(256)),
+        ),
+    ] {
+        let mut bash = Bash::builder()
+            .limits(ExecutionLimits::new().max_live_intermediate_bytes(8192))
+            .build();
+        bash.fs()
+            .write_file(Path::new("/list"), content.as_bytes())
+            .await
+            .unwrap();
+        let result = bash
+            .exec_with_options(&script, ExecOptions::new().stdin(StreamData::from(content)))
+            .await;
+        assert!(
+            matches!(
+                result,
+                Err(Error::ResourceLimit(LimitExceeded::ExecutionBudget(
+                    ExecutionBudgetExceeded::LiveBytes { .. }
+                )))
+            ),
+            "expected budget rejection"
+        );
+        assert!(!bash.fs().exists(Path::new("/out.tar")).await.unwrap());
+        assert_eq!(
+            bash.exec("echo recovered").await.unwrap().stdout,
+            "recovered\n"
+        );
+    }
+}
+
+#[tokio::test]
+async fn tar_files_from_content_boundary_and_empty_lists() {
+    for (bytes, succeeds) in [(8000, true), (8192, false), (8193, false)] {
+        let mut bash = Bash::builder()
+            .limits(ExecutionLimits::new().max_live_intermediate_bytes(8192))
+            .build();
+        bash.fs()
+            .write_file(Path::new("/list"), &vec![b'\n'; bytes])
+            .await
+            .unwrap();
+        let result = bash.exec("tar -cf /out.tar -T /list").await;
+        if succeeds {
+            let result = result.unwrap();
+            assert_eq!(result.exit_code, 2);
+            assert!(result.stderr.contains("empty archive"));
+        } else {
+            assert!(
+                matches!(
+                    result,
+                    Err(Error::ResourceLimit(LimitExceeded::ExecutionBudget(
+                        ExecutionBudgetExceeded::LiveBytes { .. }
+                    )))
+                ),
+                "expected budget rejection"
+            );
+        }
+    }
+}
+
+#[tokio::test]
+async fn tar_files_from_preserves_order_duplicates_crlf_and_lossy_names() {
+    let mut bash = Bash::new();
+    for name in ["a", "b", "\u{fffd}"] {
+        bash.fs()
+            .write_file(Path::new(&format!("/{name}")), b"data")
+            .await
+            .unwrap();
+    }
+    bash.fs()
+        .write_file(Path::new("/list"), b"a\r\n\nb\na\n\xff")
+        .await
+        .unwrap();
+    let result = bash
+        .exec("cd /; tar -cf /out.tar -T /list; tar -tf /out.tar")
+        .await
+        .unwrap();
+    assert_eq!(result.exit_code, 0, "{}", result.stderr);
+    assert_eq!(result.stdout, "a\nb\na\n\u{fffd}\n");
+}
+
+#[tokio::test]
+async fn tar_files_from_matches_real_bash_tar() {
+    let script = "printf a > a; printf b > b; printf 'a\\n\\nb\\na' > list; cp list list2; tar -cf out.tar -T list --files-from=list2; tar -tf out.tar; printf 'b\\n' | tar -cf stdin.tar -T -; tar -tf stdin.tar";
+    let mut bash = Bash::new();
+    let actual = bash.exec(script).await.unwrap();
+    let temp = tempfile::tempdir().unwrap();
+    let host_script = if std::process::Command::new("gtar")
+        .arg("--version")
+        .output()
+        .is_ok()
+    {
+        script
+            .replace("; tar ", "; gtar ")
+            .replace("| tar ", "| gtar ")
+    } else {
+        script.to_string()
+    };
+    let expected = std::process::Command::new("bash")
+        .args(["-c", &host_script])
+        .env("COPYFILE_DISABLE", "1")
+        .current_dir(temp.path())
+        .output()
+        .unwrap();
+    assert!(
+        expected.status.success(),
+        "{}",
+        String::from_utf8_lossy(&expected.stderr)
+    );
+    assert_eq!(actual.exit_code, 0, "{}", actual.stderr);
+    assert_eq!(actual.stdout.as_bytes(), expected.stdout);
+}
+
+#[tokio::test]
+async fn tar_files_from_repeated_reads_share_input_budget() {
+    let mut bash = Bash::builder()
+        .limits(ExecutionLimits::new().max_aggregate_input_bytes(100))
+        .build();
+    bash.fs()
+        .write_file(Path::new("/list"), "a\n".repeat(20).as_bytes())
+        .await
+        .unwrap();
+    let result = bash.exec("tar -cf /out.tar -T /list -T /list").await;
+    assert!(matches!(
+        result,
+        Err(Error::ResourceLimit(LimitExceeded::ExecutionBudget(
+            ExecutionBudgetExceeded::InputBytes { .. }
+        )))
+    ));
+    assert!(!bash.fs().exists(Path::new("/out.tar")).await.unwrap());
+    assert_eq!(
+        bash.exec("echo recovered").await.unwrap().stdout,
+        "recovered\n"
+    );
+}
diff --git a/crates/bashkit/tests/tar_files_from_allocation_tests.rs b/crates/bashkit/tests/tar_files_from_allocation_tests.rs
new file mode 100644
index 000000000..94c6ffcd7
--- /dev/null
+++ b/crates/bashkit/tests/tar_files_from_allocation_tests.rs
@@ -0,0 +1,76 @@
+//! Tar file-list allocation regression. The allocator is process-wide,
+//! so this test needs its own binary to exclude unrelated test allocations.
+
+use std::alloc::{GlobalAlloc, Layout, System};
+use std::sync::atomic::{AtomicUsize, Ordering};
+
+use bashkit::{Bash, Error, ExecOptions, ExecutionLimits, LimitExceeded, StreamData};
+use std::path::Path;
+
+static LIVE: AtomicUsize = AtomicUsize::new(0);
+static PEAK: AtomicUsize = AtomicUsize::new(0);
+
+/// Tracks live heap bytes and their high-water mark.
+struct Counting;
+
+unsafe impl GlobalAlloc for Counting {
+    unsafe fn alloc(&self, layout: Layout) -> *mut u8 {
+        let ptr = unsafe { System.alloc(layout) };
+        if !ptr.is_null() {
+            let live = LIVE.fetch_add(layout.size(), Ordering::Relaxed) + layout.size();
+            PEAK.fetch_max(live, Ordering::Relaxed);
+        }
+        ptr
+    }
+
+    unsafe fn dealloc(&self, ptr: *mut u8, layout: Layout) {
+        LIVE.fetch_sub(layout.size(), Ordering::Relaxed);
+        unsafe { System.dealloc(ptr, layout) };
+    }
+}
+
+#[global_allocator]
+static ALLOCATOR: Counting = Counting;
+
+#[tokio::test(flavor = "current_thread")]
+async fn tar_files_from_rejects_before_per_line_allocation_amplification() {
+    for options in [
+        "-T /list",
+        "--files-from=/list",
+        "--files-from /list",
+        "-T /list -T /list",
+        "-T -",
+    ] {
+        let mut bash = Bash::builder()
+            .limits(ExecutionLimits::new().max_live_intermediate_bytes(65_536))
+            .build();
+        bash.fs()
+            .write_file(Path::new("/list"), "x\n".repeat(20_000).as_bytes())
+            .await
+            .unwrap();
+        bash.exec("true").await.unwrap();
+        let stdin = ExecOptions::new().stdin(StreamData::from("x\n".repeat(20_000)));
+        let before = LIVE.load(Ordering::Relaxed);
+        PEAK.store(before, Ordering::Relaxed);
+        let result = bash
+            .exec_with_options(&format!("tar -cf /out.tar {options}"), stdin)
+            .await;
+        let peak = PEAK.load(Ordering::Relaxed).saturating_sub(before);
+        assert!(
+            matches!(
+                result,
+                Err(Error::ResourceLimit(LimitExceeded::ExecutionBudget(_)))
+            ),
+            "{result:?}"
+        );
+        eprintln!("{options}: peak heap growth {peak} bytes");
+        // Includes interpreter overhead and the VFS read; the old collector
+        // retained over 800 KiB before its first live-budget rejection.
+        assert!(peak < 256 * 1024, "unbudgeted list amplification: {peak}");
+        assert!(!bash.fs().exists(Path::new("/out.tar")).await.unwrap());
+        assert_eq!(
+            bash.exec("echo recovered").await.unwrap().stdout,
+            "recovered\n"
+        );
+    }
+}

From d8bb6161fe3da9aa5fd94e5c5219fe2b6a1ec2fd Mon Sep 17 00:00:00 2001
From: Mykhailo Chalyi <mike@chaliy.name>
Date: Sat, 10 Oct 2026 23:55:14 -0500
Subject: [PATCH 2/8] chore(knowledge): document tar file-list resource
 admission

---
 knowledge/foundations/builtins.md  | 14 ++++++++++++++
 knowledge/operations/testing.md    |  7 +++++++
 knowledge/security/threat-model.md |  2 +-
 3 files changed, 22 insertions(+), 1 deletion(-)

diff --git a/knowledge/foundations/builtins.md b/knowledge/foundations/builtins.md
index 9549510eb..c8b90df0e 100644
--- a/knowledge/foundations/builtins.md
+++ b/knowledge/foundations/builtins.md
@@ -652,6 +652,20 @@ bundles (`-cjf`, `cjf`) and `--bzip2`, and detects gzip/bzip2 magic while listin
 or extracting so `.tar.bz2`/`.tbz2` inputs work without an explicit codec flag.
 `bzip2`, `bunzip2`, and `bzcat` share the same byte-native codec path.
 
+`tar -T` / `--files-from` admits each VFS read using its metadata size,
+retains the read lease through parsing, and charges any extra returned capacity.
+The filesystem backend owns allocation admission if a host-backed file grows
+between stat and read. Stdin is borrowed. Names are decoded directly into
+`BudgetedString` owners held by a `BudgetedVec`; neither per-line copies nor
+lossy UTF-8 replacement can allocate before live-budget admission. Shared work
+charges cover source bytes, every line (including blanks), and decoding steps,
+checking the request deadline/cancellation during dense-list scans. Repeated
+sources share input/live/work budgets, preserving order, duplicates, CRLF,
+blank lines, stdin, and missing-member behavior. Tests:
+`tar_files_from_budget_tests` and the isolated counting-allocator
+`tar_files_from_allocation_tests` (TM-DOS-103).
+
+
 The implementation uses `bzip2` 0.6 with its default pure-Rust
 `libbz2-rs-sys` backend. The crate is maintained by the Trifecta Tech
 Foundation, dual MIT/Apache-2.0; its backend retains the permissive
diff --git a/knowledge/operations/testing.md b/knowledge/operations/testing.md
index 878d8da35..f98d9f233 100644
--- a/knowledge/operations/testing.md
+++ b/knowledge/operations/testing.md
@@ -94,6 +94,13 @@ bounded 1,024-entry / 1,024-byte-target request that previously retained over
 1 MiB of candidate paths. It complements the shared-budget integration tests
 rather than substituting budget counters for an actual allocation measurement.
 
+`tar_files_from_allocation_tests.rs` also needs its own binary for its
+process-wide counting allocator. It uses a 40 KB newline-dense list and a
+64 KB live budget through `Bash::exec`, rejecting the former >1 MB eager
+collector peak while asserting bounded rejection and subsequent session use.
+The consolidated `tar_files_from_budget_tests` covers live/input/work limits,
+stdin, repeated lists, blank/CRLF/lossy names, and GNU tar differential behavior.
+
 Filtering still works as usual: `cargo test --test integration -- foo`
 matches `integration::*::foo*` test paths.
 
diff --git a/knowledge/security/threat-model.md b/knowledge/security/threat-model.md
index f09fb23da..fd656aaa2 100644
--- a/knowledge/security/threat-model.md
+++ b/knowledge/security/threat-model.md
@@ -1416,7 +1416,7 @@ This section maps former vulnerability IDs to the new threat ID scheme and track
 | TM-DOS-100 | jq control-character normalization amplification | A jq JSON string consisting of literal controls expands sixfold when each byte becomes `\u00XX`; an unmetered compatibility copy can exhaust memory or CPU before strict parsing | The jq-only normalizer charges input-length work before its single pass, borrows unchanged input, and acquires/grows a shared live-intermediate lease before every allocation growth (`builtins/jq/input.rs`), **MITIGATED** |
 | TM-DOS-101 | yq structured-data amplification | YAML aliases, YAML/JSON nesting, multi-document floods, filters, and output format expansion are all attacker-controlled | A pre-deserialization lexical pass rejects aliases without misclassifying quoted or block scalar content; real parsers with recursion/depth caps, aggregate budgets, shared jaq work/deadline/output controls, and a final rendered-output cap; integration tests cover alias bombs plus YAML+JSON depth/document/input/output bounds, proptest composes arbitrary YAML+filters, and `yq_fuzz` covers stdin/in-place format paths, **MITIGATED** |
 | TM-DOS-102 | Archive decoder allocation-before-check | A small gzip/bzip2 stream makes the decoder output buffer allocate beyond live-memory or filesystem quotas before the post-growth size check runs | Decoder chunks validate absolute/ratio bounds and acquire a shared execution-budget lease before `try_reserve_exact` and copy; corrupt, truncated, CRC-invalid, ratio-bomb, and live-budget tests fail closed, **MITIGATED** |
-| TM-DOS-103 | Post-allocation resource charging | Archive/compression and other growing buffers could call `reserve`/`extend` before taking a live-byte lease; concurrent `fetch_add` accounting could also wrap or transiently overcommit the ceiling | `BudgetedVec`/`BudgetedBytes` and `BudgetedString` own their `ExecutionBudgetLease`, charge planned capacity before `try_reserve_exact`, roll back on allocation/error, and release on drop. CAS admission rejects overflow and concurrent overcommit. Archive creation, extraction/list output, gzip/bzip2 encoders, decompression, and `od` output use the builders. `od` rejects widths above 65,536 bytes before layout arithmetic (including empty input), pads only a single <= 8-byte field on the stack, uses u64 padding products for 32-bit safety, and charges input/field rendering work; `od_resource_tests` cover huge-width rejection, boundary formatting, live/work budgets, and subsequent execution, **MITIGATED** |
+| TM-DOS-103 | Post-allocation resource charging | Archive/compression and other growing buffers could call `reserve`/`extend` before taking a live-byte lease; concurrent `fetch_add` accounting could also wrap or transiently overcommit the ceiling | `BudgetedVec`/`BudgetedBytes` and `BudgetedString` own their `ExecutionBudgetLease`, charge planned capacity before `try_reserve_exact`, roll back on allocation/error, and release on drop. CAS admission rejects overflow and concurrent overcommit. Archive creation, extraction/list output, gzip/bzip2 encoders, decompression, and `od` output use the builders. Tar `-T`/`--files-from` leases raw list reads before VFS loading, retains budget-owned names/vector capacity, decodes lossy UTF-8 directly into admitted storage, and charges bytes/lines/decoding work; bounded allocation regressions include nonexistent names, repeated lists, stdin, and session recovery. `od` rejects widths above 65,536 bytes before layout arithmetic (including empty input), pads only a single <= 8-byte field on the stack, uses u64 padding products for 32-bit safety, and charges input/field rendering work; `od_resource_tests` cover huge-width rejection, boundary formatting, live/work budgets, and subsequent execution, **MITIGATED** |
 | TM-DOS-104 | Pipeline stderr aggregation exceeds the configured output cap before final truncation | A pipeline with many stderr-producing stages can accumulate their combined diagnostics in memory | The pipeline aggregate stops appending at `max_stderr_bytes` and propagates its truncation signal to the final result, **MITIGATED** |
 | TM-DOS-106 | Zip creation allocation-before-check | `zip` recursively collected complete file contents and encoded its output before acquiring live-byte leases, allowing transient allocations above the configured intermediate-memory ceiling | Zip traversal collects paths only; each VFS file size is leased before `read_file`, leases remain live with the entries, and archive encoding uses `BudgetedBytes` to charge capacity before growth — **MITIGATED** |
 | TM-DOS-108 | CLI host-stdin read can stall before execution | A producer keeps the one-shot CLI's stdin pipe open while idle or trickles fewer than 10 MiB, so the pre-execution read never reaches EOF or the byte cap | Read stdin on a dedicated thread and bound the wait with the selected execution timeout; timeout exits with a diagnostic suggesting `--no-stdin`, while the existing byte cap remains enforced — **MITIGATED** |

From eea62b732a0b0f349b05ce53e0b9e09851eb5bd5 Mon Sep 17 00:00:00 2001
From: Mykhailo Chalyi <mike@chaliy.name>
Date: Sun, 11 Oct 2026 00:16:09 -0500
Subject: [PATCH 3/8] test(tar): verify lossy decoding and malformed-input work
 limits

---
 crates/bashkit/src/builtins/archive.rs        | 30 +++++++++++++++++++
 .../tar_files_from_budget_tests.rs            |  9 ++++--
 2 files changed, 37 insertions(+), 2 deletions(-)

diff --git a/crates/bashkit/src/builtins/archive.rs b/crates/bashkit/src/builtins/archive.rs
index 955cdf75c..544ebd5bf 100644
--- a/crates/bashkit/src/builtins/archive.rs
+++ b/crates/bashkit/src/builtins/archive.rs
@@ -1952,6 +1952,36 @@ mod tests {
 
     // ==================== tar tests ====================
 
+    #[tokio::test]
+    async fn tar_files_from_lossy_decoder_matches_std() {
+        let (fs, mut cwd, mut variables) = create_test_ctx().await;
+        let env = HashMap::new();
+        let ctx = Context {
+            args: &[],
+            env: &env,
+            variables: &mut variables,
+            cwd: &mut cwd,
+            fs,
+            stdin: None,
+            #[cfg(feature = "http_client")]
+            http_client: None,
+            #[cfg(feature = "git")]
+            git_client: None,
+            #[cfg(feature = "ssh")]
+            ssh_client: None,
+            shell: None,
+        };
+        // Valid prefixes, malformed multi-byte sequences, and incomplete
+        // tails must retain the previous standard-library decoding semantics.
+        for byte in 0..=255 {
+            let bytes = [b'A', byte, 0xf0, 0x9f, 0x92, byte, b'Z', 0xe2, 0x82];
+            for input in [bytes.as_slice(), &bytes[..7]] {
+                let name = tar_list_name(&ctx, input).unwrap();
+                assert_eq!(&*name, String::from_utf8_lossy(input).as_ref());
+            }
+        }
+    }
+
     #[tokio::test]
     async fn test_tar_create_and_list() {
         let (fs, mut cwd, mut variables) = create_test_ctx().await;
diff --git a/crates/bashkit/tests/integration/tar_files_from_budget_tests.rs b/crates/bashkit/tests/integration/tar_files_from_budget_tests.rs
index 4f07596c2..72f24067c 100644
--- a/crates/bashkit/tests/integration/tar_files_from_budget_tests.rs
+++ b/crates/bashkit/tests/integration/tar_files_from_budget_tests.rs
@@ -32,12 +32,17 @@ async fn tar_files_from_large_content_obeys_live_budget() {
 
 #[tokio::test]
 async fn tar_files_from_dense_lines_obey_work_budget() {
-    for content in ["x\n".repeat(2000), "\n".repeat(2000), "x".repeat(20_000)] {
+    for content in [
+        "x\n".repeat(2000).into_bytes(),
+        "\n".repeat(2000).into_bytes(),
+        "x".repeat(20_000).into_bytes(),
+        vec![0xff; 128],
+    ] {
         let mut bash = Bash::builder()
             .limits(ExecutionLimits::new().max_work_units(100))
             .build();
         bash.fs()
-            .write_file(Path::new("/list"), content.as_bytes())
+            .write_file(Path::new("/list"), &content)
             .await
             .unwrap();
         let result = bash.exec("tar -cf /out.tar -T /list").await;

From 4b333e0ee67df716f1786d8766c1577ca492abac Mon Sep 17 00:00:00 2001
From: Mykhailo Chalyi <mike@chaliy.name>
Date: Sun, 11 Oct 2026 00:26:47 -0500
Subject: [PATCH 4/8] chore(knowledge): conform tar admission notes to OKF
 formatting

---
 knowledge/foundations/builtins.md | 1 -
 1 file changed, 1 deletion(-)

diff --git a/knowledge/foundations/builtins.md b/knowledge/foundations/builtins.md
index c8b90df0e..909f869f5 100644
--- a/knowledge/foundations/builtins.md
+++ b/knowledge/foundations/builtins.md
@@ -665,7 +665,6 @@ blank lines, stdin, and missing-member behavior. Tests:
 `tar_files_from_budget_tests` and the isolated counting-allocator
 `tar_files_from_allocation_tests` (TM-DOS-103).
 
-
 The implementation uses `bzip2` 0.6 with its default pure-Rust
 `libbz2-rs-sys` backend. The crate is maintained by the Trifecta Tech
 Foundation, dual MIT/Apache-2.0; its backend retains the permissive

From 73e27ed4f50698ecea907e5f502cdac3217530a3 Mon Sep 17 00:00:00 2001
From: Mykhailo Chalyi <mike@chaliy.name>
Date: Sun, 11 Oct 2026 13:10:15 -0500
Subject: [PATCH 5/8] fix(parser): bound nested substitution stack frames

---
 crates/bashkit/docs/threat-model.md           |   11 +-
 crates/bashkit/src/parser/mod.rs              | 2071 +++++++++--------
 .../integration/blackbox_security_tests.rs    |   53 +
 3 files changed, 1189 insertions(+), 946 deletions(-)

diff --git a/crates/bashkit/docs/threat-model.md b/crates/bashkit/docs/threat-model.md
index 511c233f5..9d694185f 100644
--- a/crates/bashkit/docs/threat-model.md
+++ b/crates/bashkit/docs/threat-model.md
@@ -111,7 +111,7 @@ through configurable limits.
 | Brace range OOM (TM-DOS-041) | `{1..999999999}` | Cap range size | **MITIGATED** |
 | Brace combinatorial (TM-DOS-042) | `{1..100}{1..100}{1..100}` | Cap total expansion | **MITIGATED** |
 | Compound assign overflow (TM-DOS-043) | `((x+=1))` with x=i64::MAX | `wrapping_*` ops | **MITIGATED** |
-| Lexer stack overflow (TM-DOS-044) | ~50 nested `$()` in quotes | Depth tracking | **MITIGATED** |
+| Lexer stack overflow (TM-DOS-044) | ~50 nested `$()` in quotes | Shared AST depth, heap-owned child parsers, outlined nonrecursive parser frames | **MITIGATED** |
 | parse_word_string limits (TM-DOS-050) | Parameter expansion ignores limits | Propagate limits | **MITIGATED** |
 | Removed YAML helper parser (TM-DOS-051) | Former custom parser recursed over indentation | Parser deleted; yq uses TM-DOS-101 controls | **REMOVED** |
 | Template engine recursion (TM-DOS-052) | Nested `{{#if}}`/`{{#each}}` overflow | Add depth limit | **MITIGATED** |
@@ -656,15 +656,18 @@ The parser includes multiple layers of depth protection to prevent stack overflo
 attacks:
 
 1. **Configurable depth limit** (`max_ast_depth`, default 100): Controls maximum nesting
-   of compound commands (if/for/while/case/subshell).
+   of compound commands (if/for/while/case/subshell) and substitutions.
 
 2. **Hard cap** (`HARD_MAX_AST_DEPTH = 100`): Even if the caller configures a higher
    `max_ast_depth`, the parser clamps it to 100. This prevents misconfiguration from
    causing stack overflow.
 
 3. **Child parser inheritance** (TM-DOS-021): When parsing `$(...)` or `<(...)`,
-   the child parser inherits the *remaining* depth budget and fuel from the parent.
-   This prevents attackers from bypassing depth limits through nested substitutions.
+   each substitution consumes one level of the enclosing AST depth. Command
+   substitution child parsers inherit the same ceiling, remaining fuel, execution
+   budget, and timeout origin, and stay heap-owned while parsing. Nonrecursive
+   parameter parsing and AST assembly run outside recursive frames, keeping the
+   unchanged hard ceiling safe on default 2 MiB Rust test-thread stacks.
 
 4. **Arithmetic depth limit** (TM-DOS-026): The arithmetic evaluator (`$((expr))`)
    has its own depth limit (`MAX_ARITHMETIC_DEPTH = 50`) to prevent stack overflow
diff --git a/crates/bashkit/src/parser/mod.rs b/crates/bashkit/src/parser/mod.rs
index b68384495..bb44d0e52 100644
--- a/crates/bashkit/src/parser/mod.rs
+++ b/crates/bashkit/src/parser/mod.rs
@@ -4,6 +4,10 @@
 //!
 //! # Design Notes
 //!
+//! Substitution parsers share the enclosing AST depth and start time. Keep child
+//! parsers heap-owned and nonrecursive AST assembly out of recursive frames so
+//! the hard depth ceiling is safe on default 2 MiB test-thread stacks (TM-DOS-044).
+//!
 //! Reserved words (like `done`, `fi`, `then`) are only treated as special in command
 //! position - when they would start a command. In argument position, they are regular
 //! words. The termination of compound commands is handled by `parse_compound_list_until`
@@ -492,6 +496,12 @@ impl<'a> Parser<'a> {
 
     /// Parse the input and return the AST.
     pub fn parse(mut self) -> Result<Script> {
+        self.parse_inner()
+    }
+
+    // Child parsers remain heap-owned throughout recursion; consuming a
+    // boxed Parser through `parse(self)` would move it back onto the stack.
+    fn parse_inner(&mut self) -> Result<Script> {
         let mut commands = Vec::new();
         let start_span = self.current_span;
         self.parse_script_into(&mut commands)?;
@@ -585,10 +595,13 @@ impl<'a> Parser<'a> {
             self.failed_command_line = start_line;
             self.failed_command_start = (start_offset, start_line);
             self.top_level_list = true;
-            if let Some(cmd) = self.parse_command_list()? {
+            let parsed = self.parse_command_list()?.map(|cmd| {
                 self.top_starts.push((start_offset, start_line));
-                commands.push((cmd, self.current_span.start.line));
-            } else if self.current_token.is_some() && self.current_span.start.offset == start_offset
+                commands.push((*cmd, self.current_span.start.line));
+            });
+            if parsed.is_none()
+                && self.current_token.is_some()
+                && self.current_span.start.offset == start_offset
             {
                 return Err(self.error("unexpected token"));
             }
@@ -652,8 +665,11 @@ impl<'a> Parser<'a> {
         Ok(())
     }
 
+    // THREAT[TM-DOS-044]: Command enums are large. Heap-owned grammar results
+    // avoid retaining their move temporaries on every recursive parser frame.
+    // Unbox only when inserting into the public AST's command vectors.
     /// Parse a command list (commands connected by && or ||)
-    fn parse_command_list(&mut self) -> Result<Option<Command>> {
+    fn parse_command_list(&mut self) -> Result<Option<Box<Command>>> {
         self.tick()?;
         let top_level = std::mem::take(&mut self.top_level_list);
         match self.current_token {
@@ -663,10 +679,10 @@ impl<'a> Parser<'a> {
             _ => {}
         }
         let start_span = self.current_span;
-        let first = match self.parse_pipeline()? {
-            Some(cmd) => cmd,
-            None => return Ok(None),
-        };
+        let first = self.parse_pipeline()?;
+        if first.is_none() {
+            return Ok(None);
+        }
 
         let mut rest = Vec::new();
 
@@ -708,16 +724,7 @@ impl<'a> Parser<'a> {
                         || matches!(self.current_token, Some(tokens::Token::Newline))
                     {
                         // Just & at end - return as background
-                        rest.push((
-                            ListOperator::Background,
-                            Command::Simple(SimpleCommand {
-                                name: Word::literal(""),
-                                args: vec![],
-                                redirects: vec![],
-                                assignments: vec![],
-                                span: self.current_span,
-                            }),
-                        ));
+                        rest.push(empty_background(self.current_span));
                         break;
                     }
                     ListOperator::Background
@@ -727,9 +734,8 @@ impl<'a> Parser<'a> {
 
             self.skip_newlines()?;
 
-            if let Some(cmd) = self.parse_pipeline()? {
-                rest.push((op, cmd));
-            } else {
+            let parsed = self.parse_pipeline()?.map(|cmd| rest.push((op, *cmd)));
+            if parsed.is_none() {
                 // `{ cmd & }`, `do cmd & done`: the `&` before a closing
                 // keyword still backgrounds `cmd`.
                 if matches!(op, ListOperator::Background) {
@@ -739,21 +745,13 @@ impl<'a> Parser<'a> {
             }
         }
 
-        if rest.is_empty() {
-            Ok(Some(first))
-        } else {
-            Ok(Some(Command::List(CommandList {
-                first: Box::new(first),
-                rest,
-                span: start_span.merge(self.current_span),
-            })))
-        }
+        finish_command_list(first, rest, start_span.merge(self.current_span))
     }
 
     /// Parse a pipeline (commands connected by |)
     ///
     /// Handles `!` pipeline negation: `! cmd | cmd2` negates the exit code.
-    fn parse_pipeline(&mut self) -> Result<Option<Command>> {
+    fn parse_pipeline(&mut self) -> Result<Option<Box<Command>>> {
         let start_span = self.current_span;
 
         // Check for pipeline negation: `! command`
@@ -765,17 +763,22 @@ impl<'a> Parser<'a> {
             _ => false,
         };
 
-        let first = match self.parse_command()? {
-            Some(cmd) => cmd,
-            None => {
-                if negated {
-                    return Err(self.error("expected command after !"));
-                }
-                return Ok(None);
+        let first = self.parse_command()?;
+        if first.is_none() {
+            if negated {
+                return Err(self.error("expected command after !"));
             }
-        };
-
-        let mut commands = vec![first];
+            return Ok(None);
+        }
+        if !negated
+            && !matches!(
+                self.current_token,
+                Some(tokens::Token::Pipe | tokens::Token::PipeBoth)
+            )
+        {
+            return Ok(first);
+        }
+        let mut commands: Vec<Command> = first.into_iter().map(|cmd| *cmd).collect();
 
         while matches!(
             self.current_token,
@@ -789,22 +792,16 @@ impl<'a> Parser<'a> {
             self.advance();
             self.skip_newlines()?;
 
-            if let Some(cmd) = self.parse_command()? {
-                commands.push(cmd);
-            } else {
+            if self
+                .parse_command()?
+                .map(|cmd| commands.push(*cmd))
+                .is_none()
+            {
                 return Err(self.error("expected command after |"));
             }
         }
 
-        if commands.len() == 1 && !negated {
-            Ok(Some(commands.remove(0)))
-        } else {
-            Ok(Some(Command::Pipeline(Pipeline {
-                negated,
-                commands,
-                span: start_span.merge(self.current_span),
-            })))
-        }
+        finish_pipeline(commands, negated, start_span.merge(self.current_span))
     }
 
     /// Parse redirections that follow a compound command (>, >>, 2>, etc.)
@@ -1063,10 +1060,10 @@ impl<'a> Parser<'a> {
     fn parse_compound_with_redirects(
         &mut self,
         parser: impl FnOnce(&mut Self) -> Result<CompoundCommand>,
-    ) -> Result<Option<Command>> {
+    ) -> Result<Option<Box<Command>>> {
         let compound = parser(self)?;
         let redirects = self.parse_trailing_redirects()?;
-        Ok(Some(Command::Compound(compound, redirects)))
+        Ok(Some(Box::new(Command::Compound(compound, redirects))))
     }
 
     /// The subscript of `name[sub]=...` as written in the source.
@@ -1114,7 +1111,7 @@ impl<'a> Parser<'a> {
     }
 
     /// Parse a single command (simple or compound)
-    fn parse_command(&mut self) -> Result<Option<Command>> {
+    fn parse_command(&mut self) -> Result<Option<Box<Command>>> {
         self.skip_newlines()?;
         self.check_error_token()?;
         self.expand_command_alias();
@@ -1131,7 +1128,7 @@ impl<'a> Parser<'a> {
                 "select" => return self.parse_compound_with_redirects(|s| s.parse_select()),
                 "time" => return self.parse_compound_with_redirects(|s| s.parse_time()),
                 "coproc" => return self.parse_compound_with_redirects(|s| s.parse_coproc()),
-                "function" => return self.parse_function_keyword().map(Some),
+                "function" => return self.parse_function_keyword().map(|cmd| Some(Box::new(cmd))),
                 _ => {
                     // Check for POSIX-style function: name() { body }
                     // Don't match if word contains '=' (that's an assignment like arr=(a b c))
@@ -1143,7 +1140,7 @@ impl<'a> Parser<'a> {
                         )
                         && matches!(self.peek_next(), Some(tokens::Token::LeftParen))
                     {
-                        return self.parse_function_posix().map(Some);
+                        return self.parse_function_posix().map(|cmd| Some(Box::new(cmd)));
                     }
                 }
             }
@@ -1170,10 +1167,8 @@ impl<'a> Parser<'a> {
         }
 
         // Default to simple command
-        match self.parse_simple_command()? {
-            Some(cmd) => Ok(Some(Command::Simple(cmd))),
-            None => Ok(None),
-        }
+        self.parse_simple_command()
+            .map(|cmd| cmd.map(|cmd| Box::new(Command::Simple(cmd))))
     }
 
     /// Parse an if statement
@@ -1791,7 +1786,7 @@ impl<'a> Parser<'a> {
                 && self.current_token.is_some()
             {
                 if let Some(cmd) = self.parse_command_list()? {
-                    commands.push(cmd);
+                    commands.push(*cmd);
                 }
                 self.skip_newlines()?;
             }
@@ -1889,7 +1884,7 @@ impl<'a> Parser<'a> {
             append,
             verbose,
             option_error,
-            command: command.map(Box::new),
+            command,
             span: start_span.merge(self.current_span),
         })))
     }
@@ -1940,7 +1935,7 @@ impl<'a> Parser<'a> {
 
             Ok(CompoundCommand::Coproc(ast::CoprocCommand {
                 name,
-                body: Box::new(body),
+                body,
                 span: start_span.merge(self.current_span),
             }))
         })();
@@ -1997,7 +1992,7 @@ impl<'a> Parser<'a> {
                 break;
             }
             if let Some(cmd) = self.parse_command_list()? {
-                commands.push(cmd);
+                commands.push(*cmd);
             }
         }
 
@@ -2028,7 +2023,7 @@ impl<'a> Parser<'a> {
                 break;
             }
             if let Some(cmd) = self.parse_command_list()? {
-                commands.push(cmd);
+                commands.push(*cmd);
             }
         }
 
@@ -2604,7 +2599,7 @@ impl<'a> Parser<'a> {
             return Err(self.error("expected '{' for function body"));
         }
         match self.parse_command()? {
-            Some(cmd @ Command::Compound(..)) => Ok(cmd),
+            Some(cmd) if matches!(*cmd, Command::Compound(..)) => Ok(*cmd),
             _ => Err(self.error("expected '{' for function body")),
         }
     }
@@ -2633,7 +2628,7 @@ impl<'a> Parser<'a> {
             }
 
             if let Some(cmd) = self.parse_command_list()? {
-                commands.push(cmd);
+                commands.push(*cmd);
             } else {
                 break;
             }
@@ -3388,33 +3383,12 @@ impl<'a> Parser<'a> {
             };
         }
 
-        // Handle assignment-only and redirect-only commands (`VAR=value`,
-        // `< file`, `> file`): bash runs them as null commands that still
-        // perform their assignments/redirections (#2448: `$(<file)`).
-        if words.is_empty() && (!assignments.is_empty() || !redirects.is_empty()) {
-            return Ok(Some(SimpleCommand {
-                name: Word::literal(""),
-                args: Vec::new(),
-                redirects,
-                assignments,
-                span: start_span.merge(self.current_span),
-            }));
-        }
-
-        if words.is_empty() {
-            return Ok(None);
-        }
-
-        let name = words.remove(0);
-        let args = words;
-
-        Ok(Some(SimpleCommand {
-            name,
-            args,
-            redirects,
+        finish_simple_command(
+            words,
             assignments,
-            span: start_span.merge(self.current_span),
-        }))
+            redirects,
+            start_span.merge(self.current_span),
+        )
     }
 
     /// `x<(true)`, `<(true)x`, `x=<(true)`: a process substitution and the
@@ -3519,35 +3493,7 @@ impl<'a> Parser<'a> {
                     if matches!(n.as_str(), "declare" | "typeset" | "local" | "export" | "readonly" | "let" | "eval"))
         });
         if w.ends_with('=') && decl_command {
-            let saved_raw = self.current_raw.clone();
-            self.advance();
-            if let Some(word) = self.try_parse_compound_array_arg(w.clone(), saved_raw.clone()) {
-                words.push(word);
-                return true;
-            }
-            // Not a compound assignment — treat as regular word
-            let word = if is_literal {
-                Word {
-                    parts: vec![WordPart::Literal(w)],
-                    quoted: true,
-                    has_unquoted_glob: false,
-                    part_quoted: Vec::new(),
-                    raw: saved_raw.clone(),
-                }
-            } else {
-                let mut word = self.parse_word(w);
-                if is_quoted {
-                    word.quoted = true;
-                }
-                if is_glob_quoted {
-                    word.has_unquoted_glob = true;
-                }
-                word
-            };
-            let mut word = word;
-            word.raw = saved_raw;
-            words.push(word);
-            return true;
+            return self.parse_declaration_word(words, w, is_literal, is_quoted, is_glob_quoted);
         }
 
         let word = if is_literal {
@@ -3573,6 +3519,46 @@ impl<'a> Parser<'a> {
         true
     }
 
+    #[inline(never)]
+    fn parse_declaration_word(
+        &mut self,
+        words: &mut Vec<Word>,
+        w: String,
+        is_literal: bool,
+        is_quoted: bool,
+        is_glob_quoted: bool,
+    ) -> bool {
+        let saved_raw = self.current_raw.clone();
+        self.advance();
+        if let Some(word) = self.try_parse_compound_array_arg(w.clone(), saved_raw.clone()) {
+            words.push(word);
+            return true;
+        }
+        // Not a compound assignment — treat as regular word
+        let word = if is_literal {
+            Word {
+                parts: vec![WordPart::Literal(w)],
+                quoted: true,
+                has_unquoted_glob: false,
+                part_quoted: Vec::new(),
+                raw: saved_raw.clone(),
+            }
+        } else {
+            let mut word = self.parse_word(w);
+            if is_quoted {
+                word.quoted = true;
+            }
+            if is_glob_quoted {
+                word.has_unquoted_glob = true;
+            }
+            word
+        };
+        let mut word = word;
+        word.raw = saved_raw;
+        words.push(word);
+        true
+    }
+
     /// One redirection of a simple command (outlined, see `parse_simple_word`).
     #[inline(never)]
     fn parse_simple_redirect(
@@ -4009,16 +3995,28 @@ impl<'a> Parser<'a> {
         }
     }
 
-    /// Parse a word string into a Word with proper parts (variables, literals)
     /// Parser for a `$(...)` body, on the heap: one lives per nesting level
     /// while the inner script parses, so keeping it out of `parse_word`'s
     /// frame leaves room for deep nesting (TM-DOS-044).
     // THREAT[TM-DOS-021]: Propagate parent parser limits to child parser
     // to prevent depth limit bypass via nested command substitution.
     #[inline(never)]
-    fn nested_parser<'b>(&self, src: &'b str) -> Box<Parser<'b>> {
-        let remaining_depth = self.max_depth.saturating_sub(self.current_depth);
-        let mut parser = Box::new(Parser::with_limits(src, remaining_depth, self.fuel));
+    fn nested_parser<'b>(&self, src: &'b str) -> Result<Box<Parser<'b>>> {
+        if self.current_depth >= self.max_depth {
+            return Err(Error::parse(format!(
+                "AST nesting too deep ({} levels, max {})",
+                self.current_depth + 1,
+                self.max_depth
+            )));
+        }
+        let mut parser = Box::new(Parser::with_limits_and_timeout(
+            src,
+            self.max_depth,
+            self.fuel,
+            self.timeout,
+        ));
+        parser.current_depth = self.current_depth + 1;
+        parser.started_at = self.started_at;
         parser.execution_budget = self.execution_budget.clone();
         parser.set_options(self.options.clone());
         // `$( )` spans count from the outer word's line, so `$LINENO` and
@@ -4029,103 +4027,793 @@ impl<'a> Parser<'a> {
             parser.current_span.start.line += shift;
             parser.current_span.end.line += shift;
         }
-        parser
+        Ok(parser)
     }
 
-    fn parse_word(&self, s: String) -> Word {
-        let mut parts = Vec::new();
-        let mut part_quoted = Vec::new();
-        let mut chars = s.chars().peekable();
-        let mut current = String::new();
-        let mut in_quoted_segment = false;
-        // Parts count when the current quoted segment opened, to spot `""`.
-        let mut segment_start = 0usize;
-        let mut has_empty_quoted = false;
-        let mut saw_quote_marker = false;
+    // THREAT[TM-DOS-044]: This nonrecursive branch has many WordPart
+    // temporaries. Keep its frame out of every nested substitution parse.
+    #[inline(never)]
+    fn parse_braced_parameter(
+        &self,
+        chars: &mut std::iter::Peekable<std::str::Chars<'_>>,
+        parts: &mut Vec<WordPart>,
+        part_quoted: &mut Vec<bool>,
+        in_quoted_segment: bool,
+    ) {
         macro_rules! push_part {
             ($part:expr) => {{
                 parts.push($part);
                 part_quoted.push(in_quoted_segment);
             }};
         }
+        // ${VAR} format with possible parameter expansion
+        chars.next(); // consume '{'
 
-        while let Some(ch) = chars.next() {
-            if ch == '\x00' {
-                // NUL sentinel from lexer: next char is a literal (escaped in source).
-                if let Some(literal_ch) = chars.next() {
-                    if literal_ch == '~'
-                        && !in_quoted_segment
-                        && (current.is_empty() || current.ends_with([':', '=']))
-                    {
-                        // `\~` where a tilde prefix could start: a quoted
-                        // part, so it never tilde-expands.
-                        if !current.is_empty() {
-                            push_part!(WordPart::Literal(std::mem::take(&mut current)));
-                        }
-                        parts.push(WordPart::Literal("~".to_string()));
-                        part_quoted.push(true);
+        if let Some(inner) = bad_brace_parameter(chars) {
+            // Bash accepts the word and fails when expanding it.
+            for _ in 0..=inner.chars().count() {
+                chars.next();
+            }
+            push_part!(WordPart::BadSubstitution(bad_substitution_text(&inner)));
+        } else if chars.peek() == Some(&'#') && !hash_param_with_op(chars) {
+            // ${#var} or ${#arr[@]} - length expansion
+            chars.next(); // consume '#'
+            let mut var_name = String::new();
+            while let Some(&c) = chars.peek() {
+                if c == '}' || c == '[' {
+                    break;
+                }
+                var_name.push(chars.next().unwrap());
+            }
+            // Check for array length ${#arr[@]} or ${#arr[*]}
+            if chars.peek() == Some(&'[') {
+                chars.next(); // consume '['
+                let mut index = String::new();
+                while let Some(&c) = chars.peek() {
+                    if c == ']' {
+                        chars.next();
+                        break;
+                    }
+                    index.push(chars.next().unwrap());
+                }
+                // Consume closing }
+                if chars.peek() == Some(&'}') {
+                    chars.next();
+                }
+                if index == "@" || index == "*" {
+                    push_part!(WordPart::ArrayLength(var_name));
+                } else {
+                    // ${#arr[n]} - length of element (same as ${#arr[n]})
+                    push_part!(WordPart::Length(format!("{}[{}]", var_name, index)));
+                }
+            } else {
+                // Consume closing }
+                if chars.peek() == Some(&'}') {
+                    chars.next();
+                }
+                if var_name.is_empty() {
+                    // `${#}` is `$#`, not a length.
+                    push_part!(WordPart::Variable("#".to_string()));
+                } else {
+                    push_part!(WordPart::Length(var_name));
+                }
+            }
+        } else if chars.peek() == Some(&'!') {
+            // Check for ${!arr[@]} or ${!arr[*]} - array indices
+            // or ${!var} - indirect expansion
+            chars.next(); // consume '!'
+            let mut var_name = String::new();
+            while let Some(&c) = chars.peek() {
+                if c == '}'
+                    || c == '['
+                    || c == '*'
+                    || c == '@'
+                    || c == ':'
+                    || c == '-'
+                    || c == '='
+                    || c == '+'
+                    || c == '?'
+                {
+                    break;
+                }
+                // `${!x#y}`, `${!x/a/b}`: an operator ends the name
+                // (`${!#}` is still the indirect `$#`).
+                if !var_name.is_empty() && matches!(c, '#' | '%' | '/' | '^' | ',' | '~') {
+                    break;
+                }
+                var_name.push(chars.next().unwrap());
+            }
+            // Check for array indices ${!arr[@]} or ${!arr[*]}
+            if chars.peek() == Some(&'[') {
+                chars.next(); // consume '['
+                let mut index = String::new();
+                while let Some(&c) = chars.peek() {
+                    if c == ']' {
+                        chars.next();
+                        break;
+                    }
+                    index.push(chars.next().unwrap());
+                }
+                if chars.peek() == Some(&'}') {
+                    chars.next();
+                    if index == "@" || index == "*" {
+                        push_part!(WordPart::ArrayIndices {
+                            name: var_name,
+                            star: index == "*",
+                        });
                     } else {
-                        current.push(literal_ch);
+                        // `${!a[1]}`: the element names the variable.
+                        push_part!(WordPart::IndirectSuffix {
+                            name: format!("{var_name}[{index}]"),
+                            suffix: String::new(),
+                        });
                     }
+                } else {
+                    // `${!ref[@]:2}`, `${!a[0]#x}`: the elements'
+                    // value names the variable the operator applies to.
+                    let suffix = self.read_brace_operand(chars);
+                    push_part!(WordPart::IndirectSuffix {
+                        name: format!("{var_name}[{index}]"),
+                        suffix,
+                    });
                 }
-            } else if ch == '\u{1e}' || ch == '\u{1f}' {
-                // A quote boundary ends the literal run, so `part_quoted`
-                // records which literal text was quoted (brace expansion
-                // only sees unquoted literals).
-                let quoted = ch == '\u{1e}';
-                saw_quote_marker = true;
-                if quoted != in_quoted_segment && !current.is_empty() {
-                    push_part!(WordPart::Literal(std::mem::take(&mut current)));
-                } else if !quoted && in_quoted_segment && parts.len() == segment_start {
-                    // An empty quoted segment (`$x""`): keep it as an empty
-                    // quoted part so field splitting can still make a field.
-                    push_part!(WordPart::Literal(String::new()));
-                    has_empty_quoted = true;
+            } else if chars.peek() == Some(&'}') {
+                // ${!var} - indirect expansion (no operator)
+                chars.next(); // consume '}'
+                push_part!(WordPart::IndirectExpansion {
+                    name: var_name,
+                    operator: None,
+                    operand: String::new(),
+                    colon_variant: false,
+                });
+            } else if chars.peek() == Some(&':') {
+                // ${!var:op} - indirect expansion with colon operator
+                let mut lookahead = chars.clone();
+                lookahead.next(); // skip ':'
+                if matches!(
+                    lookahead.peek(),
+                    Some(&'-') | Some(&'=') | Some(&'+') | Some(&'?')
+                ) {
+                    chars.next(); // consume ':'
+                    let op_char = chars.next().unwrap();
+                    let operand = self.read_brace_operand(chars);
+                    let operator = match op_char {
+                        '-' => ParameterOp::UseDefault,
+                        '=' => ParameterOp::AssignDefault,
+                        '+' => ParameterOp::UseReplacement,
+                        '?' => ParameterOp::Error,
+                        _ => unreachable!(),
+                    };
+                    push_part!(WordPart::IndirectExpansion {
+                        name: var_name,
+                        operator: Some(operator),
+                        operand,
+                        colon_variant: true,
+                    });
+                } else {
+                    // `${!x:1:2}`: substring of the named variable.
+                    let suffix = self.read_brace_operand(chars);
+                    push_part!(WordPart::IndirectSuffix {
+                        name: var_name,
+                        suffix,
+                    });
                 }
-                if quoted && !in_quoted_segment {
-                    segment_start = parts.len();
+            } else if matches!(
+                chars.peek(),
+                Some(&'-') | Some(&'=') | Some(&'+') | Some(&'?')
+            ) {
+                // ${!var-op} - indirect expansion with non-colon operator
+                let op_char = chars.next().unwrap();
+                let operand = self.read_brace_operand(chars);
+                let operator = match op_char {
+                    '-' => ParameterOp::UseDefault,
+                    '=' => ParameterOp::AssignDefault,
+                    '+' => ParameterOp::UseReplacement,
+                    '?' => ParameterOp::Error,
+                    _ => unreachable!(),
+                };
+                push_part!(WordPart::IndirectExpansion {
+                    name: var_name,
+                    operator: Some(operator),
+                    operand,
+                    colon_variant: false,
+                });
+            } else {
+                // ${!prefix*} or ${!prefix@} - prefix matching
+                let suffix = self.read_brace_operand(chars);
+                // `${!ref@a}`: transform the variable `ref` names.
+                if push_indirect_transformation(
+                    parts,
+                    part_quoted,
+                    in_quoted_segment,
+                    &var_name,
+                    &suffix,
+                ) {
+                } else if suffix.ends_with('*') || suffix.ends_with('@') {
+                    let full_prefix = format!("{}{}", var_name, &suffix[..suffix.len() - 1]);
+                    push_part!(WordPart::PrefixMatch {
+                        prefix: full_prefix,
+                        star: suffix.ends_with('*'),
+                    });
+                } else {
+                    push_part!(WordPart::IndirectSuffix {
+                        name: var_name,
+                        suffix,
+                    });
                 }
-                in_quoted_segment = quoted;
-            } else if ch == '$' {
-                // Flush current literal
-                if !current.is_empty() {
-                    push_part!(WordPart::Literal(std::mem::take(&mut current)));
+            }
+        } else {
+            // Read variable name
+            let mut var_name = String::new();
+            while let Some(&c) = chars.peek() {
+                if c.is_ascii_alphanumeric() || c == '_' {
+                    var_name.push(chars.next().unwrap());
+                } else {
+                    break;
                 }
+            }
 
-                // Check for $'...' - ANSI-C quoting
-                if chars.peek() == Some(&'\'') {
-                    chars.next(); // consume opening '
-                    let mut ansi = String::new();
-                    while let Some(c) = chars.next() {
-                        if c == '\'' {
-                            break;
-                        }
-                        if c == '\\' {
-                            if let Some(esc) = chars.next() {
-                                match esc {
-                                    'n' => ansi.push('\n'),
-                                    't' => ansi.push('\t'),
-                                    'r' => ansi.push('\r'),
-                                    'a' => ansi.push('\x07'),
-                                    'b' => ansi.push('\x08'),
-                                    'e' | 'E' => ansi.push('\x1B'),
-                                    '\\' => ansi.push('\\'),
-                                    '\'' => ansi.push('\''),
-                                    _ => {
-                                        ansi.push('\\');
-                                        ansi.push(esc);
-                                    }
-                                }
+            // Handle special parameters: ${@...}, ${*...}, ${-...},
+            // ${?...}, ${$...}
+            if var_name.is_empty()
+                && let Some(&c) = chars.peek()
+                && matches!(c, '@' | '*' | '-' | '?' | '$' | '#')
+            {
+                var_name.push(chars.next().unwrap());
+            }
+
+            // Check for array access ${arr[index]} or ${arr[@]:offset:length}
+            // `${arr[i]OP...}` with a pattern/case/transform OP reuses the
+            // scalar operator parsing below on the name `arr[i]`.
+            let mut subscript_op = false;
+            let had_subscript = chars.peek() == Some(&'[');
+            if chars.peek() == Some(&'[') {
+                chars.next(); // consume '['
+                let mut index = String::new();
+                // Track nesting so nested ${...} containing
+                // brackets (e.g. ${#arr[@]}) don't prematurely
+                // close the subscript.
+                let mut bracket_depth: i32 = 0;
+                let mut brace_depth: i32 = 0;
+                while let Some(&c) = chars.peek() {
+                    if c == ']' && bracket_depth == 0 && brace_depth == 0 {
+                        chars.next();
+                        break;
+                    }
+                    match c {
+                        '[' => bracket_depth += 1,
+                        ']' => bracket_depth -= 1,
+                        '$' => {
+                            index.push(chars.next().unwrap());
+                            if chars.peek() == Some(&'{') {
+                                brace_depth += 1;
+                                index.push(chars.next().unwrap());
+                                continue;
                             }
+                            continue;
+                        }
+                        '{' => brace_depth += 1,
+                        '}' if brace_depth > 0 => brace_depth -= 1,
+                        '}' => {}
+                        _ => {}
+                    }
+                    index.push(chars.next().unwrap());
+                }
+                // Strip surrounding quotes from index (e.g. "foo" -> foo)
+                if index.len() >= 2
+                    && ((index.starts_with('"') && index.ends_with('"'))
+                        || (index.starts_with('\'') && index.ends_with('\'')))
+                {
+                    index = index[1..index.len() - 1].to_string();
+                }
+                // After ], check for operators on array subscripts
+                if let Some(&next_c) = chars.peek() {
+                    if next_c == ':' {
+                        // Peek ahead to distinguish param ops (:- := :+ :?) from slice (:N)
+                        let mut lookahead = chars.clone();
+                        lookahead.next(); // skip ':'
+                        let is_param_op = matches!(
+                            lookahead.peek(),
+                            Some(&'-') | Some(&'=') | Some(&'+') | Some(&'?')
+                        );
+                        if is_param_op {
+                            chars.next(); // consume ':'
+                            let arr_name = format!("{}[{}]", var_name, index);
+                            let op_char = chars.next().unwrap();
+                            let operand = self.read_brace_operand(chars);
+                            let operator = match op_char {
+                                '-' => ParameterOp::UseDefault,
+                                '=' => ParameterOp::AssignDefault,
+                                '+' => ParameterOp::UseReplacement,
+                                '?' => ParameterOp::Error,
+                                _ => unreachable!(),
+                            };
+                            push_part!(WordPart::ParameterExpansion {
+                                name: arr_name,
+                                operator,
+                                operand,
+                                colon_variant: true,
+                            });
                         } else {
-                            ansi.push(c);
+                            // Array slice ${arr[@]:offset:length}
+                            chars.next(); // consume ':'
+                            let offset = read_slice_field(chars, true);
+                            let length = if chars.peek() == Some(&':') {
+                                chars.next();
+                                Some(read_slice_field(chars, false))
+                            } else {
+                                None
+                            };
+                            if chars.peek() == Some(&'}') {
+                                chars.next();
+                            }
+                            // `${a[@]:}`: an empty offset is a
+                            // bad substitution (bash).
+                            if offset.is_empty() && length.is_none() {
+                                push_part!(WordPart::BadSubstitution(format!(
+                                    "${{{}[{index}]:}}",
+                                    std::mem::take(&mut var_name)
+                                )));
+                            } else {
+                                // `${a[@]:o:l}` slices the elements,
+                                // `${a[1]:o:l}` the element's text.
+                                push_part!(WordPart::Substring {
+                                    name: format!("{}[{}]", std::mem::take(&mut var_name), index),
+                                    offset,
+                                    length,
+                                });
+                            }
+                        }
+                    } else if matches!(next_c, '-' | '+' | '=' | '?') {
+                        // Non-colon operators on array: ${arr[@]-default}
+                        let arr_name = format!("{}[{}]", var_name, index);
+                        let op_char = chars.next().unwrap();
+                        let operand = self.read_brace_operand(chars);
+                        let operator = match op_char {
+                            '-' => ParameterOp::UseDefault,
+                            '=' => ParameterOp::AssignDefault,
+                            '+' => ParameterOp::UseReplacement,
+                            '?' => ParameterOp::Error,
+                            _ => unreachable!(),
+                        };
+                        push_part!(WordPart::ParameterExpansion {
+                            name: arr_name,
+                            operator,
+                            operand,
+                            colon_variant: false,
+                        });
+                    } else if matches!(next_c, '#' | '%' | '/' | '^' | ',' | '~' | '@') {
+                        var_name = format!("{}[{}]", var_name, index);
+                        subscript_op = true;
+                    } else {
+                        // Plain array access ${arr[index]}
+                        if chars.peek() == Some(&'}') {
+                            chars.next();
                         }
+                        push_part!(WordPart::ArrayAccess {
+                            name: std::mem::take(&mut var_name),
+                            index,
+                        });
                     }
-                    push_part!(WordPart::Literal(ansi));
-                } else if chars.peek() == Some(&'(') {
-                    // Check for $( - command substitution or arithmetic
-                    chars.next(); // consume first '('
-
+                } else {
+                    push_part!(WordPart::ArrayAccess {
+                        name: std::mem::take(&mut var_name),
+                        index,
+                    });
+                }
+            }
+            if (!had_subscript || subscript_op)
+                && let Some(&c) = chars.peek()
+            {
+                // Check for operator
+                match c {
+                    ':' => {
+                        chars.next(); // consume ':'
+                        match chars.peek() {
+                            Some(&'-') | Some(&'=') | Some(&'+') | Some(&'?') => {
+                                let op_char = chars.next().unwrap();
+                                let operand = self.read_brace_operand(chars);
+                                let operator = match op_char {
+                                    '-' => ParameterOp::UseDefault,
+                                    '=' => ParameterOp::AssignDefault,
+                                    '+' => ParameterOp::UseReplacement,
+                                    '?' => ParameterOp::Error,
+                                    _ => unreachable!(),
+                                };
+                                push_part!(WordPart::ParameterExpansion {
+                                    name: var_name,
+                                    operator,
+                                    operand,
+                                    colon_variant: true,
+                                });
+                            }
+                            _ => {
+                                // Substring extraction ${var:offset} or ${var:offset:length}
+                                let offset = read_slice_field(chars, true);
+                                let length = if chars.peek() == Some(&':') {
+                                    chars.next(); // consume ':'
+                                    Some(read_slice_field(chars, false))
+                                } else {
+                                    None
+                                };
+                                if chars.peek() == Some(&'}') {
+                                    chars.next();
+                                }
+                                if offset.is_empty() && length.is_none() {
+                                    push_part!(WordPart::BadSubstitution(format!(
+                                        "${{{var_name}:}}"
+                                    )));
+                                } else {
+                                    push_part!(WordPart::Substring {
+                                        name: var_name,
+                                        offset,
+                                        length,
+                                    });
+                                }
+                            }
+                        }
+                    }
+                    // Non-colon test operators: ${var-default}, ${var+alt}, ${var=assign}, ${var?err}
+                    '-' | '=' | '+' | '?' => {
+                        let op_char = chars.next().unwrap();
+                        let operand = self.read_brace_operand(chars);
+                        let operator = match op_char {
+                            '-' => ParameterOp::UseDefault,
+                            '=' => ParameterOp::AssignDefault,
+                            '+' => ParameterOp::UseReplacement,
+                            '?' => ParameterOp::Error,
+                            _ => unreachable!(),
+                        };
+                        push_part!(WordPart::ParameterExpansion {
+                            name: var_name,
+                            operator,
+                            operand,
+                            colon_variant: false,
+                        });
+                    }
+                    '#' => {
+                        chars.next();
+                        if chars.peek() == Some(&'#') {
+                            chars.next();
+                            let op = self.read_brace_operand(chars);
+                            push_part!(WordPart::ParameterExpansion {
+                                name: var_name,
+                                operator: ParameterOp::RemovePrefixLong,
+                                operand: op,
+                                colon_variant: false,
+                            });
+                        } else {
+                            let op = self.read_brace_operand(chars);
+                            push_part!(WordPart::ParameterExpansion {
+                                name: var_name,
+                                operator: ParameterOp::RemovePrefixShort,
+                                operand: op,
+                                colon_variant: false,
+                            });
+                        }
+                    }
+                    '%' => {
+                        chars.next();
+                        if chars.peek() == Some(&'%') {
+                            chars.next();
+                            let op = self.read_brace_operand(chars);
+                            push_part!(WordPart::ParameterExpansion {
+                                name: var_name,
+                                operator: ParameterOp::RemoveSuffixLong,
+                                operand: op,
+                                colon_variant: false,
+                            });
+                        } else {
+                            let op = self.read_brace_operand(chars);
+                            push_part!(WordPart::ParameterExpansion {
+                                name: var_name,
+                                operator: ParameterOp::RemoveSuffixShort,
+                                operand: op,
+                                colon_variant: false,
+                            });
+                        }
+                    }
+                    '/' => {
+                        chars.next();
+                        let replace_all = if chars.peek() == Some(&'/') {
+                            chars.next();
+                            true
+                        } else {
+                            false
+                        };
+                        let mut pattern = String::new();
+                        // `${x///}`, `${x////c}`: the pattern
+                        // cannot be empty, so a `/` right after
+                        // `//` is the pattern itself.
+                        if replace_all && chars.peek() == Some(&'/') {
+                            chars.next();
+                            pattern.push('/');
+                        }
+                        let mut in_dq = false;
+                        while let Some(&ch) = chars.peek() {
+                            if ch == '\x00' {
+                                pattern.push(chars.next().unwrap());
+                                if let Some(n) = chars.next() {
+                                    pattern.push(n);
+                                }
+                                continue;
+                            }
+                            if ch == '"' {
+                                in_dq = !in_dq;
+                            } else if !in_dq && (ch == '/' || ch == '}') {
+                                break;
+                            }
+                            if ch == '\\' {
+                                chars.next();
+                                if let Some(&next) = chars.peek()
+                                    && next == '/'
+                                {
+                                    pattern.push(chars.next().unwrap());
+                                    continue;
+                                }
+                                pattern.push('\\');
+                                if let Some(n) = chars.next() {
+                                    pattern.push(n);
+                                }
+                                continue;
+                            }
+                            pattern.push(chars.next().unwrap());
+                        }
+                        let replacement = if chars.peek() == Some(&'/') {
+                            chars.next();
+                            let mut repl = String::new();
+                            let mut in_dq = false;
+                            while let Some(&ch) = chars.peek() {
+                                if ch == '\x00' {
+                                    repl.push(chars.next().unwrap());
+                                    if let Some(n) = chars.next() {
+                                        repl.push(n);
+                                    }
+                                    continue;
+                                }
+                                if ch == '"' {
+                                    in_dq = !in_dq;
+                                } else if ch == '\'' && !in_dq {
+                                    // `"${y/b/'}'}"`: a single-quoted span
+                                    // hides `}`; the expansion quote-removes it.
+                                    repl.push(chars.next().unwrap());
+                                    for q in chars.by_ref() {
+                                        repl.push(q);
+                                        if q == '\'' {
+                                            break;
+                                        }
+                                    }
+                                    continue;
+                                } else if ch == '\\' {
+                                    repl.push(chars.next().unwrap());
+                                    if let Some(n) = chars.next() {
+                                        // `\/` is a literal slash, as in the
+                                        // pattern (bash removes the backslash).
+                                        if n == '/' {
+                                            repl.pop();
+                                        }
+                                        repl.push(n);
+                                    }
+                                    continue;
+                                } else if !in_dq && ch == '}' {
+                                    break;
+                                }
+                                repl.push(chars.next().unwrap());
+                            }
+                            repl
+                        } else {
+                            String::new()
+                        };
+                        if chars.peek() == Some(&'}') {
+                            chars.next();
+                        }
+                        let op = if replace_all {
+                            ParameterOp::ReplaceAll {
+                                pattern,
+                                replacement,
+                            }
+                        } else {
+                            ParameterOp::ReplaceFirst {
+                                pattern,
+                                replacement,
+                            }
+                        };
+                        push_part!(WordPart::ParameterExpansion {
+                            name: var_name,
+                            operator: op,
+                            operand: String::new(),
+                            colon_variant: false,
+                        });
+                    }
+                    '^' => {
+                        chars.next();
+                        let op = if chars.peek() == Some(&'^') {
+                            chars.next();
+                            ParameterOp::UpperAll
+                        } else {
+                            ParameterOp::UpperFirst
+                        };
+                        // `${v^^pat}`: only characters matching `pat`.
+                        let operand = self.read_brace_operand(chars);
+                        push_part!(WordPart::ParameterExpansion {
+                            name: var_name,
+                            operator: op,
+                            operand,
+                            colon_variant: false,
+                        });
+                    }
+                    '~' => {
+                        // `${v~}` / `${v~~}`: toggle case (undocumented
+                        // in the bash manual, supported by bash 4+).
+                        chars.next();
+                        let op = if chars.peek() == Some(&'~') {
+                            chars.next();
+                            ParameterOp::ToggleAll
+                        } else {
+                            ParameterOp::ToggleFirst
+                        };
+                        let operand = self.read_brace_operand(chars);
+                        push_part!(WordPart::ParameterExpansion {
+                            name: var_name,
+                            operator: op,
+                            operand,
+                            colon_variant: false,
+                        });
+                    }
+                    ',' => {
+                        chars.next();
+                        let op = if chars.peek() == Some(&',') {
+                            chars.next();
+                            ParameterOp::LowerAll
+                        } else {
+                            ParameterOp::LowerFirst
+                        };
+                        // `${v^^pat}`: only characters matching `pat`.
+                        let operand = self.read_brace_operand(chars);
+                        push_part!(WordPart::ParameterExpansion {
+                            name: var_name,
+                            operator: op,
+                            operand,
+                            colon_variant: false,
+                        });
+                    }
+                    '@' => {
+                        chars.next();
+                        if let Some(&op) = chars.peek() {
+                            chars.next();
+                            if chars.peek() == Some(&'}') {
+                                chars.next();
+                            }
+                            push_part!(WordPart::Transformation {
+                                name: var_name,
+                                operator: op,
+                            });
+                        } else {
+                            if chars.peek() == Some(&'}') {
+                                chars.next();
+                            }
+                            push_part!(WordPart::Variable(var_name));
+                        }
+                    }
+                    '}' => {
+                        chars.next();
+                        if !var_name.is_empty() {
+                            push_part!(WordPart::Variable(var_name));
+                        }
+                    }
+                    _ => {
+                        while let Some(&ch) = chars.peek() {
+                            if ch == '}' {
+                                chars.next();
+                                break;
+                            }
+                            chars.next();
+                        }
+                        if !var_name.is_empty() {
+                            push_part!(WordPart::Variable(var_name));
+                        }
+                    }
+                }
+            } else if !had_subscript && !var_name.is_empty() {
+                push_part!(WordPart::Variable(var_name));
+            }
+        }
+    }
+
+    fn parse_word(&self, s: String) -> Word {
+        let mut parts = Vec::new();
+        let mut part_quoted = Vec::new();
+        let mut chars = s.chars().peekable();
+        let mut current = String::new();
+        let mut in_quoted_segment = false;
+        // Parts count when the current quoted segment opened, to spot `""`.
+        let mut segment_start = 0usize;
+        let mut has_empty_quoted = false;
+        let mut saw_quote_marker = false;
+        macro_rules! push_part {
+            ($part:expr) => {{
+                parts.push($part);
+                part_quoted.push(in_quoted_segment);
+            }};
+        }
+
+        while let Some(ch) = chars.next() {
+            if ch == '\x00' {
+                // NUL sentinel from lexer: next char is a literal (escaped in source).
+                if let Some(literal_ch) = chars.next() {
+                    if literal_ch == '~'
+                        && !in_quoted_segment
+                        && (current.is_empty() || current.ends_with([':', '=']))
+                    {
+                        // `\~` where a tilde prefix could start: a quoted
+                        // part, so it never tilde-expands.
+                        if !current.is_empty() {
+                            push_part!(WordPart::Literal(std::mem::take(&mut current)));
+                        }
+                        parts.push(WordPart::Literal("~".to_string()));
+                        part_quoted.push(true);
+                    } else {
+                        current.push(literal_ch);
+                    }
+                }
+            } else if ch == '\u{1e}' || ch == '\u{1f}' {
+                // A quote boundary ends the literal run, so `part_quoted`
+                // records which literal text was quoted (brace expansion
+                // only sees unquoted literals).
+                let quoted = ch == '\u{1e}';
+                saw_quote_marker = true;
+                if quoted != in_quoted_segment && !current.is_empty() {
+                    push_part!(WordPart::Literal(std::mem::take(&mut current)));
+                } else if !quoted && in_quoted_segment && parts.len() == segment_start {
+                    // An empty quoted segment (`$x""`): keep it as an empty
+                    // quoted part so field splitting can still make a field.
+                    push_part!(WordPart::Literal(String::new()));
+                    has_empty_quoted = true;
+                }
+                if quoted && !in_quoted_segment {
+                    segment_start = parts.len();
+                }
+                in_quoted_segment = quoted;
+            } else if ch == '$' {
+                // Flush current literal
+                if !current.is_empty() {
+                    push_part!(WordPart::Literal(std::mem::take(&mut current)));
+                }
+
+                // Check for $'...' - ANSI-C quoting
+                if chars.peek() == Some(&'\'') {
+                    chars.next(); // consume opening '
+                    let mut ansi = String::new();
+                    while let Some(c) = chars.next() {
+                        if c == '\'' {
+                            break;
+                        }
+                        if c == '\\' {
+                            if let Some(esc) = chars.next() {
+                                match esc {
+                                    'n' => ansi.push('\n'),
+                                    't' => ansi.push('\t'),
+                                    'r' => ansi.push('\r'),
+                                    'a' => ansi.push('\x07'),
+                                    'b' => ansi.push('\x08'),
+                                    'e' | 'E' => ansi.push('\x1B'),
+                                    '\\' => ansi.push('\\'),
+                                    '\'' => ansi.push('\''),
+                                    _ => {
+                                        ansi.push('\\');
+                                        ansi.push(esc);
+                                    }
+                                }
+                            }
+                        } else {
+                            ansi.push(c);
+                        }
+                    }
+                    push_part!(WordPart::Literal(ansi));
+                } else if chars.peek() == Some(&'(') {
+                    // Check for $( - command substitution or arithmetic
+                    chars.next(); // consume first '('
+
                     // Check for $(( - arithmetic expansion
                     if chars.peek() == Some(&'(') {
                         chars.next(); // consume second '('
@@ -4160,7 +4848,6 @@ impl<'a> Parser<'a> {
                             }
                             cmd_str.push(c);
                         }
-                        let inner_parser = self.nested_parser(&cmd_str);
                         // A failed inner parse must never make the part vanish:
                         // dropping it splices the literals on either side into a
                         // word that appears nowhere in the source (`a$(|)b` ->
@@ -4168,7 +4855,10 @@ impl<'a> Parser<'a> {
                         // permission gate as a real command name. Keep the part
                         // so the word stays non-literal, and remember the error so
                         // `parse_script` can reject the script like bash does.
-                        match inner_parser.parse() {
+                        match self
+                            .nested_parser(&cmd_str)
+                            .and_then(|mut parser| parser.parse_inner())
+                        {
                             Ok(script) => {
                                 push_part!(WordPart::CommandSubstitution(script.commands));
                             }
@@ -4181,686 +4871,12 @@ impl<'a> Parser<'a> {
                         }
                     }
                 } else if chars.peek() == Some(&'{') {
-                    // ${VAR} format with possible parameter expansion
-                    chars.next(); // consume '{'
-
-                    if let Some(inner) = bad_brace_parameter(&chars) {
-                        // Bash accepts the word and fails when expanding it.
-                        for _ in 0..=inner.chars().count() {
-                            chars.next();
-                        }
-                        push_part!(WordPart::BadSubstitution(bad_substitution_text(&inner)));
-                    } else if chars.peek() == Some(&'#') && !hash_param_with_op(&chars) {
-                        // ${#var} or ${#arr[@]} - length expansion
-                        chars.next(); // consume '#'
-                        let mut var_name = String::new();
-                        while let Some(&c) = chars.peek() {
-                            if c == '}' || c == '[' {
-                                break;
-                            }
-                            var_name.push(chars.next().unwrap());
-                        }
-                        // Check for array length ${#arr[@]} or ${#arr[*]}
-                        if chars.peek() == Some(&'[') {
-                            chars.next(); // consume '['
-                            let mut index = String::new();
-                            while let Some(&c) = chars.peek() {
-                                if c == ']' {
-                                    chars.next();
-                                    break;
-                                }
-                                index.push(chars.next().unwrap());
-                            }
-                            // Consume closing }
-                            if chars.peek() == Some(&'}') {
-                                chars.next();
-                            }
-                            if index == "@" || index == "*" {
-                                push_part!(WordPart::ArrayLength(var_name));
-                            } else {
-                                // ${#arr[n]} - length of element (same as ${#arr[n]})
-                                push_part!(WordPart::Length(format!("{}[{}]", var_name, index)));
-                            }
-                        } else {
-                            // Consume closing }
-                            if chars.peek() == Some(&'}') {
-                                chars.next();
-                            }
-                            if var_name.is_empty() {
-                                // `${#}` is `$#`, not a length.
-                                push_part!(WordPart::Variable("#".to_string()));
-                            } else {
-                                push_part!(WordPart::Length(var_name));
-                            }
-                        }
-                    } else if chars.peek() == Some(&'!') {
-                        // Check for ${!arr[@]} or ${!arr[*]} - array indices
-                        // or ${!var} - indirect expansion
-                        chars.next(); // consume '!'
-                        let mut var_name = String::new();
-                        while let Some(&c) = chars.peek() {
-                            if c == '}'
-                                || c == '['
-                                || c == '*'
-                                || c == '@'
-                                || c == ':'
-                                || c == '-'
-                                || c == '='
-                                || c == '+'
-                                || c == '?'
-                            {
-                                break;
-                            }
-                            // `${!x#y}`, `${!x/a/b}`: an operator ends the name
-                            // (`${!#}` is still the indirect `$#`).
-                            if !var_name.is_empty()
-                                && matches!(c, '#' | '%' | '/' | '^' | ',' | '~')
-                            {
-                                break;
-                            }
-                            var_name.push(chars.next().unwrap());
-                        }
-                        // Check for array indices ${!arr[@]} or ${!arr[*]}
-                        if chars.peek() == Some(&'[') {
-                            chars.next(); // consume '['
-                            let mut index = String::new();
-                            while let Some(&c) = chars.peek() {
-                                if c == ']' {
-                                    chars.next();
-                                    break;
-                                }
-                                index.push(chars.next().unwrap());
-                            }
-                            if chars.peek() == Some(&'}') {
-                                chars.next();
-                                if index == "@" || index == "*" {
-                                    push_part!(WordPart::ArrayIndices {
-                                        name: var_name,
-                                        star: index == "*",
-                                    });
-                                } else {
-                                    // `${!a[1]}`: the element names the variable.
-                                    push_part!(WordPart::IndirectSuffix {
-                                        name: format!("{var_name}[{index}]"),
-                                        suffix: String::new(),
-                                    });
-                                }
-                            } else {
-                                // `${!ref[@]:2}`, `${!a[0]#x}`: the elements'
-                                // value names the variable the operator applies to.
-                                let suffix = self.read_brace_operand(&mut chars);
-                                push_part!(WordPart::IndirectSuffix {
-                                    name: format!("{var_name}[{index}]"),
-                                    suffix,
-                                });
-                            }
-                        } else if chars.peek() == Some(&'}') {
-                            // ${!var} - indirect expansion (no operator)
-                            chars.next(); // consume '}'
-                            push_part!(WordPart::IndirectExpansion {
-                                name: var_name,
-                                operator: None,
-                                operand: String::new(),
-                                colon_variant: false,
-                            });
-                        } else if chars.peek() == Some(&':') {
-                            // ${!var:op} - indirect expansion with colon operator
-                            let mut lookahead = chars.clone();
-                            lookahead.next(); // skip ':'
-                            if matches!(
-                                lookahead.peek(),
-                                Some(&'-') | Some(&'=') | Some(&'+') | Some(&'?')
-                            ) {
-                                chars.next(); // consume ':'
-                                let op_char = chars.next().unwrap();
-                                let operand = self.read_brace_operand(&mut chars);
-                                let operator = match op_char {
-                                    '-' => ParameterOp::UseDefault,
-                                    '=' => ParameterOp::AssignDefault,
-                                    '+' => ParameterOp::UseReplacement,
-                                    '?' => ParameterOp::Error,
-                                    _ => unreachable!(),
-                                };
-                                push_part!(WordPart::IndirectExpansion {
-                                    name: var_name,
-                                    operator: Some(operator),
-                                    operand,
-                                    colon_variant: true,
-                                });
-                            } else {
-                                // `${!x:1:2}`: substring of the named variable.
-                                let suffix = self.read_brace_operand(&mut chars);
-                                push_part!(WordPart::IndirectSuffix {
-                                    name: var_name,
-                                    suffix,
-                                });
-                            }
-                        } else if matches!(
-                            chars.peek(),
-                            Some(&'-') | Some(&'=') | Some(&'+') | Some(&'?')
-                        ) {
-                            // ${!var-op} - indirect expansion with non-colon operator
-                            let op_char = chars.next().unwrap();
-                            let operand = self.read_brace_operand(&mut chars);
-                            let operator = match op_char {
-                                '-' => ParameterOp::UseDefault,
-                                '=' => ParameterOp::AssignDefault,
-                                '+' => ParameterOp::UseReplacement,
-                                '?' => ParameterOp::Error,
-                                _ => unreachable!(),
-                            };
-                            push_part!(WordPart::IndirectExpansion {
-                                name: var_name,
-                                operator: Some(operator),
-                                operand,
-                                colon_variant: false,
-                            });
-                        } else {
-                            // ${!prefix*} or ${!prefix@} - prefix matching
-                            let suffix = self.read_brace_operand(&mut chars);
-                            // `${!ref@a}`: transform the variable `ref` names.
-                            if push_indirect_transformation(
-                                &mut parts,
-                                &mut part_quoted,
-                                in_quoted_segment,
-                                &var_name,
-                                &suffix,
-                            ) {
-                            } else if suffix.ends_with('*') || suffix.ends_with('@') {
-                                let full_prefix =
-                                    format!("{}{}", var_name, &suffix[..suffix.len() - 1]);
-                                push_part!(WordPart::PrefixMatch {
-                                    prefix: full_prefix,
-                                    star: suffix.ends_with('*'),
-                                });
-                            } else {
-                                push_part!(WordPart::IndirectSuffix {
-                                    name: var_name,
-                                    suffix,
-                                });
-                            }
-                        }
-                    } else {
-                        // Read variable name
-                        let mut var_name = String::new();
-                        while let Some(&c) = chars.peek() {
-                            if c.is_ascii_alphanumeric() || c == '_' {
-                                var_name.push(chars.next().unwrap());
-                            } else {
-                                break;
-                            }
-                        }
-
-                        // Handle special parameters: ${@...}, ${*...}, ${-...},
-                        // ${?...}, ${$...}
-                        if var_name.is_empty()
-                            && let Some(&c) = chars.peek()
-                            && matches!(c, '@' | '*' | '-' | '?' | '$' | '#')
-                        {
-                            var_name.push(chars.next().unwrap());
-                        }
-
-                        // Check for array access ${arr[index]} or ${arr[@]:offset:length}
-                        // `${arr[i]OP...}` with a pattern/case/transform OP reuses the
-                        // scalar operator parsing below on the name `arr[i]`.
-                        let mut subscript_op = false;
-                        let had_subscript = chars.peek() == Some(&'[');
-                        if chars.peek() == Some(&'[') {
-                            chars.next(); // consume '['
-                            let mut index = String::new();
-                            // Track nesting so nested ${...} containing
-                            // brackets (e.g. ${#arr[@]}) don't prematurely
-                            // close the subscript.
-                            let mut bracket_depth: i32 = 0;
-                            let mut brace_depth: i32 = 0;
-                            while let Some(&c) = chars.peek() {
-                                if c == ']' && bracket_depth == 0 && brace_depth == 0 {
-                                    chars.next();
-                                    break;
-                                }
-                                match c {
-                                    '[' => bracket_depth += 1,
-                                    ']' => bracket_depth -= 1,
-                                    '$' => {
-                                        index.push(chars.next().unwrap());
-                                        if chars.peek() == Some(&'{') {
-                                            brace_depth += 1;
-                                            index.push(chars.next().unwrap());
-                                            continue;
-                                        }
-                                        continue;
-                                    }
-                                    '{' => brace_depth += 1,
-                                    '}' if brace_depth > 0 => brace_depth -= 1,
-                                    '}' => {}
-                                    _ => {}
-                                }
-                                index.push(chars.next().unwrap());
-                            }
-                            // Strip surrounding quotes from index (e.g. "foo" -> foo)
-                            if index.len() >= 2
-                                && ((index.starts_with('"') && index.ends_with('"'))
-                                    || (index.starts_with('\'') && index.ends_with('\'')))
-                            {
-                                index = index[1..index.len() - 1].to_string();
-                            }
-                            // After ], check for operators on array subscripts
-                            if let Some(&next_c) = chars.peek() {
-                                if next_c == ':' {
-                                    // Peek ahead to distinguish param ops (:- := :+ :?) from slice (:N)
-                                    let mut lookahead = chars.clone();
-                                    lookahead.next(); // skip ':'
-                                    let is_param_op = matches!(
-                                        lookahead.peek(),
-                                        Some(&'-') | Some(&'=') | Some(&'+') | Some(&'?')
-                                    );
-                                    if is_param_op {
-                                        chars.next(); // consume ':'
-                                        let arr_name = format!("{}[{}]", var_name, index);
-                                        let op_char = chars.next().unwrap();
-                                        let operand = self.read_brace_operand(&mut chars);
-                                        let operator = match op_char {
-                                            '-' => ParameterOp::UseDefault,
-                                            '=' => ParameterOp::AssignDefault,
-                                            '+' => ParameterOp::UseReplacement,
-                                            '?' => ParameterOp::Error,
-                                            _ => unreachable!(),
-                                        };
-                                        push_part!(WordPart::ParameterExpansion {
-                                            name: arr_name,
-                                            operator,
-                                            operand,
-                                            colon_variant: true,
-                                        });
-                                    } else {
-                                        // Array slice ${arr[@]:offset:length}
-                                        chars.next(); // consume ':'
-                                        let offset = read_slice_field(&mut chars, true);
-                                        let length = if chars.peek() == Some(&':') {
-                                            chars.next();
-                                            Some(read_slice_field(&mut chars, false))
-                                        } else {
-                                            None
-                                        };
-                                        if chars.peek() == Some(&'}') {
-                                            chars.next();
-                                        }
-                                        // `${a[@]:}`: an empty offset is a
-                                        // bad substitution (bash).
-                                        if offset.is_empty() && length.is_none() {
-                                            push_part!(WordPart::BadSubstitution(format!(
-                                                "${{{}[{index}]:}}",
-                                                std::mem::take(&mut var_name)
-                                            )));
-                                        } else {
-                                            // `${a[@]:o:l}` slices the elements,
-                                            // `${a[1]:o:l}` the element's text.
-                                            push_part!(WordPart::Substring {
-                                                name: format!(
-                                                    "{}[{}]",
-                                                    std::mem::take(&mut var_name),
-                                                    index
-                                                ),
-                                                offset,
-                                                length,
-                                            });
-                                        }
-                                    }
-                                } else if matches!(next_c, '-' | '+' | '=' | '?') {
-                                    // Non-colon operators on array: ${arr[@]-default}
-                                    let arr_name = format!("{}[{}]", var_name, index);
-                                    let op_char = chars.next().unwrap();
-                                    let operand = self.read_brace_operand(&mut chars);
-                                    let operator = match op_char {
-                                        '-' => ParameterOp::UseDefault,
-                                        '=' => ParameterOp::AssignDefault,
-                                        '+' => ParameterOp::UseReplacement,
-                                        '?' => ParameterOp::Error,
-                                        _ => unreachable!(),
-                                    };
-                                    push_part!(WordPart::ParameterExpansion {
-                                        name: arr_name,
-                                        operator,
-                                        operand,
-                                        colon_variant: false,
-                                    });
-                                } else if matches!(next_c, '#' | '%' | '/' | '^' | ',' | '~' | '@')
-                                {
-                                    var_name = format!("{}[{}]", var_name, index);
-                                    subscript_op = true;
-                                } else {
-                                    // Plain array access ${arr[index]}
-                                    if chars.peek() == Some(&'}') {
-                                        chars.next();
-                                    }
-                                    push_part!(WordPart::ArrayAccess {
-                                        name: std::mem::take(&mut var_name),
-                                        index,
-                                    });
-                                }
-                            } else {
-                                push_part!(WordPart::ArrayAccess {
-                                    name: std::mem::take(&mut var_name),
-                                    index,
-                                });
-                            }
-                        }
-                        if (!had_subscript || subscript_op)
-                            && let Some(&c) = chars.peek()
-                        {
-                            // Check for operator
-                            match c {
-                                ':' => {
-                                    chars.next(); // consume ':'
-                                    match chars.peek() {
-                                        Some(&'-') | Some(&'=') | Some(&'+') | Some(&'?') => {
-                                            let op_char = chars.next().unwrap();
-                                            let operand = self.read_brace_operand(&mut chars);
-                                            let operator = match op_char {
-                                                '-' => ParameterOp::UseDefault,
-                                                '=' => ParameterOp::AssignDefault,
-                                                '+' => ParameterOp::UseReplacement,
-                                                '?' => ParameterOp::Error,
-                                                _ => unreachable!(),
-                                            };
-                                            push_part!(WordPart::ParameterExpansion {
-                                                name: var_name,
-                                                operator,
-                                                operand,
-                                                colon_variant: true,
-                                            });
-                                        }
-                                        _ => {
-                                            // Substring extraction ${var:offset} or ${var:offset:length}
-                                            let offset = read_slice_field(&mut chars, true);
-                                            let length = if chars.peek() == Some(&':') {
-                                                chars.next(); // consume ':'
-                                                Some(read_slice_field(&mut chars, false))
-                                            } else {
-                                                None
-                                            };
-                                            if chars.peek() == Some(&'}') {
-                                                chars.next();
-                                            }
-                                            if offset.is_empty() && length.is_none() {
-                                                push_part!(WordPart::BadSubstitution(format!(
-                                                    "${{{var_name}:}}"
-                                                )));
-                                            } else {
-                                                push_part!(WordPart::Substring {
-                                                    name: var_name,
-                                                    offset,
-                                                    length,
-                                                });
-                                            }
-                                        }
-                                    }
-                                }
-                                // Non-colon test operators: ${var-default}, ${var+alt}, ${var=assign}, ${var?err}
-                                '-' | '=' | '+' | '?' => {
-                                    let op_char = chars.next().unwrap();
-                                    let operand = self.read_brace_operand(&mut chars);
-                                    let operator = match op_char {
-                                        '-' => ParameterOp::UseDefault,
-                                        '=' => ParameterOp::AssignDefault,
-                                        '+' => ParameterOp::UseReplacement,
-                                        '?' => ParameterOp::Error,
-                                        _ => unreachable!(),
-                                    };
-                                    push_part!(WordPart::ParameterExpansion {
-                                        name: var_name,
-                                        operator,
-                                        operand,
-                                        colon_variant: false,
-                                    });
-                                }
-                                '#' => {
-                                    chars.next();
-                                    if chars.peek() == Some(&'#') {
-                                        chars.next();
-                                        let op = self.read_brace_operand(&mut chars);
-                                        push_part!(WordPart::ParameterExpansion {
-                                            name: var_name,
-                                            operator: ParameterOp::RemovePrefixLong,
-                                            operand: op,
-                                            colon_variant: false,
-                                        });
-                                    } else {
-                                        let op = self.read_brace_operand(&mut chars);
-                                        push_part!(WordPart::ParameterExpansion {
-                                            name: var_name,
-                                            operator: ParameterOp::RemovePrefixShort,
-                                            operand: op,
-                                            colon_variant: false,
-                                        });
-                                    }
-                                }
-                                '%' => {
-                                    chars.next();
-                                    if chars.peek() == Some(&'%') {
-                                        chars.next();
-                                        let op = self.read_brace_operand(&mut chars);
-                                        push_part!(WordPart::ParameterExpansion {
-                                            name: var_name,
-                                            operator: ParameterOp::RemoveSuffixLong,
-                                            operand: op,
-                                            colon_variant: false,
-                                        });
-                                    } else {
-                                        let op = self.read_brace_operand(&mut chars);
-                                        push_part!(WordPart::ParameterExpansion {
-                                            name: var_name,
-                                            operator: ParameterOp::RemoveSuffixShort,
-                                            operand: op,
-                                            colon_variant: false,
-                                        });
-                                    }
-                                }
-                                '/' => {
-                                    chars.next();
-                                    let replace_all = if chars.peek() == Some(&'/') {
-                                        chars.next();
-                                        true
-                                    } else {
-                                        false
-                                    };
-                                    let mut pattern = String::new();
-                                    // `${x///}`, `${x////c}`: the pattern
-                                    // cannot be empty, so a `/` right after
-                                    // `//` is the pattern itself.
-                                    if replace_all && chars.peek() == Some(&'/') {
-                                        chars.next();
-                                        pattern.push('/');
-                                    }
-                                    let mut in_dq = false;
-                                    while let Some(&ch) = chars.peek() {
-                                        if ch == '\x00' {
-                                            pattern.push(chars.next().unwrap());
-                                            if let Some(n) = chars.next() {
-                                                pattern.push(n);
-                                            }
-                                            continue;
-                                        }
-                                        if ch == '"' {
-                                            in_dq = !in_dq;
-                                        } else if !in_dq && (ch == '/' || ch == '}') {
-                                            break;
-                                        }
-                                        if ch == '\\' {
-                                            chars.next();
-                                            if let Some(&next) = chars.peek()
-                                                && next == '/'
-                                            {
-                                                pattern.push(chars.next().unwrap());
-                                                continue;
-                                            }
-                                            pattern.push('\\');
-                                            if let Some(n) = chars.next() {
-                                                pattern.push(n);
-                                            }
-                                            continue;
-                                        }
-                                        pattern.push(chars.next().unwrap());
-                                    }
-                                    let replacement = if chars.peek() == Some(&'/') {
-                                        chars.next();
-                                        let mut repl = String::new();
-                                        let mut in_dq = false;
-                                        while let Some(&ch) = chars.peek() {
-                                            if ch == '\x00' {
-                                                repl.push(chars.next().unwrap());
-                                                if let Some(n) = chars.next() {
-                                                    repl.push(n);
-                                                }
-                                                continue;
-                                            }
-                                            if ch == '"' {
-                                                in_dq = !in_dq;
-                                            } else if ch == '\'' && !in_dq {
-                                                // `"${y/b/'}'}"`: a single-quoted span
-                                                // hides `}`; the expansion quote-removes it.
-                                                repl.push(chars.next().unwrap());
-                                                for q in chars.by_ref() {
-                                                    repl.push(q);
-                                                    if q == '\'' {
-                                                        break;
-                                                    }
-                                                }
-                                                continue;
-                                            } else if ch == '\\' {
-                                                repl.push(chars.next().unwrap());
-                                                if let Some(n) = chars.next() {
-                                                    // `\/` is a literal slash, as in the
-                                                    // pattern (bash removes the backslash).
-                                                    if n == '/' {
-                                                        repl.pop();
-                                                    }
-                                                    repl.push(n);
-                                                }
-                                                continue;
-                                            } else if !in_dq && ch == '}' {
-                                                break;
-                                            }
-                                            repl.push(chars.next().unwrap());
-                                        }
-                                        repl
-                                    } else {
-                                        String::new()
-                                    };
-                                    if chars.peek() == Some(&'}') {
-                                        chars.next();
-                                    }
-                                    let op = if replace_all {
-                                        ParameterOp::ReplaceAll {
-                                            pattern,
-                                            replacement,
-                                        }
-                                    } else {
-                                        ParameterOp::ReplaceFirst {
-                                            pattern,
-                                            replacement,
-                                        }
-                                    };
-                                    push_part!(WordPart::ParameterExpansion {
-                                        name: var_name,
-                                        operator: op,
-                                        operand: String::new(),
-                                        colon_variant: false,
-                                    });
-                                }
-                                '^' => {
-                                    chars.next();
-                                    let op = if chars.peek() == Some(&'^') {
-                                        chars.next();
-                                        ParameterOp::UpperAll
-                                    } else {
-                                        ParameterOp::UpperFirst
-                                    };
-                                    // `${v^^pat}`: only characters matching `pat`.
-                                    let operand = self.read_brace_operand(&mut chars);
-                                    push_part!(WordPart::ParameterExpansion {
-                                        name: var_name,
-                                        operator: op,
-                                        operand,
-                                        colon_variant: false,
-                                    });
-                                }
-                                '~' => {
-                                    // `${v~}` / `${v~~}`: toggle case (undocumented
-                                    // in the bash manual, supported by bash 4+).
-                                    chars.next();
-                                    let op = if chars.peek() == Some(&'~') {
-                                        chars.next();
-                                        ParameterOp::ToggleAll
-                                    } else {
-                                        ParameterOp::ToggleFirst
-                                    };
-                                    let operand = self.read_brace_operand(&mut chars);
-                                    push_part!(WordPart::ParameterExpansion {
-                                        name: var_name,
-                                        operator: op,
-                                        operand,
-                                        colon_variant: false,
-                                    });
-                                }
-                                ',' => {
-                                    chars.next();
-                                    let op = if chars.peek() == Some(&',') {
-                                        chars.next();
-                                        ParameterOp::LowerAll
-                                    } else {
-                                        ParameterOp::LowerFirst
-                                    };
-                                    // `${v^^pat}`: only characters matching `pat`.
-                                    let operand = self.read_brace_operand(&mut chars);
-                                    push_part!(WordPart::ParameterExpansion {
-                                        name: var_name,
-                                        operator: op,
-                                        operand,
-                                        colon_variant: false,
-                                    });
-                                }
-                                '@' => {
-                                    chars.next();
-                                    if let Some(&op) = chars.peek() {
-                                        chars.next();
-                                        if chars.peek() == Some(&'}') {
-                                            chars.next();
-                                        }
-                                        push_part!(WordPart::Transformation {
-                                            name: var_name,
-                                            operator: op,
-                                        });
-                                    } else {
-                                        if chars.peek() == Some(&'}') {
-                                            chars.next();
-                                        }
-                                        push_part!(WordPart::Variable(var_name));
-                                    }
-                                }
-                                '}' => {
-                                    chars.next();
-                                    if !var_name.is_empty() {
-                                        push_part!(WordPart::Variable(var_name));
-                                    }
-                                }
-                                _ => {
-                                    while let Some(&ch) = chars.peek() {
-                                        if ch == '}' {
-                                            chars.next();
-                                            break;
-                                        }
-                                        chars.next();
-                                    }
-                                    if !var_name.is_empty() {
-                                        push_part!(WordPart::Variable(var_name));
-                                    }
-                                }
-                            }
-                        } else if !had_subscript && !var_name.is_empty() {
-                            push_part!(WordPart::Variable(var_name));
-                        }
-                    }
+                    self.parse_braced_parameter(
+                        &mut chars,
+                        &mut parts,
+                        &mut part_quoted,
+                        in_quoted_segment,
+                    );
                 } else if let Some(&c) = chars.peek() {
                     // Check for special single-character variables ($?, $#, $@, $*, $!, $$, $-, $0-$9)
                     if matches!(c, '?' | '#' | '@' | '*' | '!' | '$' | '-') || c.is_ascii_digit() {
@@ -4896,60 +4912,13 @@ impl<'a> Parser<'a> {
             push_part!(WordPart::Literal(current));
         }
 
-        // Empty quoted parts only matter next to an unquoted expansion
-        // (`""$x""` keeps empty fields) or a quoted `@` expansion (`"$@"""`
-        // is one empty field when there are no positional parameters);
-        // elsewhere drop them so the word keeps its plain shape.
-        if has_empty_quoted {
-            let unquoted_expansion = parts
-                .iter()
-                .zip(&part_quoted)
-                .any(|(p, q)| !*q && !matches!(p, WordPart::Literal(_)));
-            let quoted_at = parts.iter().zip(&part_quoted).any(|(p, q)| {
-                *q && match p {
-                    WordPart::Variable(name) => name == "@",
-                    WordPart::ArrayAccess { index, .. } => index == "@",
-                    WordPart::ParameterExpansion { name, .. }
-                    | WordPart::Transformation { name, .. }
-                    | WordPart::Substring { name, .. } => name == "@" || name.ends_with("[@]"),
-                    _ => false,
-                }
-            });
-            // `{X,,Y,}''`: brace items next to the empty quotes are words
-            // even when empty.
-            let brace_candidate = parts
-                .iter()
-                .zip(&part_quoted)
-                .any(|(p, q)| !*q && matches!(p, WordPart::Literal(t) if t.contains('{')));
-            if !unquoted_expansion && !quoted_at && !brace_candidate {
-                let mut kept_parts = Vec::with_capacity(parts.len());
-                let mut kept_quoted = Vec::with_capacity(parts.len());
-                for (p, q) in parts.into_iter().zip(part_quoted) {
-                    if !matches!(&p, WordPart::Literal(s) if s.is_empty()) {
-                        kept_parts.push(p);
-                        kept_quoted.push(q);
-                    }
-                }
-                parts = kept_parts;
-                part_quoted = kept_quoted;
-            }
-        }
-
-        // If no parts, create an empty literal
-        if parts.is_empty() {
-            push_part!(WordPart::Literal(String::new()));
-        }
-
-        // Every part quoted (`'a'"$x"`, `"$x"""`): the word is quoted, so its
-        // expansions are not field-split.
-        let quoted = saw_quote_marker && part_quoted.iter().all(|q| *q);
-        Word {
+        finish_word(
             parts,
-            quoted,
-            has_unquoted_glob: false,
             part_quoted,
-            raw: None,
-        }
+            has_empty_quoted,
+            saw_quote_marker,
+            in_quoted_segment,
+        )
     }
 
     /// Read operand for brace expansion (everything until closing brace)
@@ -5012,9 +4981,146 @@ fn add_stderr_to_pipe(cmd: &mut Command) {
     }
 }
 
-/// `cmd &` right before a closing keyword: an empty command carrying the `&`.
-/// Out of line so the `Command` temporary does not enlarge the recursive
-/// `parse_command_list` frame (nested `$(...)` parse depth, TM-DOS-044).
+// AST assembly runs after recursive parsing returns, keeping its temporaries
+// off the recursive grammar frames (TM-DOS-044).
+#[inline(never)]
+fn finish_command_list(
+    first: Option<Box<Command>>,
+    rest: Vec<(ListOperator, Command)>,
+    span: Span,
+) -> Result<Option<Box<Command>>> {
+    let Some(first) = first else {
+        return Ok(None);
+    };
+    if rest.is_empty() {
+        Ok(Some(first))
+    } else {
+        Ok(Some(Box::new(Command::List(CommandList {
+            first,
+            rest,
+            span,
+        }))))
+    }
+}
+
+#[inline(never)]
+fn finish_pipeline(
+    commands: Vec<Command>,
+    negated: bool,
+    span: Span,
+) -> Result<Option<Box<Command>>> {
+    Ok(Some(Box::new(Command::Pipeline(Pipeline {
+        negated,
+        commands,
+        span,
+    }))))
+}
+
+#[inline(never)]
+fn finish_word(
+    mut parts: Vec<WordPart>,
+    mut part_quoted: Vec<bool>,
+    has_empty_quoted: bool,
+    saw_quote_marker: bool,
+    in_quoted_segment: bool,
+) -> Word {
+    // Empty quoted parts only matter next to an unquoted expansion
+    // (`""$x""` keeps empty fields) or a quoted `@` expansion (`"$@"""`
+    // is one empty field when there are no positional parameters);
+    // elsewhere drop them so the word keeps its plain shape.
+    if has_empty_quoted {
+        let unquoted_expansion = parts
+            .iter()
+            .zip(&part_quoted)
+            .any(|(p, q)| !*q && !matches!(p, WordPart::Literal(_)));
+        let quoted_at = parts.iter().zip(&part_quoted).any(|(p, q)| {
+            *q && match p {
+                WordPart::Variable(name) => name == "@",
+                WordPart::ArrayAccess { index, .. } => index == "@",
+                WordPart::ParameterExpansion { name, .. }
+                | WordPart::Transformation { name, .. }
+                | WordPart::Substring { name, .. } => name == "@" || name.ends_with("[@]"),
+                _ => false,
+            }
+        });
+        // `{X,,Y,}''`: brace items next to the empty quotes are words
+        // even when empty.
+        let brace_candidate = parts
+            .iter()
+            .zip(&part_quoted)
+            .any(|(p, q)| !*q && matches!(p, WordPart::Literal(t) if t.contains('{')));
+        if !unquoted_expansion && !quoted_at && !brace_candidate {
+            let mut kept_parts = Vec::with_capacity(parts.len());
+            let mut kept_quoted = Vec::with_capacity(parts.len());
+            for (p, q) in parts.into_iter().zip(part_quoted) {
+                if !matches!(&p, WordPart::Literal(s) if s.is_empty()) {
+                    kept_parts.push(p);
+                    kept_quoted.push(q);
+                }
+            }
+            parts = kept_parts;
+            part_quoted = kept_quoted;
+        }
+    }
+
+    // If no parts, create an empty literal
+    if parts.is_empty() {
+        parts.push(WordPart::Literal(String::new()));
+        part_quoted.push(in_quoted_segment);
+    }
+
+    // Every part quoted (`'a'"$x"`, `"$x"""`): the word is quoted, so its
+    // expansions are not field-split.
+    let quoted = saw_quote_marker && part_quoted.iter().all(|q| *q);
+    Word {
+        parts,
+        quoted,
+        has_unquoted_glob: false,
+        part_quoted,
+        raw: None,
+    }
+}
+
+// AST assembly runs after recursive parsing returns, keeping its temporaries
+// off the recursive grammar frames (TM-DOS-044).
+#[inline(never)]
+fn finish_simple_command(
+    mut words: Vec<Word>,
+    assignments: Vec<Assignment>,
+    redirects: Vec<Redirect>,
+    span: Span,
+) -> Result<Option<SimpleCommand>> {
+    // Handle assignment-only and redirect-only commands (`VAR=value`,
+    // `< file`, `> file`): bash runs them as null commands that still
+    // perform their assignments/redirections (#2448: `$(<file)`).
+    if words.is_empty() && (!assignments.is_empty() || !redirects.is_empty()) {
+        return Ok(Some(SimpleCommand {
+            name: Word::literal(""),
+            args: Vec::new(),
+            redirects,
+            assignments,
+            span,
+        }));
+    }
+
+    if words.is_empty() {
+        return Ok(None);
+    }
+
+    let name = words.remove(0);
+    let args = words;
+
+    Ok(Some(SimpleCommand {
+        name,
+        args,
+        redirects,
+        assignments,
+        span,
+    }))
+}
+
+/// `cmd &` before a closing keyword: an empty command carrying the `&`.
+/// Keep its `Command` temporary off the recursive list frame (TM-DOS-044).
 #[inline(never)]
 fn empty_background(span: Span) -> (ListOperator, Command) {
     (
@@ -6102,6 +6208,87 @@ mod tests {
         }
     }
 
+    fn nested_command_substitution(levels: usize) -> String {
+        let mut script = String::from("echo ok");
+        for _ in 0..levels {
+            script = format!("echo $({script})");
+        }
+        script
+    }
+
+    #[test]
+    fn nested_command_substitution_consumes_ast_depth() {
+        let script = nested_command_substitution(4);
+        let err = Parser::with_limits(&script, 3, 10_000)
+            .parse()
+            .expect_err("substitution parsers must share AST depth");
+        assert!(err.to_string().contains("AST nesting too deep"));
+    }
+
+    #[test]
+    fn nested_command_substitution_parser_is_stack_safe() {
+        let script = nested_command_substitution(50);
+        Parser::new(&script)
+            .parse()
+            .expect("depth 50 remains within the hard AST limit");
+    }
+
+    #[test]
+    fn nested_command_substitution_hard_cap_is_stack_safe() {
+        let script = nested_command_substitution(120);
+        let err = Parser::with_limits(&script, usize::MAX, 100_000)
+            .parse()
+            .expect_err("the hard AST cap also covers substitution parsers");
+        assert!(err.to_string().contains("AST nesting too deep"));
+    }
+
+    #[test]
+    fn nested_command_substitution_depth_boundary() {
+        let valid = nested_command_substitution(3);
+        Parser::with_limits(&valid, 3, 10_000).parse().unwrap();
+        let mixed = "if true; then echo $(echo $(echo ok)); fi";
+        Parser::with_limits(mixed, 3, 10_000).parse().unwrap();
+        let err = Parser::with_limits(mixed, 2, 10_000).parse().unwrap_err();
+        assert!(err.to_string().contains("AST nesting too deep"));
+    }
+
+    #[test]
+    fn nested_command_substitution_hard_cap_in_other_grammar_positions() {
+        for template in [
+            "echo $(true; BODY)",
+            "echo $(true | BODY)",
+            "x=$(BODY)",
+            "echo $(>out BODY)",
+            "a=($(BODY))",
+            "declare a=($(BODY))",
+            "echo $(echo ${v:-x}; BODY)",
+        ] {
+            let mut script = String::from("echo ok");
+            for _ in 0..120 {
+                script = template.replace("BODY", &script);
+            }
+            let err = Parser::with_limits(&script, usize::MAX, 100_000)
+                .parse()
+                .unwrap_err();
+            assert!(
+                err.to_string().contains("AST nesting too deep"),
+                "{template}: {err}"
+            );
+        }
+    }
+
+    #[test]
+    fn nested_command_substitution_preserves_timeout_origin() {
+        let mut parent =
+            Parser::with_limits_and_timeout("echo ok", 10, 1000, Some(Duration::from_millis(1)));
+        parent.started_at = Instant::now() - Duration::from_secs(1);
+        let mut child = parent.nested_parser("echo ok").unwrap();
+        assert!(matches!(
+            child.parse_inner(),
+            Err(Error::ResourceLimit(LimitExceeded::ParserTimeout(_)))
+        ));
+    }
+
     fn nested_process_substitution(levels: usize) -> String {
         let mut script = String::from("cat ");
         for _ in 0..levels {
diff --git a/crates/bashkit/tests/integration/blackbox_security_tests.rs b/crates/bashkit/tests/integration/blackbox_security_tests.rs
index 4a316137a..f10c6bf1a 100644
--- a/crates/bashkit/tests/integration/blackbox_security_tests.rs
+++ b/crates/bashkit/tests/integration/blackbox_security_tests.rs
@@ -86,6 +86,59 @@ mod finding_nested_cmd_subst_stack_overflow {
             Err(_) => {}
         }
     }
+    #[tokio::test]
+    async fn hard_ast_cap_rejects_substitutions_and_session_recovers() {
+        let mut bash = Bash::builder()
+            .limits(ExecutionLimits::new().max_ast_depth(usize::MAX))
+            .build();
+        let mut script = String::from("echo deep > /should-not-exist");
+        for _ in 0..120 {
+            script = format!("echo $({script})");
+        }
+        let diagnostic = match bash.exec(&script).await {
+            Ok(result) => {
+                assert_eq!(result.exit_code, 2);
+                assert!(result.stdout.is_empty());
+                result.stderr.to_string()
+            }
+            Err(err) => err.to_string(),
+        };
+        assert!(diagnostic.contains("AST nesting too deep"), "{diagnostic}");
+        assert!(
+            !bash
+                .fs()
+                .exists(std::path::Path::new("/should-not-exist"))
+                .await
+                .unwrap()
+        );
+        assert_eq!(
+            bash.exec("echo recovered").await.unwrap().stdout,
+            "recovered\n"
+        );
+    }
+
+    #[tokio::test]
+    async fn moderate_substitutions_match_real_bash() {
+        for template in [
+            "echo $(BODY)",
+            "x=$(BODY); echo \"$x\"",
+            "echo $(true; BODY)",
+        ] {
+            let mut script = String::from("echo hello");
+            for _ in 0..6 {
+                script = template.replace("BODY", &script);
+            }
+            let reference = std::process::Command::new("/bin/bash")
+                .args(["--noprofile", "--norc", "-c", &script])
+                .output()
+                .unwrap();
+            assert!(reference.status.success());
+            let result = tight_bash().exec(&script).await.unwrap();
+            assert_eq!(result.exit_code, 0);
+            assert_eq!(result.stdout.as_bytes(), reference.stdout, "{template}");
+            assert_eq!(result.stderr.as_bytes(), reference.stderr, "{template}");
+        }
+    }
 }
 
 // =============================================================================

From d3b1d7f0d3ec230e26e701daa1dc29e0c0cb1eb4 Mon Sep 17 00:00:00 2001
From: Mykhailo Chalyi <mike@chaliy.name>
Date: Sun, 11 Oct 2026 13:10:23 -0500
Subject: [PATCH 6/8] chore(knowledge): document substitution depth and stack
 safety

---
 knowledge/foundations/parser.md    | 21 +++++++++++++++++++++
 knowledge/security/threat-model.md | 12 ++++++++----
 2 files changed, 29 insertions(+), 4 deletions(-)

diff --git a/knowledge/foundations/parser.md b/knowledge/foundations/parser.md
index 871aed79c..b619abb74 100644
--- a/knowledge/foundations/parser.md
+++ b/knowledge/foundations/parser.md
@@ -24,6 +24,27 @@ Input → Lexer → Tokens → Parser → AST
 Token types, AST structures, and parser grammar live in
 `crates/bashkit/src/parser/`. They evolve as features are added.
 
+### Native Stack and Substitution Depth
+
+`max_ast_depth` (default and hard ceiling 100) counts compound commands,
+process substitutions, and each child command-substitution parser. A child
+inherits the enclosing depth plus one, the same ceiling, remaining fuel,
+execution budget, options, timeout, and original start time. A simple-command
+`$(...)` cannot reset the depth counter or restart its timeout.
+
+Child parsers stay boxed while parsing by mutable reference. Private grammar
+results also carry boxed command nodes across recursive calls; commands are
+unboxed into the existing public AST vectors. A lone pipeline reuses its first
+boxed command without building an intermediate vector. This avoids retaining
+large command move temporaries on the native stack. Nonrecursive
+braced-parameter parsing and AST assembly are outlined so their debug-build
+stack temporaries are not retained at every recursive level (TM-DOS-044).
+The default 2 MiB Rust test-thread stack must handle depth-50 substitutions
+and reject input beyond the hard ceiling, including oversized caller limits.
+Do not increase thread stacks or reduce the existing ceiling to hide a crash.
+Parser unit tests cover exact depth boundaries and mixed compound/substitution
+nesting; integration tests cover execution, shell recovery, and real Bash parity.
+
 ### Parser Rules (Simplified)
 
 ```
diff --git a/knowledge/security/threat-model.md b/knowledge/security/threat-model.md
index 6b5f19c5b..c3fb3420f 100644
--- a/knowledge/security/threat-model.md
+++ b/knowledge/security/threat-model.md
@@ -238,7 +238,7 @@ runaway scripts without permanently breaking the session.
 | ID | Threat | Attack Vector | Mitigation | Status |
 |----|--------|--------------|------------|--------|
 | TM-DOS-020 | Function and signal-trap recursion | `f() { f; }; f` or `trap 'kill -USR1 $$' USR1; kill -USR1 $$` | Signal handlers, functions, source, and child shells share the function-depth counter, plus a dedicated trap-nesting cap of 3 that trips first on small stacks; direct, mutual, and mixed signal recursion cannot refresh either. Nested-trap exhaustion is skipped with a diagnostic and the first trip fails the exec as a resource-limit error, while handler logic failures never disturb the interrupted command (TM-DOS-030). Effective depth limit is at most 16 even if an embedder requests more; the previous default 100 and hardened 64 could overflow a 2 MiB host stack before the counter fired (#2459). CLI subprocess tests run direct, mutual, and mixed signal/function/source recursion on that stack size with small command budgets. | **MITIGATED** |
-| TM-DOS-021 | Command sub nesting | `$($($($())))` | Child parsers inherit remaining depth budget + fuel from parent | **MITIGATED** |
+| TM-DOS-021 | Command sub nesting | `$($($($())))` | Child parsers increment shared AST depth and inherit ceiling, fuel, budget and timeout origin; heap ownership and outlined nonrecursive frames keep the hard cap stack-safe | **MITIGATED** |
 | TM-DOS-022 | Parser recursion | Deeply nested `(((())))` | `max_ast_depth` limit (100) + `HARD_MAX_AST_DEPTH` cap (100) | **MITIGATED** |
 | TM-DOS-026 | Arithmetic recursion and expansion amplification | `$((((...))))`, `a=a+a; $((a))`, `i=arr[i]; $((arr[i]))`, nested `${a[${a[...]}]}` passed to `let` | `MAX_ARITHMETIC_DEPTH` limit (50) checked before dollar expansion and tokenization; shared fuel across textual expansion, nested read-only subscripts, nameref/key lookup, and recursive variable evaluation; expanded-size cap | **MITIGATED** |
 | TM-DOS-064 | Heredoc suffix re-injection CPU amplification | Many `: <<E && : <<E ...` heredocs on one logical line repeatedly copy command-line suffixes | `read_heredoc_with_strip_metered` reports re-injected suffix length; parser charges it to `max_parser_operations` fuel | **MITIGATED** |
@@ -246,8 +246,12 @@ runaway scripts without permanently breaking the session.
 **Current Risk**: LOW. Implementation: `max_function_depth` 16 with a hard ceiling of 16 (TM-DOS-020/021) and `max_ast_depth` 100 (TM-DOS-022) in `limits.rs`; child parsers in command/process substitution inherit remaining depth budget + fuel from parent (TM-DOS-021, `parser/mod.rs`); arithmetic evaluator caps recursion at `MAX_ARITHMETIC_DEPTH` 50, shares expansion fuel across dollar expansion and subscript/variable evaluation, bounds variable cycles, and caps generated expression bytes (TM-DOS-026, `interpreter/mod.rs` `MAX_ARITHMETIC_DEPTH` / `MAX_ARITHMETIC_EXPANSION_*`); heredoc rest-of-line re-injection charged to parser fuel (TM-DOS-064).
 
 **History** (TM-DOS-021): Previously marked MITIGATED but child parsers created via
-`Parser::new()` used default limits, ignoring parent configuration. Fixed to propagate
-`remaining_depth` and `fuel` from parent parser.
+`Parser::new()` used default limits, ignoring parent configuration. Fixed to propagate parent limits. A later regression also reset depth across
+simple-command substitutions and retained large nonrecursive temporaries in
+recursive debug-build frames. Child parsers now increment the enclosing depth,
+preserve the timeout origin, and parse by reference while heap-owned. Outlined
+parameter parsing and AST assembly keep the unchanged hard ceiling stack-safe
+on default 2 MiB test threads (TM-DOS-044).
 
 #### 1.4 CPU Exhaustion
 
@@ -1400,7 +1404,7 @@ This section maps former vulnerability IDs to the new threat ID scheme and track
 | TM-ISO-023 | `set -e` leaks across `exec()` calls | Unexpected abort, `set` options from previous exec affect next exec | `SET_OPTION_VARS` cleared in `reset_transient_state()` (**FIXED**) |
 | ~~TM-ISO-024~~ | ~~`$?` leaks into VFS subprocess~~ | ~~False `set -e` failures in VFS script subprocess~~ | `execute_script_content` resets `last_exit_code` / `nounset_error` (**FIXED**) |
 | ~~TM-INT-007~~ | ~~Binary stream corruption~~ | ~~NUL/high bytes lost across pipelines and redirects~~ | Byte-native `StreamData` transport (**FIXED**) |
-| ~~TM-DOS-044~~ | ~~Nested `$()` stack overflow (regression)~~ | ~~SIGABRT at depth ~50 despite #492 fix~~ | Depth-50 nested-subst test (`finding_nested_cmd_subst_stack_overflow::depth_50_is_bounded`) passes (**FIXED**) |
+| ~~TM-DOS-044~~ | ~~Nested `$()` stack overflow (regression)~~ | ~~SIGABRT at depth ~50 despite #492 fix~~ | Shared AST depth, heap-owned child parsers and outlined nonrecursive frames; depth-50, hard-cap and shell-recovery tests pass on default 2 MiB threads (**FIXED**) |
 | TM-DOS-088 | Command substitution OOM via state cloning | OOM at depth N (memory ≈ N × state_size) | Dedicated `max_subst_depth` limit (default 32), separate from `max_function_depth`, **FIXED** via #1088 |
 | TM-DOS-089 | Command substitution stack overflow via inlined futures | SIGABRT at ~20-30 nested $() levels | Box::pin `expand_word` and `execute_cmd_subst` to cap per-level stack, **FIXED** via #1089 |
 | ~~TM-DOS-090~~ | ~~`shuf` unbounded range/repeat materialization~~ | ~~OOM/CPU via huge `--input-range`/`--head-count` before stdout truncation~~ | Sample ranges without full collection; reject over-limit output pre-allocation; `shuf_resource_tests` cover huge range `-n 1` and repeat caps (**FIXED**) |

From ecd0da5b4d59eb5a05f4fc8bc5e121f55ba5d6c5 Mon Sep 17 00:00:00 2001
From: Mykhailo Chalyi <mike@chaliy.name>
Date: Sun, 11 Oct 2026 13:46:17 -0500
Subject: [PATCH 7/8] fix(cpython): preserve embedded module alignment at
 runtime

---
 crates/bashkit-cpython-wasm/src/lib.rs | 67 +++++++++++++++++++++++---
 crates/bashkit/docs/cpython.md         |  4 +-
 2 files changed, 63 insertions(+), 8 deletions(-)

diff --git a/crates/bashkit-cpython-wasm/src/lib.rs b/crates/bashkit-cpython-wasm/src/lib.rs
index 29725b1f1..7f3c51b75 100644
--- a/crates/bashkit-cpython-wasm/src/lib.rs
+++ b/crates/bashkit-cpython-wasm/src/lib.rs
@@ -30,17 +30,58 @@ pub const STDLIB_PREFIX: &str = "/usr/local/lib";
 /// Stdlib sources, deflate-compressed zip read by CPython's `zipimport`.
 pub static STDLIB_ZIP: &[u8] = include_bytes!("../artifacts/python314.zip");
 
-// Wasmtime maps the module's data segments copy-on-write straight from these
-// bytes, which requires host-page alignment. 64 KiB covers every supported
-// page size (4 KiB x86-64, 16 KiB Apple silicon, 64 KiB some aarch64 Linux).
+// Wasmtime maps data segments from immutable host-page-aligned bytes. Keep
+// 64 KiB alignment for every supported host. Mach-O only preserves host-page
+// alignment through linking/ASLR; do not form an over-aligned Rust reference
+// there. Cache a padded, aligned copy once when the embedded slice needs one.
+const MODULE_ALIGNMENT: usize = 65536;
+
+#[cfg(not(target_vendor = "apple"))]
 #[repr(C, align(65536))]
 struct Aligned<T: ?Sized>(T);
 
+#[cfg(not(target_vendor = "apple"))]
 static CWASM: &Aligned<[u8]> = &Aligned(*include_bytes!(concat!(env!("OUT_DIR"), "/python.cwasm")));
+#[cfg(target_vendor = "apple")]
+static CWASM: &[u8] = include_bytes!(concat!(env!("OUT_DIR"), "/python.cwasm"));
+
+struct PaddedModule {
+    // Retain the Vec allocation: converting to a boxed slice can relocate it
+    // after we chose the aligned offset. No mutation is exposed after copying.
+    storage: Vec<u8>,
+    start: usize,
+    len: usize,
+}
+
+impl PaddedModule {
+    fn new(bytes: &[u8]) -> Self {
+        let mut storage = vec![0; bytes.len() + MODULE_ALIGNMENT - 1];
+        let start = storage.as_ptr().align_offset(MODULE_ALIGNMENT);
+        storage[start..start + bytes.len()].copy_from_slice(bytes);
+        Self {
+            storage,
+            start,
+            len: bytes.len(),
+        }
+    }
+
+    fn bytes(&self) -> &[u8] {
+        &self.storage[self.start..self.start + self.len]
+    }
+}
 
 /// Precompiled module bytes (Pulley, or native with the `native` feature) (for diagnostics and size reporting).
+/// The returned slice is immutable and 64 KiB aligned for the process lifetime.
 pub fn cwasm_bytes() -> &'static [u8] {
-    &CWASM.0
+    #[cfg(not(target_vendor = "apple"))]
+    let bytes: &[u8] = &CWASM.0;
+    #[cfg(target_vendor = "apple")]
+    let bytes = CWASM;
+    if bytes.as_ptr().align_offset(MODULE_ALIGNMENT) == 0 {
+        return bytes;
+    }
+    static PADDED: std::sync::OnceLock<PaddedModule> = std::sync::OnceLock::new();
+    PADDED.get_or_init(|| PaddedModule::new(bytes)).bytes()
 }
 
 /// Create an engine compatible with the embedded module.
@@ -53,13 +94,15 @@ pub fn engine() -> wasmtime::Result<wasmtime::Engine> {
 /// `engine` must come from [`engine`] or use [`engine_config`] unchanged
 /// (plus runtime-only settings).
 ///
-/// The first load in a process maps the embedded bytes in place (no copy).
+/// The first load in a process maps the aligned bytes in place. On hosts whose
+/// linker/loader cannot preserve 64 KiB alignment, these bytes are copied once
+/// into cached aligned storage first.
 /// Wasmtime registers code by address, so the same bytes cannot back two live
 /// modules; every later load copies them instead (tens of milliseconds).
 /// Hosts should load once and share the module.
 pub fn load_module(engine: &wasmtime::Engine) -> wasmtime::Result<wasmtime::Module> {
     static MAPPED: std::sync::atomic::AtomicBool = std::sync::atomic::AtomicBool::new(false);
-    let bytes: &'static [u8] = &CWASM.0;
+    let bytes = cwasm_bytes();
     // Native code must live in executable memory, never the read-only static,
     // so it is always copied (the first load costs ~35 ms more than Pulley's).
     if cfg!(feature = "native") || MAPPED.swap(true, std::sync::atomic::Ordering::AcqRel) {
@@ -68,7 +111,7 @@ pub fn load_module(engine: &wasmtime::Engine) -> wasmtime::Result<wasmtime::Modu
     }
     // SAFETY: the bytes were produced by `Engine::precompile_module` in this
     // crate's build script with the same wasmtime version and `engine_config`,
-    // live in immutable static memory for the life of the process, and are
+    // live in immutable process-lifetime storage, and are
     // mapped by at most one module (guarded by `MAPPED`).
     unsafe { wasmtime::Module::deserialize_raw(engine, std::ptr::NonNull::from(bytes)) }
 }
@@ -97,6 +140,16 @@ mod tests {
         assert_eq!(cwasm_bytes().as_ptr() as usize % 65536, 0);
     }
 
+    #[test]
+    fn padded_module_preserves_bytes_and_alignment() {
+        for len in [0, 1, 127, 65535, 65536, 65537] {
+            let input: Vec<_> = (0..len).map(|i| (i % 251) as u8).collect();
+            let module = PaddedModule::new(&input);
+            assert_eq!(module.bytes().as_ptr() as usize % 65536, 0);
+            assert_eq!(module.bytes(), input);
+        }
+    }
+
     #[test]
     fn stdlib_zip_is_a_zip() {
         assert_eq!(&STDLIB_ZIP[..4], b"PK\x03\x04");
diff --git a/crates/bashkit/docs/cpython.md b/crates/bashkit/docs/cpython.md
index f7ad4e7eb..e575bef14 100644
--- a/crates/bashkit/docs/cpython.md
+++ b/crates/bashkit/docs/cpython.md
@@ -44,7 +44,9 @@ the guest never runs native code in your process.
 The interpreter loads on the first call of a process: the first `python3`
 takes about 19 ms on the reference machine, later calls about 4.4 ms. To move
 that one-time cost out of the first request, call
-`bashkit::CPython::warm_up()` at startup.
+`bashkit::CPython::warm_up()` at startup. On hosts where the linker or loader
+cannot preserve 64 KiB module alignment, such as macOS, an aligned immutable
+copy is cached once for the process; later calls reuse it.
 
 ## Why CPython instead of Monty
 

From 9e72082ac9a56b965ed72b39521acb2cfceaaebf Mon Sep 17 00:00:00 2001
From: Mykhailo Chalyi <mike@chaliy.name>
Date: Sun, 11 Oct 2026 13:46:17 -0500
Subject: [PATCH 8/8] chore(knowledge): document immutable aligned module
 storage

---
 knowledge/runtimes/cpython-wasm.md | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/knowledge/runtimes/cpython-wasm.md b/knowledge/runtimes/cpython-wasm.md
index d231f206c..f0feb3173 100644
--- a/knowledge/runtimes/cpython-wasm.md
+++ b/knowledge/runtimes/cpython-wasm.md
@@ -62,6 +62,12 @@ call:
 3. **Zero-copy load**: the `.cwasm` is embedded 64 KiB-aligned and loaded with
    `Module::deserialize_raw`; wasmtime registers code by address, so only the
    first load in a process maps in place, later loads copy (`load_module`).
+   Mach-O linking/ASLR only preserves host-page alignment, so Apple targets
+   embed a byte slice rather than an over-aligned Rust reference. If its runtime
+   address is not 64 KiB aligned, one immutable padded `Vec` copy is cached for
+   the process lifetime; retaining the allocation preserves the chosen aligned
+   offset. Other hosts retain the aligned static fast path. The original
+   64 KiB pointer assertion plus byte-preservation tests cover this contract.
 4. **Copy-on-write instances**: `memory_init_cow` +
    `memory_guaranteed_dense_image_size(128 MB)` map the ~40 MB snapshot heap
    instead of copying it (without the dense image every instantiation copied