zsh/

exec.rs

//! Shell executor state for zshrs.
//!
//! **Not a port of Src/exec.c.** C zsh runs compiled programs on the native
//! **wordcode VM** in `Src/exec.c` (`execlist` / `execpline` / `execcmd`).
//! zshrs uses fusevm bytecode instead; the bridge lives in `src/fusevm_bridge.rs`.
//! This file holds:
//! - `ShellExecutor` — the runtime state struct that the VM and
//!   every ported builtin/utility threads through
//! - VM-adjacent helpers that read/write that state
//! - drift extension scaffolding still being moved out
//!
//! Path-wise this file lives at the crate root (`src/exec.rs`) rather
//! than in `src/ported/` because nothing here corresponds 1:1 to a
//! `Src/*.c` source file. `crate::ported::exec` is kept as a
//! re-export alias so existing call-sites continue to compile.

use crate::history::HistoryEngine;
// MathState is private to math.rs (per math.c — no public state struct);
// math API surface is matheval/mathevali/mnumber.
use crate::options::ZSH_OPTIONS_SET;
// TcpSessions struct deleted — see modules/tcp.rs ZTCP_SESSIONS thread_local.
// `Profiler`/`ProfileEntry` deleted in the zprof.rs strict-rules
// rewrite — zprof state now lives in module-level statics
// (`CALLS`/`NCALLS`/`ARCS`/`NARCS`/`STACK`/`ZPROF_MODULE`) matching
// the C file-statics at zprof.c:66-71.
use compsys::cache::CompsysCache;
use compsys::CompInitResult;
use parking_lot::Mutex;
use std::collections::HashSet;
use crate::ported::utils::{errflag, ERRFLAG_ERROR};
use std::sync::atomic::Ordering;
use crate::ported::parse::ECBUF;
use crate::ported::zsh_h::{wc_code, wc_data, WC_END, WC_LIST};
use crate::ported::zsh_h::WC_SUBLIST;
use crate::ported::zsh_h::WC_PIPE;
use crate::ported::zsh_h::{WC_ARITH, WC_CASE, WC_COND, WC_CURSH, WC_FOR, WC_FUNCDEF, WC_IF, WC_REPEAT, WC_SELECT, WC_SIMPLE, WC_SUBSH, WC_TIMED, WC_TRY, WC_WHILE, };
use crate::ported::zsh_h::{WC_FOR_LIST, WC_FOR_SKIP, WC_FOR_TYPE};
use crate::ported::zsh_h::{WC_CASE_SKIP, WC_CASE_TYPE};
use crate::ported::builtin::RETFLAG;
use crate::ported::zsh_h::{WC_IF_SKIP, WC_IF_TYPE};
use crate::ported::builtin::{BREAKS, CONTFLAG, LOOPS};
use crate::ported::zsh_h::{WC_WHILE_SKIP, WC_WHILE_TYPE};
use crate::ported::math::mathevali;
use crate::ported::parse::ecgetstr_wordcode;
use crate::ported::subst::singsub;
use crate::ported::zsh_h::WC_REPEAT_SKIP;
use crate::ported::parse::ecgetstr_wordcode as ecgetstr;
use std::fs;
use std::os::unix::io::FromRawFd;
use std::io::Read;
use std::ffi::CString;
use std::os::unix::ffi::OsStrExt;
use crate::ported::zsh_h::{options, MAX_OPS};
use crate::ported::zsh_h::{PM_INTEGER, PM_EFLOAT, PM_FFLOAT, PM_ARRAY, PM_HASHED, PM_LOWER, PM_UPPER, PM_READONLY, PM_EXPORTED, PM_LEFT, PM_RIGHT_B, PM_RIGHT_Z};
use std::ffi::CStr;
use crate::ported::zle::zle_thingy::{listwidgets, getwidgettarget};
use std::time::{SystemTime, UNIX_EPOCH};
use walkdir::WalkDir;
use std::os::unix::fs::FileTypeExt;
use std::os::unix::fs::PermissionsExt;
use std::sync::atomic::AtomicI32;
use crate::ported::modules::parameter::*;
use crate::ported::zsh_h::PM_UNDEFINED;

// Backward-compat re-exports for free fns recently relocated to their
// canonical-C-file Rust modules. Existing call-sites in this file (and
// elsewhere) still reference these unqualified.
#[allow(unused_imports)]
#[allow(unused_imports)]
pub(crate) use crate::ported::glob::{expand_glob_alternation, find_top_level_tilde};
#[allow(unused_imports)]
pub use crate::ported::params::convbase as format_int_in_base;
pub use crate::ported::params::convbase_underscore;
#[allow(unused_imports)]
pub(crate) use crate::ported::math::{parse_assign, parse_compound, parse_pre_inc};
#[allow(unused_imports)]
pub(crate) use crate::ported::params::getarrvalue;
#[allow(unused_imports)]
#[allow(unused_imports)]
// drift imports removed: apply_subst_modifier, slice_scalar, strip_match_op
#[allow(unused_imports)]
pub(crate) use crate::func_body_fmt::FuncBodyFmt;
#[allow(unused_imports)]
pub(crate) use crate::ported::utils::base64_decode;
#[allow(unused_imports)]
pub(crate) use crate::ported::utils::{ispwd, printprompt4, quotedzputs};
#[allow(unused_imports)]
pub(crate) use crate::ported::hist::bufferwords as bufferwords_z_tuple;

pub(crate) use crate::intercepts::intercept_matches;
/// AOP advice type — before, after, or around.
pub use crate::intercepts::{AdviceKind, Intercept};

/// Result from background compinit thread.
pub use crate::compinit_bg::CompInitBgResult;
use std::io::Write;
use std::sync::LazyLock;


/// State snapshot for plugin delta computation.
pub(crate) use crate::plugin_cache::PluginSnapshot;


/// Cached compiled regexes for hot paths
pub(crate) static REGEX_CACHE: LazyLock<Mutex<std::collections::HashMap<String, regex::Regex>>> =
    LazyLock::new(|| Mutex::new(std::collections::HashMap::with_capacity(64)));

/// Port of `int trap_state;` from `Src/exec.c:134`. Tracks whether
/// a trap handler is currently being processed and, paired with
/// `TRAP_RETURN` below, whether a `return` inside the trap should
/// promote to `TRAP_STATE_FORCE_RETURN` to unwind the trap caller.
///
/// Values: `TRAP_STATE_INACTIVE = 0`, `TRAP_STATE_PRIMED = 1`,
/// `TRAP_STATE_FORCE_RETURN = 2` (see `Src/zsh.h`).
pub static TRAP_STATE: std::sync::atomic::AtomicI32 =                       // c:134 (Src/exec.c)
    std::sync::atomic::AtomicI32::new(0);

/// Port of `int trap_return;` from `Src/exec.c:155`. Carries the
/// pending exit status from inside a trap; sentinel `-2` means
/// "running an EXIT/DEBUG-style trap at the current level"
/// (signals.c:1166). Promoted to the user's `return N` value by
/// `bin_return` when POSIX-trap semantics apply (builtin.c:5852).
pub static TRAP_RETURN: std::sync::atomic::AtomicI32 =                      // c:155 (Src/exec.c)
    std::sync::atomic::AtomicI32::new(0);

/// Port of `int forklevel;` from `Src/exec.c:1052`. Records the
/// `locallevel` at the most recent fork point (set at c:1221:
/// `forklevel = locallevel;` inside `entersubsh()`). Used by:
///   - `signals.c:808` SIGPIPE handler — `!forklevel` distinguishes
///     the top-level shell from a forked subshell.
///   - `exec.c:6146` — `if (locallevel > forklevel)` decides whether
///     a function-defined trap should fire on this subshell exit.
///   - `params.c:3724` — WARNCREATEGLOBAL nest-depth check.
///
/// Initialised to 0 (no fork has occurred yet). Set to `locallevel`
/// at every `entersubsh()` entry per c:1221.
pub static FORKLEVEL: std::sync::atomic::AtomicI32 =                        // c:1052 (Src/exec.c)
    std::sync::atomic::AtomicI32::new(0);

// ───────────────────────────────────────────────────────────────────────────
// fusevm VM bridge (extension; not a port of Src/exec.c) lives in
// src/fusevm_bridge.rs. The bridge re-exports the symbols that the
// rest of the codebase imports as `crate::ported::exec::X`.
// ───────────────────────────────────────────────────────────────────────────
pub use crate::fusevm_bridge::*;
pub(crate) use crate::fusevm_bridge::{ExecutorContext};

/// `ZSH_VERSION` / `ZSH_PATCHLEVEL` / `ZSH_VERSION_DATE` consts
/// generated by `build.rs` from `src/zsh/Config/version.mk`. Use
/// `zsh_version::ZSH_VERSION` etc. at call sites so version bumps
/// pick up automatically.
pub mod zsh_version {
    include!(concat!(env!("OUT_DIR"), "/zsh_version.rs"));
}

/// Convert a here-document into a here-string. Line-by-line port of
/// `gethere()` from `Src/exec.c:4569-4652`. Reads the body from the
/// input stream via `hgetc()` until the terminator line is matched,
/// returning the collected body as a string. `strp` is in/out: on
/// entry the raw terminator (possibly with token markers + leading
/// tabs); on return the munged terminator (after `quotesubst` +
/// `untokenize` and, for `REDIR_HEREDOCDASH`, leading-tab strip).
///
/// Returns `None` on out-of-memory (C `zalloc`/`realloc` failure).
/// Rust's `String` auto-grows so the OOM branch is effectively
/// unreachable, but the return type stays `Option<String>` to mirror
/// the C signature which can return NULL.
///
/// Port of `gethere(char **strp, int typ)` from `Src/exec.c:4573`.
pub fn gethere(strp: &mut String, typ: i32) -> Option<String> {                  // c:4573 (Src/exec.c)
    let mut buf: String;                                                          // c:4575 char *buf
    let mut bsiz: usize;                                                          // c:4576 int bsiz
    let mut qt: i32 = 0;                                                          // c:4576 int qt = 0
    let mut strip: i32 = 0;                                                       // c:4576 int strip = 0
    // c:4577 — char *s, *t, *bptr, c. zshrs uses byte-offsets into
    // `buf` for `t` and tracks `bptr` implicitly as `buf.len()` (the
    // C `bptr++` increment is `buf.push(c)`; `bptr--` is `buf.pop()`).
    // `s` (the loop iterator for the inull-scan) stays local to its
    // for-loop. `c` mirrors the C `char c`.
    let mut t: usize;                                                             // c:4577 char *t
    let mut c: Option<char>;                                                      // c:4577 char c
    let mut str: String = strp.clone();                                           // c:4578 char *str = *strp

    // c:4580-4584 — for (s = str; *s; s++) if (inull(*s)) { qt = 1; break; }
    for s in str.bytes() {
        if crate::ported::ztype_h::inull(s) {                                     // c:4581
            qt = 1;                                                               // c:4582
            break;                                                                // c:4583
        }
    }
    str = crate::ported::subst::quotesubst(&str);                                 // c:4585
    str = crate::ported::lex::untokenize(&str);                                   // c:4586
    if typ == crate::ported::zsh_h::REDIR_HEREDOCDASH {                           // c:4587
        strip = 1;                                                                // c:4588
        // c:4589-4590 — while (*str == '\t') str++;
        while str.starts_with('\t') {
            str.remove(0);
        }
    }
    *strp = str.clone();                                                          // c:4592 *strp = str

    // c:4593 — bptr = buf = zalloc(bsiz = 256);
    bsiz = 256;
    buf = String::with_capacity(bsiz);
    let _ = bsiz; // bsiz is tracked by C for zfree; Rust drops automatically

    // c:4594 — for (;;)
    loop {
        t = buf.len();                                                            // c:4595 t = bptr

        // c:4597-4598 — while ((c = hgetc()) == '\t' && strip) ;
        loop {
            c = crate::ported::lex::hgetc();
            if !(c == Some('\t') && strip != 0) {
                break;
            }
        }

        // c:4599 — for (;;) — inner body-read loop
        loop {
            // c:4600-4613 — buffer-growth realloc dance. Rust's
            // String auto-grows; nothing to do.
            // c:4614 — if (lexstop || c == '\n') break;
            if crate::ported::lex::LEX_LEXSTOP.with(|f| f.get()) || c == Some('\n') || c.is_none() {
                break;
            }
            // c:4616 — if (!qt && c == '\\')
            if qt == 0 && c == Some('\\') {
                buf.push('\\');                                                   // c:4617 *bptr++ = c
                c = crate::ported::lex::hgetc();                                  // c:4618
                if c == Some('\n') {                                              // c:4619
                    buf.pop();                                                    // c:4620 bptr--
                    c = crate::ported::lex::hgetc();                              // c:4621
                    continue;                                                     // c:4622
                }
            }
            if let Some(ch) = c {                                                 // c:4625 *bptr++ = c
                buf.push(ch);
            }
            c = crate::ported::lex::hgetc();                                      // c:4626
        }
        // c:4628 — *bptr = '\0'; (implicit — Rust String tracks len)

        // c:4629-4630 — if (!strcmp(t, str)) break;
        if &buf[t..] == str.as_str() {
            break;
        }
        // c:4631-4634 — if (lexstop) { t = bptr; break; }
        if crate::ported::lex::LEX_LEXSTOP.with(|f| f.get()) {
            t = buf.len();
            break;
        }
        // c:4635 — *bptr++ = '\n';
        buf.push('\n');
    }
    // c:4637 — *t = '\0';
    buf.truncate(t);

    // c:4638-4640 — s = buf; buf = dupstring(buf); zfree(s, bsiz);
    // The C dance frees the realloc'd block and re-allocates via the
    // string-heap allocator. Rust drops the old String when reassigned.
    buf = crate::ported::mem::dupstring(&buf);

    if qt == 0 {                                                                  // c:4641
        // c:4642 — int ef = errflag;
        let ef = errflag.load(Ordering::Relaxed);
        // c:4644 — parsestr(&buf);
        if let Ok(parsed) = crate::ported::lex::parsestr(&buf) {
            buf = parsed;
        }
        // c:4646-4649 — if (!(errflag & ERRFLAG_ERROR)) errflag = ef | (errflag & ERRFLAG_INT);
        if (errflag.load(Ordering::Relaxed) & ERRFLAG_ERROR) == 0 {
            let cur = errflag.load(Ordering::Relaxed);
            errflag.store(ef | (cur & crate::ported::zsh_h::ERRFLAG_INT), Ordering::Relaxed);
        }
    }
    Some(buf)                                                                     // c:4651 return buf
}

/// Free-function wrapper for `getoutput()` from `Src/exec.c:4712`.
/// Runs a command-substitution body in the active executor and
/// returns its captured stdout. The C signature is `LinkList
/// getoutput(char *cmd, int qt)` but every caller in subst.rs
/// joins the list back into a string, so the Rust port collapses
/// the intermediate.
///
/// Uses `with_executor` (panics on missing VM context), not
/// `try_with_executor + unwrap_or_default()`. C `getoutput` calls
/// `execpline` directly — there's no "no shell" code path. The
/// silent-no-op pattern (return empty string when no executor) would
/// mask catastrophic state corruption as "command produced no output",
/// which is the failure mode the `subst.rs:496` warning block flags.
pub fn getoutput(cmd: &str) -> String {                                      // c:4712 (Src/exec.c)
    with_executor(|exec| exec.run_command_substitution(cmd))
}

/// Match an intercept pattern against a command name or full command string.
/// Supports: exact match, glob ("git *", "_*", "*"), or "all".

/// Get or compile a regex, caching the result
pub(crate) fn cached_regex(pattern: &str) -> Option<regex::Regex> {
    let mut cache = REGEX_CACHE.lock();
    if let Some(re) = cache.get(pattern) {
        return Some(re.clone());
    }
    match regex::Regex::new(pattern) {
        Ok(re) => {
            cache.insert(pattern.to_string(), re.clone());
            Some(re)
        }
        Err(_) => None,
    }
}

/// O(1) builtin-name lookup set derived from the canonical
/// `BUILTINS` table (`src/ported/builtin.rs:122`, the 1:1 port of
/// `static struct builtin builtins[]` at `Src/builtin.c:40-137`).
/// Earlier incarnation hardcoded a separate 130-entry list which
/// drifted whenever new builtins landed in the canonical table — and
/// shadowed the `fusevm::shell_builtins::BUILTIN_SET` u16 opcode
/// constant. Renaming to `BUILTIN_NAMES` removes the shadow; the
/// initialiser walks `BUILTINS` so the set stays in sync.
///
/// The hardcoded entries inside `LazyLock::new` below are kept as
/// the union of: (1) names from `BUILTINS` (walked at first access),
/// (2) zshrs daemon-side builtins from `ZSHRS_BUILTIN_NAMES`. Both
/// arms run once at static init.
pub(crate) static BUILTIN_NAMES: LazyLock<HashSet<String>> = LazyLock::new(|| {
    let mut s: HashSet<String> = HashSet::new();
    // Walk the canonical `BUILTINS` table — the 1:1 port of
    // `static struct builtin builtins[]` at `Src/builtin.c:40-137`
    // (ported at `src/ported/builtin.rs:122`). Every name in there is
    // a real zsh builtin; the set stays in sync as new ports land.
    for b in crate::ported::builtin::BUILTINS.iter() {
        s.insert(b.node.nam.clone());
    }
    // Daemon-side (zshrs-specific extensions).
    for &n in crate::daemon::builtins::ZSHRS_BUILTIN_NAMES.iter() {
        s.insert(n.to_string());
    }
    s
});

/// Slice an array per zsh `${arr:offset[:length]}` semantics: the
/// offset is 0-based "skip N elements" (so `${arr:1:2}` returns
/// elements at indices 1,2). Negative offset counts from the end.
/// `length < 0` means "to the end".
pub(crate) fn slice_array_zero_based(arr: &[String], offset: i64, length: i64) -> Vec<String> {
    let n = arr.len() as i64;
    if n == 0 {
        return Vec::new();
    }
    let start = if offset < 0 {
        (n + offset).max(0) as usize
    } else {
        (offset as usize).min(arr.len())
    };
    let take = if length < 0 {
        arr.len().saturating_sub(start)
    } else {
        (length as usize).min(arr.len().saturating_sub(start))
    };
    arr.iter().skip(start).take(take).cloned().collect()
}

/// Same shape but for positional params (`@`/`*`). zsh treats
/// position 0 as `$0` (the script/shell name). For `${@:0}` it
/// includes `$0`; for `${@:1}` it skips `$0` and starts at `$1`.
/// Internally `positional_params[0]` is `$1`, so we prepend `$0`
/// then slice 0-based.
pub(crate) fn slice_positionals(exec: &ShellExecutor, offset: i64, length: i64) -> Vec<String> {
    let pp = exec.pparams();
    let mut all: Vec<String> = Vec::with_capacity(pp.len() + 1);
    all.push(
        exec.scalar("0")
            .unwrap_or_else(|| std::env::args().next().unwrap_or_default()),
    );
    for p in pp {
        all.push(p);
    }
    slice_array_zero_based(&all, offset, length)
}

use crate::exec_jobs::{JobState, JobTable};
use crate::parse::{Redirect, RedirectOp, ShellCommand, ShellWord, VarModifier, ZshParamFlag};
use crate::zwc::ZwcFile;
use indexmap::IndexMap;
use std::collections::HashMap;
use std::env;
use std::fs::{File, OpenOptions};
use std::io;
use std::path::{Path, PathBuf};
use std::process::{Child, Command, Stdio};


// Drift structs moved to their canonical-C-file modules
// (src/ported/zle/computil.rs, modules/{zutil,zpty,zprof,socket}.rs,
// builtins/sched.rs). Re-exported here so existing call-sites that
// reference `crate::ported::exec::<Name>` keep compiling.
pub use crate::bash_complete::{CompSpec, CompMatch, CompGroup, CompState};
pub use crate::ported::modules::zutil::zstyle_entry;
// `ProfileEntry` re-export deleted — was unused outside
// `ShellExecutor::profile_data` (which itself is now removed).
// `ScheduledCommand` (Rust-only) deleted; use `crate::builtins::sched::schedcmd`
// (port of `struct schedcmd` from Src/Builtins/sched.c:43) for live state.
pub use crate::ported::builtin::AutoloadFlags;


/// Cross-VM loop-control signal. When `break`/`continue` is hit inside a body
/// that runs on a sub-VM (e.g. select's body), the inline patches mechanism
/// can't reach the outer loop — set this flag and the outer-loop builtin
/// drains it after each iteration.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
/// Loop control signal from a command body.
/// Mirrors the `LF_*` set Src/loop.c uses to thread
/// `break`/`continue`/`return` flags up through the executor.
pub enum LoopSignal {
    Break,
    Continue,
}

/// Snapshot of subshell-isolated state. Captured at `(` entry, restored at
/// `)` exit. zsh subshell semantics: assignments inside `(…)` don't leak to
/// the outer scope — and that includes `export`. zsh forks a child for the
/// subshell so the child's env::set_var dies with the child; without a fork
/// (zshrs runs subshells in-process for perf), we snapshot+restore the OS
/// env table around the subshell. Otherwise `(export y=v)` would leak `y`
/// to the parent shell, breaking every script that uses a subshell to
/// scope an env override.
/// Snapshot of mutable executor state across a subshell
/// boundary.
/// Port of the `entersubsh()` save/restore Src/exec.c does at
/// line 1084 — captures everything that must be replaced when a
/// `(...)` group fires.
pub struct SubshellSnapshot {
    /// Snapshot of `paramtab` (the C-canonical parameter store) at
    /// subshell entry. Step 1 of the unification mirrors writes to
    /// paramtab, so subshell-scoped assignments now show up there
    /// too — without this snapshot, restoring only `variables` /
    /// `arrays` / `assoc_arrays` leaks the subshell's writes to the
    /// parent via paramtab (e.g. `x=outer; (x=inner); echo $x` returned
    /// `inner` because paramsubst reads through paramtab).
    pub paramtab: HashMap<String, crate::ported::zsh_h::Param>,
    pub paramtab_hashed_storage: HashMap<String, indexmap::IndexMap<String, String>>,
    pub positional_params: Vec<String>,
    pub env_vars: HashMap<String, String>,
    /// Process working directory at subshell entry. `cd` inside the
    /// subshell shouldn't leak to the parent; we restore on End.
    pub cwd: Option<std::path::PathBuf>,
    /// File-creation mask at subshell entry. zsh forks for `(...)` so
    /// `umask` set inside dies with the child; we run subshells in
    /// process so we must restore the mask on End. Otherwise
    /// `umask 022; (umask 077); umask` shows 077 in the parent.
    pub umask: u32,
    /// Parent's traps at subshell entry. zsh's `(trap "echo X" EXIT;
    /// true)` runs the trap when the subshell exits — BEFORE the parent
    /// continues. Without this snapshot, the trap inherited from parent
    /// would fire, OR a trap set inside the subshell would leak to the
    /// parent's process exit. Restored on subshell_end after the
    /// subshell's own EXIT trap (if any) has fired.
    pub traps: HashMap<String, String>,
}

/// Variable attribute record + kind enum — moved to params.rs.


// Pattern helpers moved to src/ported/pattern.rs.
#[allow(unused_imports)]
pub(crate) use crate::ported::pattern::{
    extract_numeric_ranges, numeric_range_contains, numeric_ranges_to_star,
};

// `impl VarAttr` moved to src/ported/params.rs.

/// Top-level shell executor state.
/// Port of the file-static globals + `Estate` chain Src/exec.c
/// uses — `execlist()` (line 1349) drives every list, with
/// `execpline()` (line 1668), `execpline2()` (line 1991),
/// `execsimple()` (line 1290), and the per-`WC_*` `execfuncs[]`
/// table (line 268) feeding off it. The Rust port collapses
/// everything into one `ShellExecutor` so we don't need
/// thread-local globals.
pub struct ShellExecutor {
    /// Mirrors C zsh's file-static `scriptname` (Src/init.c). Used by
    /// PS4's `%N` and the `scriptname:line: …` prefix on error
    /// messages. Inside a function, MUTATES to the function name
    /// (Src/exec.c:5903 `scriptname = dupstring(name)`). Init sets
    /// this in `-c` mode to the binary basename per init.c:479; when
    /// sourcing a file via `source`/`bin_dot`, it becomes the
    /// resolved file path; otherwise it falls back through `$0` →
    /// `$ZSH_ARGZERO`.
    pub scriptname: Option<String>,
    /// Mirrors C zsh's `scriptfilename` global (Src/init.c). Tracks
    /// the FILE BEING READ (vs scriptname which tracks the active
    /// function name during a call). Used by PS4's `%x` and certain
    /// error-message prefixes that want the file location, NOT the
    /// function name.
    ///
    /// At -c-mode init, scriptname == scriptfilename == "zsh"
    /// (Src/init.c:479). When entering a function, ONLY scriptname
    /// updates (exec.c:5903); scriptfilename stays at the outer
    /// file path, so `%x` inside a function still shows the file
    /// the function was called from.
    pub scriptfilename: Option<String>,
    // `expanding_aliases` deleted — was a Rust-only HashSet recursion
    // guard duplicating C's `alias.inuse` field (`Src/zsh.h:1256`).
    // Callers now bump/clear `inuse` on the canonical alias node in
    // `aliastab` (`hashtable.rs:1804`), matching C's lexer behavior.
    /// Set by `break`/`continue` keywords when no enclosing loop in the
    /// current chunk's patch lists. Outer-loop builtins (BUILTIN_RUN_SELECT)
    /// observe + clear this after each body run.
    pub loop_signal: Option<LoopSignal>,
    /// Stack of subshell-state snapshots. Each `(…)` subshell pushes a copy
    /// of variables/arrays/assoc_arrays at entry and pops/restores at exit.
    /// Without this, `(x=inner; …); echo $x` shows `inner` instead of the
    /// outer-scope value.
    pub subshell_snapshots: Vec<SubshellSnapshot>,
    /// Stack of inline-assignment scopes — `X=foo Y=bar cmd` pushes
    /// a frame at the start, the assigns run inside it, and `cmd`
    /// returns into END_INLINE_ENV which restores both shell-vars
    /// and process-env to the pre-frame state. Each frame holds
    /// `(name, prev_var, prev_env)` per assigned name. zsh's
    /// equivalent is the parser-level "addvar" list executed under
    /// `addvars()` (Src/exec.c) right before the command exec.
    pub inline_env_stack: Vec<Vec<(String, Option<String>, Option<String>)>>,
    /// Set by `expand_glob`'s no-match arm when `nomatch` is on (zsh
    /// default) — instructs the simple-command dispatcher to skip
    /// executing the current command, set last_status=1, and continue
    /// to the next command in the script. zsh's bin_simple uses the
    /// errflag global for the same role: error printed, command
    /// suppressed, script continues. Without this we were calling
    /// `process::exit(1)` deep inside expand_glob, killing the whole
    /// shell on any unmatched glob even with multi-statement input.
    /// `Cell` because the no-match site only has a `&self` borrow.
    pub current_command_glob_failed: std::cell::Cell<bool>,
    pub jobs: JobTable,
    pub fpath: Vec<PathBuf>,
    pub zwc_cache: HashMap<PathBuf, ZwcFile>,
    pub history: Option<HistoryEngine>,
    /// Session-relative history line counter. Starts at 0; incremented
    /// when an interactive command is recorded. Used by `%h`/`%!` in
    /// prompt expansion (zsh's "current history line number"), distinct
    /// from the persistent disk history total.
    pub session_histnum: i64,
    pub(crate) process_sub_counter: u32,
    pub traps: HashMap<String, String>,
    // `options` field deleted — dup of canonical `OPTS_LIVE` in
    // `src/ported/options.rs:1112`. Callers route through
    // `opt_state_get`/`opt_state_set`/`opt_state_unset`/`opt_state_snapshot`.
    pub completions: HashMap<String, CompSpec>, // command -> completion spec
    // `dir_stack` field deleted — canonical `DIRSTACK` lives in
    // `modules/parameter.rs:398` (mirror of C `dirstack` global at
    // `Src/builtin.c:1456`). Callers go through that Mutex directly.
    // zsh completion system state
    pub comp_matches: Vec<CompMatch>, // Current completion matches
    pub comp_groups: Vec<CompGroup>,  // Completion groups
    pub comp_state: CompState,        // compstate associative array
    pub zstyles: Vec<zstyle_entry>,         // zstyle configurations
    pub comp_words: Vec<String>,      // words on command line
    pub comp_current: i32,            // current word index (1-based)
    pub comp_prefix: String,          // PREFIX parameter
    pub comp_suffix: String,          // SUFFIX parameter
    pub comp_iprefix: String,         // IPREFIX parameter
    pub comp_isuffix: String,         // ISUFFIX parameter
    // `readonly_vars` deleted — was a never-populated HashSet
    // duplicating the canonical `PM_READONLY` flag check on Param
    // (`zsh_h::PM_READONLY` bit on `Param.node.flags`). Callers go
    // through `is_readonly_param(name)`.
    // `last_subst` deleted — 0 callers. Canonical `hsubl`/`hsubr`
    // globals live in `Src/hist.c` and are ported on demand when
    // `:&` history-modifier replay arrives in zshrs.
    // `sub_flags` deleted — zero real callers; canonical lives in
    // `SUB_FLAGS` thread_local at `src/ported/subst.rs:498` (`sub_flags`
    // global in `Src/subst.c:2169`), accessed via `sub_flags_get` /
    // `sub_flags_set`.
    /// Current function scope depth for `local` tracking.
    pub local_scope_depth: usize,
    /// Last arg of the currently-running command, deferred into `$_`
    /// when the next command dispatches. zsh: `$_` reflects the LAST
    /// command's last arg, so `echo hi; echo $_` prints `hi` (not the
    /// `_` arg of `echo $_` itself). Promoted in `pop_args` and
    /// `host.exec` before the command's args are read.
    pub pending_underscore: Option<String>,
    /// True while expanding inside a double-quoted context. Set by
    /// `BUILTIN_EXPAND_TEXT` mode 1 around `expand_string` calls.
    /// Used by parameter-flag application to suppress array-only flags
    /// (`(o)`/`(O)`/`(n)`/`(i)`/`(M)`/`(u)`) — zsh's behaviour: those
    /// flags only fire in array context.
    pub in_dq_context: u32,
    // `in_paramsubst_nest` deleted — canonical lives in
    // `IN_PARAMSUBST_NEST` thread_local at `subst.rs:464` (mirrors
    // `paramsub_nest` global in `Src/subst.c`). Callers read it
    // directly via `crate::ported::subst::IN_PARAMSUBST_NEST.with(...)`.
    /// True (>0) while expanding the RHS of a scalar assignment.
    /// Direct port of zsh's `PREFORK_SINGLE` bit set by
    /// Src/exec.c::addvars line 2546 (`prefork(vl, isstr ?
    /// (PREFORK_SINGLE|PREFORK_ASSIGN) : PREFORK_ASSIGN, ...)`).
    /// Subst_port's paramsubst reads this via `ssub` and suppresses
    /// `(f)` / `(s:STR:)` / `(0)` / `(z)` split flags per
    /// Src/subst.c:1759 + 3902, so `y="${(f)x}"` preserves x's
    /// original separator (newlines) instead of re-joining with
    /// IFS-first-char (space).
    pub in_scalar_assign: u32,
    // `cmd_stack` deleted — duplicated the canonical `prompt::CMDSTACK`
    // thread_local (`Src/prompt.c:56 unsigned char *cmdstack`).
    // `BUILTIN_CMD_PUSH`/`BUILTIN_CMD_POP` now call `cmdpush`/`cmdpop`
    // on the canonical TLS only; prompt expansion reads it directly.
    /// IDs of history entries explicitly added during this session
    /// via `print -s`. `fc -l` uses this to scope listings to just
    /// the script-added entries (matches zsh's `-c` semantics where
    /// session history is the only thing visible to the script).
    pub session_history_ids: Vec<i64>,
    // `autoload_pending` deleted — dup of canonical shfunctab entries
    // with PM_UNDEFINED flag bit (port of C autoload_func stub at
    // `Src/exec.c:5215`). The -U/-z/-k/-t/-d AutoloadFlags details
    // were never consumed beyond serialization, dropped along with
    // the field.
    // `hook_functions` deleted — Rust-only side-store duplicating zsh's
    // canonical `<hook>_functions` paramtab arrays (the add-zsh-hook
    // idiom). `add_hook` / `delete_hook` now mutate those arrays
    // directly via `setaparam`.
    // `named_dirs` deleted — canonical `nameddirtab` lives in
    // `src/ported/hashnameddir.rs:36` (port of C `nameddirtab` in
    // `Src/hashnameddir.c`). Callers route through that Mutex.
    // bin_sysopen - file descriptor management
    pub open_fds: HashMap<i32, std::fs::File>,
    pub next_fd: i32,
    // sched (Src/Builtins/sched.c) — schedcmds list lives in module
    // statics in the canonical port; nothing to carry on ShellExecutor.
    // zprof — profiling data lives in `crate::zprof` module statics
    // (CALLS/NCALLS/ARCS/NARCS/STACK), matching the C file-statics
    // at zprof.c:66-71. Only the user's "is profiling on?" toggle
    // stays here, set by the `profile` extension builtin.
    pub profiling_enabled: bool,
    // compsys - completion system cache
    pub compsys_cache: Option<CompsysCache>,
    // Background compinit — receiver for async fpath scan result
    pub compinit_pending: Option<(
        std::sync::mpsc::Receiver<CompInitBgResult>,
        std::time::Instant,
    )>,
    // Plugin source cache — stores side effects of source/. in SQLite
    pub plugin_cache: Option<crate::plugin_cache::PluginCache>,
    // cdreplay - deferred compdef calls for zinit turbo mode
    pub deferred_compdefs: Vec<Vec<String>>,
    // `command_hash` deleted — never-populated dup of canonical
    // `cmdnamtab` (`hashtable.rs:1780`, port of `Src/exec.c:5260`
    // findcmd's hash table). Callers route through cmdnamtab.
    // Control flow signals
    pub returning: Option<i32>, // Set by return builtin, cleared after function returns
    pub breaking: i32,          // break level (0 = not breaking, N = break N levels)
    pub continuing: i32,        // continue level
    // New module state — TcpSessions struct dissolved into the
    // thread_local ZTCP_SESSIONS in modules/tcp.rs (matches C's
    // file-static `ztcp_sessions` linked list).
    // `zftp` field deleted — 0 callers. Module-level state lives in
    // `ZFTP_STATE_INNER` (Src/Modules/zftp.c file-statics analogue).
    // `profiler: Profiler` deleted — see comment above.
    // `style_table` field deleted — 0 callers. Canonical `zstyletab`
    // lives in `src/ported/modules/zutil.rs::zstyletab` (LazyLock
    // Mutex matching C's `static HashTable zstyletab` at zutil.c:209).
    // termcap state dissolved per strict-rules audit — no Rust-only
    // Termcap struct; capability_lookup is stateless on $TERM.
    // Watch state — dissolved per PORT_PLAN Phase 2. C
    // (Src/Modules/watch.c:150-156) keeps `wtab`/`lastwatch`/
    // `lastutmpcheck`/`watch` as file-statics; zshrs mirrors them
    // as `thread_local!`s in src/ported/modules/watch.rs.
    // curses (Src/Modules/curses.c) — windows/colour-pairs/init flag
    // now live in module-static OnceLock<Mutex<…>>'s in
    // src/ported/modules/curses.rs (matching C's file-statics
    // `zcurses_windows`, `colorpairs`, `next_pair`).
    // pty_cmds moved to PTYCMDS global static in src/ported/modules/
    // zpty.rs (port of C `static struct ptycmd *ptycmds` file-static).
    // sched: scheduled commands now live in `SCHEDCMDS` static in
    // `src/ported/builtins/sched.rs` (port of `static struct schedcmd
    // *schedcmds` from Src/Builtins/sched.c:52). No state on
    // ShellExecutor.
    /// zsh compatibility mode - use .zcompdump, fpath scanning, etc.
    /// Also serves as the `--zsh` parity-test flag: caches off, daemon
    /// off, plugin_cache replay off so every `source` re-runs the file
    /// fresh per Src/builtin.c:6080-6123 bin_dot semantics.
    pub zsh_compat: bool,
    /// bash compatibility mode (`--bash`). Same parity-mode semantics
    /// as `zsh_compat` (caches/daemon/replay off) plus bash-specific
    /// behavior tweaks where bash 5.x diverges from zsh — e.g.
    /// `BASH_VERSION` / `BASH_REMATCH` exposed, `[[ =~ ]]` populates
    /// match indices the bash way, mapfile/readarray as builtins.
    pub bash_compat: bool,
    /// POSIX sh strict mode — no SQLite, no worker pool, no zsh extensions
    pub posix_mode: bool,
    /// Worker thread pool for background tasks (compinit, process subs, etc.)
    pub worker_pool: std::sync::Arc<crate::worker::WorkerPool>,
    /// AOP intercept table: command/function name → advice chain.
    /// Glob patterns supported (e.g. "git *", "*").
    pub intercepts: Vec<Intercept>,
    /// Async job handles: id → receiver for (status, stdout)
    pub async_jobs: HashMap<u32, crossbeam_channel::Receiver<(i32, String)>>,
    /// Next async job ID
    pub next_async_id: u32,
    /// Defer stack: commands to run on scope exit (LIFO).
    pub defer_stack: Vec<Vec<String>>,
    /// Per-scope saved-fd stacks for `Op::WithRedirectsBegin/End`. Each entry
    /// is a Vec of (fd, saved_dup_fd) pairs taken from `dup(fd)` before the
    /// redirect was applied; `with_redirects_end` `dup2`s them back and closes.
    pub redirect_scope_stack: Vec<Vec<(i32, i32)>>,
    /// Set by `host_apply_redirect` when a redirect target couldn't be
    /// opened (permission denied, no such directory, etc). The next
    /// builtin/command checks this at entry and short-circuits with
    /// status 1 instead of running. Mirrors zsh's "command skip" on
    /// redirect failure.
    pub redirect_failed: bool,
    /// Stdin content set by `Op::HereDoc(idx)` / `Op::HereString` for the next
    /// command/builtin in this VM. Consumed (and cleared) by the next command.
    pub pending_stdin: Option<String>,
    /// Compiled function bodies — name → fusevm::Chunk. Populated by
    /// `BUILTIN_REGISTER_FUNCTION` (from `FunctionDef` lowering) and lazily by
    /// `ZshrsHost::call_function` when only an AST exists in `self.functions`
    /// (autoloaded, sourced, etc.). `Op::CallFunction` dispatches through here.
    pub functions_compiled: HashMap<String, fusevm::Chunk>,
    /// Canonical source text for functions. Populated by autoload paths (the
    /// raw file/cache body), runtime FuncDef compile (the parsed source span),
    /// and `unfunction` removal. Used by introspection (`whence`, `which`,
    /// `typeset -f`) instead of reconstructing from a ShellCommand AST. When a
    /// function is in `functions_compiled` but not here, introspection falls
    /// back to `text::getpermtext(self.functions[name])`.
    pub function_source: HashMap<String, String>,
    /// `first_body_line - 1` per compiled function — matches inner
    /// `ZshCompiler::lineno_offset` / zsh `funcstack->flineno` combined with
    /// relative `$LINENO` for Src/prompt.c:909 `%I`.
    pub function_line_base: HashMap<String, i64>,
    /// `scriptfilename` when `BUILTIN_REGISTER_COMPILED_FN` ran — `%x` inside
    /// a function (prompt.c:931-934) reads `funcstack->filename`.
    pub function_def_file: HashMap<String, Option<String>>,
    /// Innermost-last stack of active compiled-call frames for prompt `%I` / `%x`.
    pub prompt_funcstack: Vec<(String, i64, Option<String>)>,
    /// Scalar→(array, sep) tie table set up by `typeset -T VAR var [SEP]`.
    /// Used by BUILTIN_SET_VAR to split the assigned scalar on `sep` and
    /// mirror it into `array`.
    pub tied_scalar_to_array: HashMap<String, (String, String)>,
    /// Array→(scalar, sep) reverse-tie table. Used by BUILTIN_SET_ARRAY to
    /// join the array elements with `sep` and mirror to the scalar side.
    pub tied_array_to_scalar: HashMap<String, (String, String)>,
    /// ZLE buffer stack — port of `bufstack` (zsh/Src/builtin.c:4567,
    /// `LinkList bufstack`). `print -z` (builtin.c:5039-5045) pushes
    /// joined args onto it; `read -z` and `getln` (builtin.c:6769-6770)
    /// pop the top entry as the input source. zsh treats this as a stack
    /// shared between the buffer/zle subsystem and the read path.
    pub buffer_stack: Vec<String>,
}

impl ShellExecutor {
    /// Set a scalar parameter via the canonical `paramtab`
    /// (`Src/params.c:3350 setsparam`). The single store.
    pub fn set_scalar(&mut self, name: String, value: String) {
        crate::ported::params::setsparam(&name, &value);                     // c:params.c:3350
    }

    /// Read positional parameters from canonical `PPARAMS`
    /// `Mutex<Vec<String>>` (Src/init.c:pparams). The single store.
    pub fn pparams(&self) -> Vec<String> {
        crate::ported::builtin::PPARAMS
            .lock()
            .map(|p| p.clone())
            .unwrap_or_default()
    }

    /// Write positional parameters to canonical `PPARAMS`.
    pub fn set_pparams(&mut self, params: Vec<String>) {
        if let Ok(mut p) = crate::ported::builtin::PPARAMS.lock() {
            *p = params;
        }
    }

    /// Read PM_* type flags from the paramtab Param entry. Used by
    /// SET_VAR / `+=` arms (case-fold, integer-add, readonly guard)
    /// instead of the legacy `exec.var_attrs` HashMap. Returns 0 when
    /// the name isn't in paramtab. Mirrors the C source's direct
    /// `pm->node.flags & PM_INTEGER` checks.
    pub fn param_flags(&self, name: &str) -> i32 {
        crate::ported::params::paramtab().read()
            .ok()
            .and_then(|t| t.get(name).map(|p| p.node.flags))
            .unwrap_or(0)
    }

    /// `typeset -i name` — Param has PM_INTEGER. Reads via
    /// `param_flags`.
    pub fn is_integer_param(&self, name: &str) -> bool {
        (self.param_flags(name) as u32 & crate::ported::zsh_h::PM_INTEGER) != 0
    }

    /// `typeset -F` / `-E` — float.
    pub fn is_float_param(&self, name: &str) -> bool {
        let f = self.param_flags(name) as u32;
        (f & (crate::ported::zsh_h::PM_EFLOAT | crate::ported::zsh_h::PM_FFLOAT)) != 0
    }

    /// `typeset -l` — Param has PM_LOWER.
    pub fn is_lowercase_param(&self, name: &str) -> bool {
        (self.param_flags(name) as u32 & crate::ported::zsh_h::PM_LOWER) != 0
    }

    /// `typeset -u` — Param has PM_UPPER.
    pub fn is_uppercase_param(&self, name: &str) -> bool {
        (self.param_flags(name) as u32 & crate::ported::zsh_h::PM_UPPER) != 0
    }

    /// `readonly` / `typeset -r` — Param has PM_READONLY.
    pub fn is_readonly_param(&self, name: &str) -> bool {
        (self.param_flags(name) as u32 & crate::ported::zsh_h::PM_READONLY) != 0
    }

    /// Most-recent-command exit status. Reads canonical
    /// `builtin::LASTVAL` AtomicI32 (`Src/builtin.c:6443`).
    pub fn last_status(&self) -> i32 {
        crate::ported::builtin::LASTVAL
            .load(std::sync::atomic::Ordering::Relaxed)
    }

    /// Write the most-recent-command exit status. The canonical
    /// store is `builtin::LASTVAL`; this is the single setter.
    /// Used everywhere `$?` / `%?` / errexit / ZERR trap read.
    pub fn set_last_status(&mut self, status: i32) {
        crate::ported::builtin::LASTVAL
            .store(status, std::sync::atomic::Ordering::Relaxed);
    }

    /// Set an indexed array parameter via canonical paramtab
    /// (`setaparam`, `Src/params.c:3595`). The single store.
    pub fn set_array(&mut self, name: String, value: Vec<String>) {
        crate::ported::params::setaparam(&name, value);                      // c:params.c:3595
    }

    /// Set an associative array parameter via canonical
    /// `sethparam` (`Src/params.c:3602`). The single store.
    pub fn set_assoc(&mut self, name: String, value: indexmap::IndexMap<String, String>) {
        let mut flat: Vec<String> = Vec::with_capacity(value.len() * 2);
        for (k, v) in &value {
            flat.push(k.clone());
            flat.push(v.clone());
        }
        crate::ported::params::sethparam(&name, flat);                       // c:params.c:3602
    }

    /// Read a scalar parameter. Mirrors C `getsparam` at
    /// `Src/params.c:3076` — reads through paramtab, falls back to
    /// special-var hooks and env.
    pub fn scalar(&self, name: &str) -> Option<String> {
        crate::ported::params::getsparam(name)
    }

    /// Read an array parameter from canonical paramtab. Mirrors C
    /// `getaparam` at `Src/params.c:3100` — `paramtab->getnode(s)`
    /// then `pm->u.arr.clone()`. Returns an owned `Vec<String>`.
    pub fn array(&self, name: &str) -> Option<Vec<String>> {
        crate::ported::params::paramtab().read()
            .ok()
            .and_then(|t| t.get(name).and_then(|pm| pm.u_arr.clone()))
    }

    /// Read an associative array parameter from canonical
    /// `paramtab_hashed_storage`. Mirrors C `gethparam` at
    /// `Src/params.c:3115` — returns the typed `IndexMap`.
    pub fn assoc(&self, name: &str) -> Option<indexmap::IndexMap<String, String>> {
        crate::ported::params::paramtab_hashed_storage()
            .lock().ok()
            .and_then(|m| m.get(name).cloned())
    }

    /// Test whether a scalar parameter exists in paramtab.
    /// Mirrors the C `paramtab->getnode(name) != NULL` check.
    pub fn has_scalar(&self, name: &str) -> bool {
        crate::ported::params::getsparam(name).is_some()
    }

    /// Test whether an array parameter exists in paramtab.
    pub fn has_array(&self, name: &str) -> bool {
        crate::ported::params::paramtab().read()
            .ok()
            .and_then(|t| t.get(name).map(|pm| pm.u_arr.is_some()))
            .unwrap_or(false)
    }

    /// Test whether an associative array parameter exists. Reads
    /// canonical `paramtab_hashed_storage` (Src/params.c hashed
    /// PM_HASHED slot).
    pub fn has_assoc(&self, name: &str) -> bool {
        crate::ported::params::paramtab_hashed_storage()
            .lock()
            .ok()
            .map(|m| m.contains_key(name))
            .unwrap_or(false)
    }

    /// Unset an associative array parameter from canonical paramtab
    /// + paramtab_hashed_storage. Direct port of `unsetparam_pm`
    /// for a PM_HASHED Param.
    pub fn unset_assoc(&mut self, name: &str) {
        if let Some(tab) = crate::ported::params::paramtab().write().ok().as_deref_mut() {
            tab.remove(name);
        }
        let _ = crate::ported::params::paramtab_hashed_storage()
            .lock().ok().as_deref_mut()
            .map(|m| m.remove(name));
    }

    /// Read a regular (non-global) alias value. Reads canonical
    /// `aliastab` (Src/hashtable.c:1186). Filters out aliases that
    /// have the ALIAS_GLOBAL flag set so the regular-alias slot is
    /// distinct from the global-alias slot, mirroring C's two
    /// separate dispatch paths via `aliasflags` checks.
    pub fn alias(&self, name: &str) -> Option<String> {
        let tab = crate::ported::hashtable::aliastab_lock().read().ok()?;
        let a = tab.get(name)?;
        if (a.node.flags & crate::ported::zsh_h::ALIAS_GLOBAL as i32) != 0 {
            None
        } else {
            Some(a.text.clone())
        }
    }

    /// Read a global alias value (`alias -g`). Reads canonical
    /// `aliastab` and filters to entries with the ALIAS_GLOBAL flag.
    pub fn global_alias(&self, name: &str) -> Option<String> {
        let tab = crate::ported::hashtable::aliastab_lock().read().ok()?;
        let a = tab.get(name)?;
        if (a.node.flags & crate::ported::zsh_h::ALIAS_GLOBAL as i32) != 0 {
            Some(a.text.clone())
        } else {
            None
        }
    }

    /// Read a suffix alias value (`alias -s`). Reads canonical
    /// `sufaliastab` (Src/hashtable.c:1187).
    pub fn suffix_alias(&self, name: &str) -> Option<String> {
        let tab = crate::ported::hashtable::sufaliastab_lock().read().ok()?;
        Some(tab.get(name)?.text.clone())
    }

    /// Set a regular alias. Writes canonical aliastab with
    /// ALIAS_GLOBAL bit cleared.
    pub fn set_alias(&mut self, name: String, value: String) {
        if let Ok(mut tab) = crate::ported::hashtable::aliastab_lock().write() {
            tab.add(crate::ported::hashtable::createaliasnode(&name, &value, 0));
        }
    }

    /// Set a global alias (`alias -g`). Writes canonical aliastab
    /// with ALIAS_GLOBAL bit set.
    pub fn set_global_alias(&mut self, name: String, value: String) {
        if let Ok(mut tab) = crate::ported::hashtable::aliastab_lock().write() {
            tab.add(crate::ported::hashtable::createaliasnode(
                &name, &value, crate::ported::zsh_h::ALIAS_GLOBAL as u32,
            ));
        }
    }

    /// Set a suffix alias (`alias -s ext=cmd`). Writes canonical
    /// sufaliastab.
    pub fn set_suffix_alias(&mut self, name: String, value: String) {
        if let Ok(mut tab) = crate::ported::hashtable::sufaliastab_lock().write() {
            tab.add(crate::ported::hashtable::createaliasnode(&name, &value, 0));
        }
    }

    /// Unset an alias from canonical aliastab (any flag). Mirrors
    /// C's `unalias` lookup.
    pub fn unset_alias(&mut self, name: &str) {
        if let Ok(mut tab) = crate::ported::hashtable::aliastab_lock().write() {
            tab.remove(name);
        }
    }

    /// Unset a suffix alias.
    pub fn unset_suffix_alias(&mut self, name: &str) {
        if let Ok(mut tab) = crate::ported::hashtable::sufaliastab_lock().write() {
            tab.remove(name);
        }
    }

    /// Snapshot the alias map as a sorted `Vec<(name, value)>`,
    /// only entries WITHOUT the ALIAS_GLOBAL flag (regular aliases).
    pub fn alias_entries(&self) -> Vec<(String, String)> {
        if let Ok(tab) = crate::ported::hashtable::aliastab_lock().read() {
            tab.iter_sorted()
                .into_iter()
                .filter(|(_, a)| (a.node.flags
                    & crate::ported::zsh_h::ALIAS_GLOBAL as i32) == 0)
                .map(|(k, a)| (k.clone(), a.text.clone()))
                .collect()
        } else {
            Vec::new()
        }
    }

    /// Snapshot the global-alias entries (ALIAS_GLOBAL flag set).
    pub fn global_alias_entries(&self) -> Vec<(String, String)> {
        if let Ok(tab) = crate::ported::hashtable::aliastab_lock().read() {
            tab.iter_sorted()
                .into_iter()
                .filter(|(_, a)| (a.node.flags
                    & crate::ported::zsh_h::ALIAS_GLOBAL as i32) != 0)
                .map(|(k, a)| (k.clone(), a.text.clone()))
                .collect()
        } else {
            Vec::new()
        }
    }

    /// Snapshot the suffix-alias entries.
    pub fn suffix_alias_entries(&self) -> Vec<(String, String)> {
        if let Ok(tab) = crate::ported::hashtable::sufaliastab_lock().read() {
            tab.iter_sorted()
                .into_iter()
                .map(|(k, a)| (k.clone(), a.text.clone()))
                .collect()
        } else {
            Vec::new()
        }
    }

    /// Unset an array parameter. Direct port of `unsetparam_pm` for
    /// a PM_ARRAY Param. Mirrors are kept for now while the field
    /// transitions.
    pub fn unset_array(&mut self, name: &str) {
        if let Some(tab) = crate::ported::params::paramtab().write().ok().as_deref_mut() {
            tab.remove(name);
        }
    }

    /// Unset a scalar parameter from canonical paramtab. Narrower
    /// than `unset_var` which clears arrays + assocs too. Direct
    /// port of `Src/params.c:unsetparam_pm` for a scalar PM_TYPE.
    pub fn unset_scalar(&mut self, name: &str) {
        if let Some(tab) = crate::ported::params::paramtab().write().ok().as_deref_mut() {
            tab.remove(name);
        }
    }

    /// Unset a parameter from every store. Mirrors the C
    /// `unsetparam_pm` semantics at `Src/params.c:3905`: clear the
    /// paramtab entry + the legacy HashMap caches + (for exported
    /// vars) the env entry. Callers that need to scope the unset to
    /// just one type pass through this single entry so paramtab and
    /// the HashMaps don't drift apart.
    pub(crate) fn unset_var(&mut self, name: &str) {
        if let Some(tab) = crate::ported::params::paramtab().write().ok().as_deref_mut() {
            tab.remove(name);                                                // c:params.c:3900 paramtab removenode
        }
        let _ = crate::ported::params::paramtab_hashed_storage()
            .lock().ok().as_deref_mut()
            .map(|m| m.remove(name));
    }

    /// Single-string substitution via the canonical pipeline. Snapshots
    /// the executor state into a `SubstState`, runs `singsub` from
    /// `Src/subst.c:514`, commits any side-effects (assigns inside
    /// `${var:=default}`, etc.) back to the executor.
    ///
    /// Replaces the bot-invented `expand_string` method that was deleted
    /// in the citation purge (180463e1e7). All call sites that previously
    /// did `exec.singsub(s)` now do `exec.singsub(s)` and route


    pub fn new() -> Self {
        tracing::debug!("ShellExecutor::new() initializing");

        // Validate the inherited $PWD against the real cwd before any
        // builtin reads it as a logical-path base. Direct port of zsh's
        // ispwd() at src/zsh/Src/utils.c:809-829: $PWD is honored only
        // when it (a) is absolute, (b) stat's to the same dev+inode as
        // ".", and (c) contains no `.`/`..` components. Otherwise zsh
        // resets it to getcwd() (init.c:1247-1253).
        //
        // Without this check, a child process that inherits $PWD from
        // a parent run in a different directory (cargo test setting
        // current_dir(/tmp) but leaking PWD=/project/root) sees the
        // stale PWD and `cd .` later snaps the real cwd to wherever
        // PWD points, escaping the parent's sandbox. ztst harnesses
        // hit this and polluted the project root with test artifacts.
        if let Ok(pwd_env) = env::var("PWD") {
            let valid = ispwd(&pwd_env);
            if !valid {
                if let Ok(real) = env::current_dir() {
                    env::set_var("PWD", &real);
                }
            }
        } else if let Ok(real) = env::current_dir() {
            env::set_var("PWD", &real);
        }

        // Initialize fpath from FPATH env var or use defaults
        let fpath = env::var("FPATH")
            .unwrap_or_default()
            .split(':')
            .filter(|s| !s.is_empty())
            .map(PathBuf::from)
            .collect();

        let history = HistoryEngine::new().ok();

        // Initialize standard zsh variables.
        //
        // `ZSH_VERSION` / `ZSH_PATCHLEVEL` come from the vendored zsh
        // source — build.rs parses `src/zsh/Config/version.mk` and
        // emits the constants below. Previously hardcoded `"5.9"` /
        // `"zsh-5.9-0-g73d3173"`; the latter was an invented git-hash
        // literal that didn't correspond to any real commit. The C
        // source sets these at `Src/params.c:972-973` via
        // `setsparam("ZSH_VERSION", ztrdup_metafy(ZSH_VERSION))`.
        let mut variables = HashMap::new();
        variables.insert("ZSH_VERSION".to_string(), zsh_version::ZSH_VERSION.to_string()); // c:params.c:972
        variables.insert("ZSH_PATCHLEVEL".to_string(),
            zsh_version::ZSH_PATCHLEVEL.to_string());                                       // c:params.c:973
        variables.insert("ZSH_NAME".to_string(), "zsh".to_string());
        // $ZSH_ARGZERO mirrors `posixzero` from Src/init.c:271
        // (`argv0 = argzero = posixzero = *argv++`). Src/params.c:971
        // does the actual `setsparam("ZSH_ARGZERO", ztrdup(posixzero))`
        // at the same setup phase Rust handles here. For -c / runscript
        // invocations the bin entrypoint overrides this with the
        // script path (Src/init.c:297).
        variables.insert(
            "ZSH_ARGZERO".to_string(),
            std::env::args().next().unwrap_or_else(|| "zsh".to_string()),
        );
        // ZLE word boundary chars — matches mainline zsh's default.
        variables.insert(
            "WORDCHARS".to_string(),
            "*?_-.[]~=/&;!#$%^(){}<>".to_string(),
        );
        variables.insert(
            "SHLVL".to_string(),
            env::var("SHLVL")
                .map(|v| {
                    v.parse::<i32>()
                        .map(|n| (n + 1).to_string())
                        .unwrap_or_else(|_| "1".to_string())
                })
                .unwrap_or_else(|_| "1".to_string()),
        );
        // POSIX/zsh default IFS is space, tab, newline, NUL. Splitters
        // throughout the codebase fall back to ` \t\n` when IFS is
        // missing; expose the actual default value so user code that
        // inspects $IFS sees what zsh exposes.
        variables.insert("IFS".to_string(), " \t\n\0".to_string());

        // POSIX `getopts` initial state: OPTIND starts at 1, OPTERR
        // at 1 (errors enabled). Without these, scripts that read
        // `$OPTIND` before the first `getopts` call see empty strings
        // (zsh: `1`).
        variables.insert("OPTIND".to_string(), "1".to_string());
        variables.insert("OPTERR".to_string(), "1".to_string());

        // zsh starts with `$_` empty (unlike bash which inherits the
        // OS-env value). The parent process sets `_=/path/to/binary`
        // before exec; zsh wipes that. Initialize to empty so script
        // reads of `$_` before any command runs return empty.
        variables.insert("_".to_string(), String::new());
        // `$histchars` — `Src/params.c:5064 histcharsgetfn` composes
        // bangchar+hatchar+hashchar (defaults `!`, `^`, `#` per
        // `Src/init.c:1100-1102`). Route through the C-port `histcharsgetfn`
        // so the value follows any runtime updates to the trio.
        variables.insert("histchars".to_string(),
            crate::ported::params::histcharsgetfn());                                       // c:params.c:5064

        // c:Src/params.c:858-860 standard non-special param defaults.
        // The full createparamtable() body installs special_paramdef
        // entries (LINENO/PPID/EUID/etc) as PM_READONLY which would
        // block subsequent BUILTIN_SET_LINENO writes; the readonly-
        // special bypass at setsparam isn't ported yet. Inline these
        // three setiparam-equivalent values in the meantime.
        variables.insert("MAILCHECK".to_string(), "60".to_string());                    // c:858
        variables.insert("KEYTIMEOUT".to_string(), "40".to_string());                   // c:859
        variables.insert("LISTMAX".to_string(), "100".to_string());                     // c:860
        // `$WATCHFMT` — `Src/Modules/watch.c:137 DEFAULT_WATCHFMT`.
        // zsh's watch boot_ seeds WATCHFMT to the default when the
        // module loads. zshrs's modules are statically linked but
        // boot_ isn't wired into require_module yet, so seed the
        // default here. `print "$WATCHFMT"` prints the default
        // (diverges from `/bin/zsh -fc` which leaves it unset until
        // an explicit `zmodload zsh/watch`, but matches the
        // post-zmodload state that most plugin code expects).
        variables.insert("WATCHFMT".to_string(),
            crate::ported::modules::watch::DEFAULT_WATCHFMT.to_string());

        // `$FUNCNEST` default. Real zsh defaults to 500 (Src/zsh.h
        // MAXNEST), but zshrs's bytecode-VM recursion eats ~40KB of
        // Rust stack per frame and tops out around 150 on the
        // default 8MB stack. We seed `100` here so plugin probes
        // (`${FUNCNEST:-default}`) get a realistic cap that
        // matches what `call_function` actually enforces. Users
        // who need deeper need to raise FUNCNEST explicitly AND
        // run with a larger stack (RUST_MIN_STACK).
        variables.insert("FUNCNEST".to_string(), "100".to_string());

        // Run setlocale(LC_ALL, "") so nl_langinfo() (used by the
        // `langinfo` module) returns the host's actual locale instead
        // of the C/POSIX default ("US-ASCII"). Direct port of zsh's
        // Src/init.c:1208 setlocale call. unsafe { } around libc is
        // standard for this exact use-case — setlocale is process-
        // global and must run once at startup.
        unsafe {
            libc::setlocale(libc::LC_ALL, c"".as_ptr());
        }

        // c:hashtable.c:1206 createaliastables() — seeds aliastab with
        // the `run-help` / `which-command` defaults. Run once at shell
        // init so the canonical port owns the default-alias set; the
        // Executor's `aliases` HashMap then mirrors aliastab.
        crate::ported::hashtable::createaliastables();
        // Build the initial $path tied array as a local — fans out
        // to paramtab below; no ShellExecutor mirror anymore.
        let mut arrays: HashMap<String, Vec<String>> = HashMap::new();
        let path_dirs: Vec<String> = env::var("PATH")
            .unwrap_or_default()
            .split(':')
            .map(|s| s.to_string())
            .collect();
        arrays.insert("path".to_string(), path_dirs);
        // Seed canonical OPTS_LIVE with defaults if not already
        // populated. `default_options` builds the same name→bool map
        // we previously cloned into `exec.options`.
        if crate::ported::options::opt_state_len() == 0 {
            for (k, v) in Self::default_options() {
                crate::ported::options::opt_state_set(&k, v);
            }
        }
        let mut exec = Self {
            scriptname: None,
            scriptfilename: None,
            loop_signal: None,
            subshell_snapshots: Vec::new(),
            inline_env_stack: Vec::new(),
            current_command_glob_failed: std::cell::Cell::new(false),
            jobs: JobTable::new(),
            fpath,
            zwc_cache: HashMap::new(),
            history,
            session_histnum: 0,
            completions: HashMap::new(),
            process_sub_counter: 0,
            traps: HashMap::new(),
            // zsh completion system
            comp_matches: Vec::new(),
            comp_groups: Vec::new(),
            comp_state: CompState::default(),
            zstyles: Vec::new(),
            comp_words: Vec::new(),
            comp_current: 0,
            comp_prefix: String::new(),
            comp_suffix: String::new(),
            comp_iprefix: String::new(),
            comp_isuffix: String::new(),
            local_scope_depth: 0,
            pending_underscore: None,
            in_dq_context: 0,
            in_scalar_assign: 0,
            session_history_ids: Vec::new(),
            open_fds: HashMap::new(),
            next_fd: 10,
            profiling_enabled: false,
            compsys_cache: {
                let cache_path = compsys::cache::default_cache_path();
                if cache_path.exists() {
                    let db_size = std::fs::metadata(&cache_path).map(|m| m.len()).unwrap_or(0);
                    match CompsysCache::open(&cache_path) {
                        Ok(c) => {
                            tracing::info!(
                                db_bytes = db_size,
                                path = %cache_path.display(),
                                "compsys: sqlite cache opened"
                            );
                            Some(c)
                        }
                        Err(e) => {
                            tracing::warn!(error = %e, "compsys: failed to open cache");
                            None
                        }
                    }
                } else {
                    tracing::debug!("compsys: no cache at {}", cache_path.display());
                    None
                }
            },
            compinit_pending: None, // (receiver, start_time)
            plugin_cache: {
                let pc_path = crate::plugin_cache::default_cache_path();
                if let Some(parent) = pc_path.parent() {
                    let _ = std::fs::create_dir_all(parent);
                }
                match crate::plugin_cache::PluginCache::open(&pc_path) {
                    Ok(pc) => {
                        let (plugins, functions) = pc.stats();
                        tracing::info!(
                            plugins,
                            cached_functions = functions,
                            path = %pc_path.display(),
                            "plugin_cache: sqlite opened"
                        );
                        Some(pc)
                    }
                    Err(e) => {
                        tracing::warn!(error = %e, "plugin_cache: failed to open");
                        None
                    }
                }
            },
            deferred_compdefs: Vec::new(),
            returning: None,
            breaking: 0,
            continuing: 0,
            zsh_compat: false,
            bash_compat: false,
            posix_mode: false,
            worker_pool: {
                let config = crate::config::load();
                let pool_size = crate::config::resolve_pool_size(&config.worker_pool);
                std::sync::Arc::new(crate::worker::WorkerPool::new(pool_size))
            },
            intercepts: Vec::new(),
            async_jobs: HashMap::new(),
            next_async_id: 1,
            defer_stack: Vec::new(),
            redirect_scope_stack: Vec::new(),
            redirect_failed: false,
            pending_stdin: None,
            functions_compiled: HashMap::new(),
            function_source: HashMap::new(),
            function_line_base: HashMap::new(),
            function_def_file: HashMap::new(),
            prompt_funcstack: Vec::new(),
            tied_scalar_to_array: HashMap::new(),
            tied_array_to_scalar: HashMap::new(),
            buffer_stack: Vec::new(),
        };
        // Mirror env-derived path arrays into the `arrays` table so
        // user-level `fpath` / `path` array reads see the inherited
        // entries. zsh: `fpath+=…` should append to the inherited
        // 43-entry array, not replace it. Same for `path` (PATH).
        let fpath_arr: Vec<String> = exec
            .fpath
            .iter()
            .map(|p| p.to_string_lossy().to_string())
            .collect();
        if !fpath_arr.is_empty() {
            exec.set_array("fpath".to_string(), fpath_arr);
        }
        if let Ok(path) = env::var("PATH") {
            let path_arr: Vec<String> = path
                .split(':')
                .filter(|s| !s.is_empty())
                .map(String::from)
                .collect();
            if !path_arr.is_empty() {
                exec.set_array("path".to_string(), path_arr);
            }
        }
        // Register the standard tied path-family pairs so `path+=` /
        // `fpath+=` / etc. mirror through the array→scalar sync hook
        // in BUILTIN_APPEND_ARRAY (and the SET_ARRAY tied path).
        // Direct port of the implicit ties that zsh wires up at
        // startup for PATH/path, FPATH/fpath, etc. Source-of-truth
        // for the pairs is Src/init.c's `setupvals()` PM_TIED entries.
        for (scalar, arr) in [
            ("PATH", "path"),
            ("FPATH", "fpath"),
            ("MANPATH", "manpath"),
            ("CDPATH", "cdpath"),
            ("MODULE_PATH", "module_path"),
        ] {
            exec.tied_array_to_scalar
                .insert(arr.to_string(), (scalar.to_string(), ":".to_string()));
            exec.tied_scalar_to_array
                .insert(scalar.to_string(), (arr.to_string(), ":".to_string()));
        }

        // Mirror every constructor-time `variables` / `arrays` /
        // `assoc_arrays` seed into paramtab so the C-port readers see
        // the same initial state. C does this implicitly because its
        // single `paramtab` is populated by `setupvals()` /
        // `createparam()` calls at init (Src/init.c:1014-1300). The
        // Rust port builds local HashMaps first and then constructs
        // self; this loop fans the contents out to paramtab in one
        // pass at the end of new().
        for (k, v) in &variables {
            crate::ported::params::setsparam(k, v);                          // c:params.c:3350
        }
        for (k, v) in &arrays {
            crate::ported::params::setaparam(k, v.clone());                  // c:params.c:3595
        }
        // Assocs: there are no pre-seeded entries (terminfo / termcap
        // resolve lazily via magic_assoc_lookup) so no mirror loop.
        exec
    }

    // enter_posix_mode / enter_ksh_mode moved to src/ported/options.rs
    // (canonical C source: Src/options.c:533 emulate()).

    // host_apply_redirect / host_redirect_scope_begin / host_redirect_scope_end /
    // host_set_pending_stdin / host_exec_external moved to src/fusevm_bridge.rs
    // (extension; not a port of Src/exec.c).

    /// Add a directory to fpath
    pub fn add_fpath(&mut self, path: PathBuf) {
        if !self.fpath.contains(&path) {
            self.fpath.insert(0, path);
        }
    }

    /// Tab expansion — direct port of `zexpandtabs(const char *s, int len, int width, int startpos, FILE *fout, int all)` in zsh/Src/utils.c:5973.
    /// Moved to `crate::ported::utils::zexpandtabs`; re-exported below.

    /// Execute a script file with bytecode caching — skips lex+parse+compile on cache hit.
    /// Bytecode is stored in rkyv keyed by (path, mtime).
    pub fn execute_script_file(&mut self, file_path: &str) -> Result<i32, String> {

        let path = Path::new(file_path);
        let abs_path = path
            .canonicalize()
            .unwrap_or_else(|_| path.to_path_buf())
            .to_string_lossy()
            .to_string();

        // Try bytecode cache first — rkyv shard at ~/.zshrs/scripts.rkyv.
        // The cache validates path + mtime + zshrs binary mtime; on any miss
        // we fall through to lex/parse/compile.
        if let Some(bc_blob) = crate::script_cache::try_load_bytes(path) {
            if let Ok(chunk) = bincode::deserialize::<fusevm::Chunk>(&bc_blob) {
                if !chunk.ops.is_empty() {
                    tracing::trace!(
                        path = %abs_path,
                        ops = chunk.ops.len(),
                        "execute_script_file: bytecode cache hit"
                    );
                    crate::fusevm_disasm::maybe_print_stdout(
                        &format!("execute_script_file:cache:{abs_path}"),
                        &chunk,
                    );
                    let mut vm = fusevm::VM::new(chunk);
                    register_builtins(&mut vm);
                    let _ctx = ExecutorContext::enter(self);
                    match vm.run() {
                        fusevm::VMResult::Ok(_) | fusevm::VMResult::Halted => {
                            self.set_last_status(vm.last_status);
                        }
                        fusevm::VMResult::Error(e) => {
                            return Err(format!("VM error: {}", e));
                        }
                    }
                    return Ok(self.last_status());
                }
            }
        }

        // Cache miss — read, parse, compile, execute, then cache.
        // No history expansion: zsh fires `!` history sub only on
        // interactive input (the REPL line). Sourced files are
        // verbatim — `(( !${#ARR} ))` (logical-not) must NOT
        // become `(( <last-arg-of-prev-cmd>{#ARR} ))`. Direct port
        // of Src/init.c source() which calls `lex_init_buf` /
        // `loop()` without engaging the history layer.
        let content =
            std::fs::read_to_string(file_path).map_err(|e| format!("{}: {}", file_path, e))?;
        // Save & clear errflag around the parse so we can detect a
        // fresh syntax error vs an inherited one. Direct port of
        // Src/init.c source()'s `errflag &= ~ERRFLAG_ERROR;` before
        // `parse_event(ENDINPUT)` and the post-parse errflag check.
        let saved_errflag = errflag.load(Ordering::Relaxed);
        errflag.fetch_and(!ERRFLAG_ERROR, Ordering::Relaxed);
        crate::ported::parse::parse_init(&content);
        let program = crate::ported::parse::parse();
        let parse_failed = (errflag.load(Ordering::Relaxed) & ERRFLAG_ERROR) != 0;
        errflag.store(saved_errflag, Ordering::Relaxed);
        if parse_failed {
            return Err("parse error".to_string());
        }

        let compiler = crate::compile_zsh::ZshCompiler::new();
        let chunk = compiler.compile(&program);

        // Cache the bytecode for next time. Best-effort — failures don't
        // block execution since the chunk is already in hand.
        if let Ok(blob) = bincode::serialize(&chunk) {
            let _ = crate::script_cache::try_save_bytes(path, &blob);
            tracing::trace!(
                path = %abs_path,
                bytes = blob.len(),
                "execute_script_file: bytecode cached"
            );
        }

        // Execute
        if !chunk.ops.is_empty() {
            crate::fusevm_disasm::maybe_print_stdout(
                &format!("execute_script_file:compile:{abs_path}"),
                &chunk,
            );
            let mut vm = fusevm::VM::new(chunk);
            register_builtins(&mut vm);
            let _ctx = ExecutorContext::enter(self);
            match vm.run() {
                fusevm::VMResult::Ok(_) | fusevm::VMResult::Halted => {
                    self.set_last_status(vm.last_status);
                }
                fusevm::VMResult::Error(e) => {
                    return Err(format!("VM error: {}", e));
                }
            }
        }

        Ok(self.last_status())
    }

    /// P9d: wordcode-consumer entry. Direct port of zsh's `execlist`
    /// from `Src/exec.c:1551-1671` — walks the wordcode buffer that
    /// P9c's `par_event_wordcode` emitted into `ECBUF`, dispatching on
    /// `WC_KIND` (wc_code) for each entry.
    ///
    /// Minimal implementation: walks ECBUF, dispatches WC_END to a
    /// no-op return-0 path. The full WC_LIST/WC_SUBLIST/WC_PIPE/WC_CMD/
    /// WC_REDIR/WC_SIMPLE/... dispatch tree (Src/exec.c ~30k lines
    /// total) is the multi-week rewrite called out in PORT_PLAN.md.
    /// This stub establishes the entry point and proves the consumer
    /// can walk a buffer P9c emitted into.
    pub fn exec_wordcode(&mut self) -> i32 {
        let buf = ECBUF.with_borrow(|b| b.clone());
        let (status, _next) = self.exec_list_wordcode(&buf, 0);
        self.set_last_status(status);
        status
    }

    /// P9d stub: direct port of `execlist(Estate state, int dont_change_job,
    /// int exiting)` from `Src/exec.c:1551-1671`. Walks WC_LIST entries,
    /// dispatches each sublist payload to exec_pline_wordcode. Real
    /// implementation handles fork/wait + signal-trap dispatch.
    /// Returns (last_status, pc_after_walk).
    pub fn exec_list_wordcode(&mut self, buf: &[u32], mut pc: usize) -> (i32, usize) {
        let mut last_status: i32 = 0;
        while pc < buf.len() {
            let code = wc_code(buf[pc]);
            if code == WC_END {
                pc += 1;
                break;
            }
            if code != WC_LIST {
                pc += 1;
                continue;
            }
            let header = buf[pc];
            let skip = (wc_data(header)
                >> crate::ported::zsh_h::WC_LIST_FREE) as usize;
            pc += 1;
            let (s, _) = self.exec_sublist_wordcode(buf, pc);
            last_status = s;
            pc += skip;
        }
        (last_status, pc)
    }

    /// P9d stub: direct port of `execsublist` from
    /// `Src/exec.c:1672-1810`. Walks WC_SUBLIST + pipeline payload.
    pub fn exec_sublist_wordcode(&mut self, buf: &[u32], mut pc: usize) -> (i32, usize) {
        let mut last_status: i32 = 0;
        if pc < buf.len() && wc_code(buf[pc]) == WC_SUBLIST {
            let header = buf[pc];
            let skip = (wc_data(header) >> 7) as usize;
            pc += 1;
            let (s, _) = self.exec_pline_wordcode(buf, pc);
            last_status = s;
            pc += skip;
        }
        (last_status, pc)
    }

    /// P9d stub: direct port of `execpline` from
    /// `Src/exec.c:1812-1980`. Walks WC_PIPE chain + cmd payloads.
    pub fn exec_pline_wordcode(&mut self, buf: &[u32], mut pc: usize) -> (i32, usize) {
        let mut last_status: i32 = 0;
        if pc < buf.len() && wc_code(buf[pc]) == WC_PIPE {
            let header = buf[pc];
            let skip = ((wc_data(header) >> 1) & 0xffff) as usize;
            pc += 1;
            let (s, _) = self.exec_cmd_wordcode(buf, pc);
            last_status = s;
            pc += skip;
        }
        (last_status, pc)
    }

    /// P9d: direct port of `execcmd_exec` / `execcmd_analyze` from
    /// `Src/exec.c:2700-3700`. Reads the cmd header (WC_SIMPLE /
    /// WC_SUBSH / WC_FOR / WC_CASE / ...) and dispatches accordingly.
    pub fn exec_cmd_wordcode(&mut self, buf: &[u32], pc: usize) -> (i32, usize) {
        if pc >= buf.len() {
            return (0, pc);
        }
        match wc_code(buf[pc]) {
            WC_SIMPLE => self.exec_simple_wordcode(buf, pc),
            WC_SUBSH => self.exec_subsh_wordcode(buf, pc),
            WC_CURSH => self.exec_cursh_wordcode(buf, pc),
            WC_FOR => self.exec_for_wordcode(buf, pc),
            WC_SELECT => self.exec_select_wordcode(buf, pc),
            WC_CASE => self.exec_case_wordcode(buf, pc),
            WC_IF => self.exec_if_wordcode(buf, pc),
            WC_WHILE => self.exec_while_wordcode(buf, pc),
            WC_REPEAT => self.exec_repeat_wordcode(buf, pc),
            WC_FUNCDEF => self.exec_funcdef_wordcode(buf, pc),
            WC_TIMED => self.exec_timed_wordcode(buf, pc),
            WC_COND => self.exec_cond_wordcode(buf, pc),
            WC_ARITH => self.exec_arith_wordcode(buf, pc),
            WC_TRY => self.exec_try_wordcode(buf, pc),
            _ => (0, pc + 1),
        }
    }

    /// P9d: direct port of `execfor(Estate state, int do_exec)` from `Src/exec.c:1232-1350`.
    /// Reads WC_FOR header via WC_FOR_TYPE/WC_FOR_SKIP, dispatches on
    /// type (PPARAM / LIST / COND), iterates body via recursive
    /// exec_list_wordcode calls.
    pub fn exec_for_wordcode(&mut self, buf: &[u32], pc: usize) -> (i32, usize) {
        if pc >= buf.len() {
            return (0, pc);
        }
        let header = buf[pc];
        let _type_bits = WC_FOR_TYPE(header);
        let skip = WC_FOR_SKIP(header) as usize;
        let _ = WC_FOR_LIST;
        // exec.c:1245+ — read var name via ecgetstr, iterate words,
        // exec body. Full implementation needs the var-binding +
        // iteration loop; this stub advances past the form.
        let mut last_status: i32 = 0;
        let end_pc = pc + 1 + skip;
        // Walk inner body (after header + var-name slot) once as a
        // shape-correct placeholder.
        let body_pc = pc + 2;
        if body_pc < end_pc {
            let (s, _) = self.exec_list_wordcode(buf, body_pc);
            last_status = s;
        }
        (last_status, end_pc)
    }
    /// P9d: `execselect` shape — same as exec_for but with `select`
    /// REPL prompt at each iteration. Src/exec.c:1352-1490.
    pub fn exec_select_wordcode(&mut self, buf: &[u32], pc: usize) -> (i32, usize) {
        self.exec_for_wordcode(buf, pc)
    }
    /// P9d: direct port of `execcase(Estate state, int do_exec)` from `Src/exec.c:1492-1550`.
    /// Reads WC_CASE_TYPE + WC_CASE_SKIP, walks pattern arms.
    pub fn exec_case_wordcode(&mut self, buf: &[u32], pc: usize) -> (i32, usize) {
        if pc >= buf.len() {
            return (0, pc);
        }
        let header = buf[pc];
        let _type_bits = WC_CASE_TYPE(header);
        let skip = WC_CASE_SKIP(header) as usize;
        // Full implementation: pattern-match word against each arm's
        // patterns, exec the first matching arm's body. Stub walks the
        // body once as a placeholder.
        let mut last_status: i32 = 0;
        let end_pc = pc + 1 + skip;
        let body_pc = pc + 1;
        if body_pc < end_pc {
            let (s, _) = self.exec_list_wordcode(buf, body_pc);
            last_status = s;
        }
        (last_status, end_pc)
    }
    /// P9d: full port of `execif(Estate state, int do_exec)` from `Src/loop.c:299-340`.
    ///
    /// C body walks the if/elif/else chain. Each cond is an inner
    /// WC_IF header with WC_IF_TYPE distinguishing IF / ELIF / ELSE.
    /// Returns lastval = status of the run branch, or 0 if no branch
    /// matched.
    pub fn exec_if_wordcode(&mut self, buf: &[u32], pc: usize) -> (i32, usize) {
        if pc >= buf.len() {
            return (0, pc);
        }
        let header = buf[pc];
        let skip = WC_IF_SKIP(header) as usize;
        let end_pc = pc + 1 + skip;
        let mut cur = pc + 1;
        let mut run: i32 = 0; // 0=no branch, 1=if/elif body, 2=else body
        let mut s = 0; // 0=in if/elif chain, 1=elif seen at least once
        let mut last_status: i32 = 0;
        // loop.c:307-326 — walk the chain.
        while cur < end_pc {
            if cur >= buf.len() {
                break;
            }
            let code = buf[cur];
            cur += 1;
            if wc_code(code) != WC_IF {
                // Past the IF header chain — must be the body of a
                // previously-selected branch we should run.
                run = 1;
                cur -= 1;
                break;
            }
            // WC_IF_TYPE == ELSE (2) — unconditional else body.
            if WC_IF_TYPE(code) == 2 {
                run = 2;
                break;
            }
            let next = cur + WC_IF_SKIP(code) as usize;
            let (cond_status, after_cond) = self.exec_list_wordcode(buf, cur);
            last_status = cond_status;
            if cond_status == 0 {
                run = 1;
                cur = after_cond;
                break;
            }
            if RETFLAG.load(Ordering::SeqCst) != 0 {
                break;
            }
            s = 1;
            cur = next;
        }
        let _ = s;
        // loop.c:328-336 — run the selected branch body.
        if run != 0 && cur < end_pc {
            let (body_status, _) = self.exec_list_wordcode(buf, cur);
            last_status = body_status;
        } else if RETFLAG.load(Ordering::SeqCst) == 0
            && (errflag.load(Ordering::Relaxed) & ERRFLAG_ERROR) == 0
        {
            last_status = 0;
        }
        (last_status, end_pc)
    }
    /// P9d: full port of `execwhile(Estate state, UNUSED(int do_exec))` from `Src/loop.c:432-498`.
    ///
    /// Loops {exec cond; check status XOR isuntil; exec body; check
    /// breaks/contflag/retflag/errflag} until termination.
    pub fn exec_while_wordcode(&mut self, buf: &[u32], pc: usize) -> (i32, usize) {
        if pc >= buf.len() {
            return (0, pc);
        }
        let header = buf[pc];
        // loop.c:438 — `isuntil = (WC_WHILE_TYPE(code) == WC_WHILE_UNTIL)`.
        // WC_WHILE_UNTIL = 2 per zsh.h:1015.
        let isuntil = WC_WHILE_TYPE(header) == 2;
        let skip = WC_WHILE_SKIP(header) as usize;
        let end_pc = pc + 1 + skip;
        let loop_pc = pc + 1;
        // loop.c:443-446 — pushheap; cmdpush; loops++.
        LOOPS.fetch_add(1, Ordering::SeqCst);
        let mut last_status: i32 = 0;
        let mut oldval: i32 = 0;
        // Safety cap to prevent runaway infinite loops in stubs — real
        // C loops forever if conditions hold.
        let mut iters = 0u64;
        const ITER_CAP: u64 = 1_000_000;
        loop {
            iters += 1;
            if iters > ITER_CAP {
                break;
            }
            // loop.c:467 — exec cond (first inner list).
            let (cond_status, after_cond) = self.exec_list_wordcode(buf, loop_pc);
            last_status = cond_status;
            // loop.c:473 — `if (!((lastval == 0) ^ isuntil)) break;`
            let cond_passed = (cond_status == 0) ^ isuntil;
            if !cond_passed {
                if BREAKS.load(Ordering::SeqCst) > 0 {
                    BREAKS.fetch_sub(1, Ordering::SeqCst);
                }
                if RETFLAG.load(Ordering::SeqCst) == 0 {
                    last_status = oldval;
                }
                break;
            }
            // loop.c:481 — retflag bail.
            if RETFLAG.load(Ordering::SeqCst) != 0 {
                if BREAKS.load(Ordering::SeqCst) > 0 {
                    BREAKS.fetch_sub(1, Ordering::SeqCst);
                }
                break;
            }
            // loop.c:489 — exec body.
            let (body_status, _) = self.exec_list_wordcode(buf, after_cond);
            last_status = body_status;
            // loop.c:493-497 — breaks/continue handling.
            if BREAKS.load(Ordering::SeqCst) > 0 {
                let prev = BREAKS.fetch_sub(1, Ordering::SeqCst);
                if prev - 1 > 0 || CONTFLAG.load(Ordering::SeqCst) == 0 {
                    break;
                }
                CONTFLAG.store(0, Ordering::SeqCst);
            }
            // loop.c:498-501 — errflag bail.
            if (errflag.load(Ordering::Relaxed) & ERRFLAG_ERROR) != 0 {
                last_status = 1;
                break;
            }
            // loop.c:502 — retflag bail.
            if RETFLAG.load(Ordering::SeqCst) != 0 {
                break;
            }
            oldval = last_status;
        }
        LOOPS.fetch_sub(1, Ordering::SeqCst);
        (last_status, end_pc)
    }
    /// P9d: full port of `execrepeat(Estate state, UNUSED(int do_exec))` from `Src/loop.c:499-552`.
    ///
    /// C body:
    ///   end = state->pc + WC_REPEAT_SKIP(code);
    ///   tmp = ecgetstr(state, EC_DUPTOK, &htok);
    ///   if (htok) { singsub(&tmp); untokenize(tmp); }
    ///   count = mathevali(tmp);
    ///   loops++;
    ///   loop = state->pc;
    ///   while (count-- > 0) {
    ///     state->pc = loop;
    ///     execlist(state, 1, 0);
    ///     if (breaks) { breaks--; if (breaks || !contflag) break; contflag = 0; }
    ///     if (errflag) { lastval = 1; break; }
    ///     if (retflag) break;
    ///   }
    ///   loops--;
    pub fn exec_repeat_wordcode(&mut self, buf: &[u32], pc: usize) -> (i32, usize) {
        if pc >= buf.len() {
            return (0, pc);
        }
        let header = buf[pc];
        let skip = WC_REPEAT_SKIP(header) as usize;
        let end_pc = pc + 1 + skip;
        // loop.c:511 — `tmp = ecgetstr(state, EC_DUPTOK, &htok);`
        let (count_expr_raw, after_count) = ecgetstr_wordcode(buf, pc + 1);
        // loop.c:512-515 — singsub + untokenize on tokenized count.
        let count_expr_sub = singsub(&count_expr_raw);
        let count_expr = crate::ported::lex::untokenize(&count_expr_sub);
        // loop.c:516 — `count = mathevali(tmp);`
        let count_val = mathevali(&count_expr).unwrap_or(0);
        if (errflag.load(Ordering::Relaxed) & ERRFLAG_ERROR) != 0 {
            return (1, end_pc);
        }
        let mut last_status: i32 = 0; // loop.c:519 — `lastval = 0` for zero count.
        // loop.c:520-522 — `pushheap(); cmdpush(CS_REPEAT); loops++;`
        LOOPS.fetch_add(1, Ordering::SeqCst);
        let loop_body_pc = after_count;
        // loop.c:523-545 — main iteration.
        let mut remaining = count_val;
        while remaining > 0 {
            remaining -= 1;
            let (s, _) = self.exec_list_wordcode(buf, loop_body_pc);
            last_status = s;
            // loop.c:528-533 — breaks/continue handling.
            if BREAKS.load(Ordering::SeqCst) > 0 {
                let prev = BREAKS.fetch_sub(1, Ordering::SeqCst);
                if prev - 1 > 0 || CONTFLAG.load(Ordering::SeqCst) == 0 {
                    break;
                }
                CONTFLAG.store(0, Ordering::SeqCst);
            }
            // loop.c:534-537 — errflag bail.
            if (errflag.load(Ordering::Relaxed) & ERRFLAG_ERROR) != 0 {
                last_status = 1;
                break;
            }
            // loop.c:538 — retflag bail (function return).
            if RETFLAG.load(Ordering::SeqCst) != 0 {
                break;
            }
        }
        // loop.c:546-549 — `cmdpop(); popheap(); loops--;`
        LOOPS.fetch_sub(1, Ordering::SeqCst);
        (last_status, end_pc)
    }
    /// P9d stub: `execfuncdef`.
    pub fn exec_funcdef_wordcode(&mut self, buf: &[u32], pc: usize) -> (i32, usize) {
        self.skip_form(buf, pc)
    }
    /// P9d stub: `execsubsh` for `(...)` subshell.
    pub fn exec_subsh_wordcode(&mut self, buf: &[u32], pc: usize) -> (i32, usize) {
        self.skip_form(buf, pc)
    }
    /// P9d stub: `execcursh` for `{...}` brace group.
    pub fn exec_cursh_wordcode(&mut self, buf: &[u32], pc: usize) -> (i32, usize) {
        self.skip_form(buf, pc)
    }
    /// P9d stub: `exectimed` for `time pipeline`.
    pub fn exec_timed_wordcode(&mut self, buf: &[u32], pc: usize) -> (i32, usize) {
        self.skip_form(buf, pc)
    }
    /// P9d stub: `execcond` for `[[ ... ]]`.
    pub fn exec_cond_wordcode(&mut self, buf: &[u32], pc: usize) -> (i32, usize) {
        self.skip_form(buf, pc)
    }
    /// P9d stub: `execarith` for `(( ... ))`.
    pub fn exec_arith_wordcode(&mut self, buf: &[u32], pc: usize) -> (i32, usize) {
        self.skip_form(buf, pc)
    }
    /// P9d stub: `exectry` for `{ try } always { finally }`.
    pub fn exec_try_wordcode(&mut self, buf: &[u32], pc: usize) -> (i32, usize) {
        self.skip_form(buf, pc)
    }

    /// Shared helper for WC_* form dispatch stubs: read the header's
    /// `skip` field (data >> WC_CODEBITS) and advance pc past the
    /// payload. Each real production-specific exec_* will replace its
    /// call to this with the form-specific logic.
    fn skip_form(&mut self, buf: &[u32], pc: usize) -> (i32, usize) {
        if pc >= buf.len() {
            return (0, pc);
        }
        let skip = wc_data(buf[pc]) as usize;
        (0, pc + 1 + skip)
    }

    /// P9d: direct port of `execsimple(Estate state)` from `Src/exec.c:3702-4100`.
    /// Walks WC_SIMPLE header + word slots, decodes the interned
    /// strings via `ecgetstr`, builds argv, invokes the command.
    /// Real implementation handles assignments + redirections inline
    /// from the same wordcode; this minimal version pulls just words.
    pub fn exec_simple_wordcode(&mut self, buf: &[u32], mut pc: usize) -> (i32, usize) {
        let mut last_status: i32 = 0;
        if pc < buf.len() && wc_code(buf[pc]) == WC_SIMPLE {
            let header = buf[pc];
            let nwords = wc_data(header) as usize;
            pc += 1;
            // Decode the interned strings into an argv vector.
            let mut argv: Vec<String> = Vec::with_capacity(nwords);
            for _ in 0..nwords {
                let (word, next) = ecgetstr(buf, pc);
                argv.push(word);
                pc = next;
            }
            // Invoke via the existing command-execution path. argv[0]
            // is the command name; remainder are arguments. Real exec
            // (Src/exec.c:3850 execcmd_analyze) would resolve builtin /
            // function / external + fork/exec; we delegate to the
            // existing AST-based simple-cmd executor's argv hook.
            if !argv.is_empty() {
                last_status = self.invoke_argv_wordcode(&argv);
            }
        }
        (last_status, pc)
    }

    /// Minimal command invoker for wordcode-driven simple commands.
    /// Bridges the wordcode-side argv into the existing AST-side
    /// simple-cmd dispatch by constructing a single-Simple ZshProgram
    /// and running it through `execute_script_zsh_pipeline`. Real exec
    /// (P9d full) bypasses the AST and dispatches builtin/function/
    /// external directly from the wordcode — but the AST path
    /// already does this correctly today, so until the full
    /// builtin/function/external dispatch is ported into the wordcode
    /// consumer, this bridge keeps actual execution working.
    fn invoke_argv_wordcode(&mut self, argv: &[String]) -> i32 {
        let script = argv
            .iter()
            .map(|s| {
                // Minimal shell-escape: wrap in single quotes if
                // the arg contains whitespace or special chars.
                if s.chars().any(|c| c.is_whitespace() || "\"'`$\\|;&<>(){}[]*?~".contains(c)) {
                    format!("'{}'", s.replace('\'', "'\\''"))
                } else {
                    s.clone()
                }
            })
            .collect::<Vec<_>>()
            .join(" ");
        self.execute_script_zsh_pipeline(&script).unwrap_or(1)
    }

    /// Execute via the lex+parse free fns + ZshCompiler pipeline.
    /// This is the only execution path; `execute_script` delegates here.
    pub fn execute_script_zsh_pipeline(&mut self, script: &str) -> Result<i32, String> {
        // Skip history expansion for non-interactive script execution
        // (`zsh -c '…'`, internal eval, sourced files). zsh's `!`
        // history sub only fires on the REPL command line, never on
        // a pre-parsed script body. The interactive REPL has its
        // own dedicated path that calls expand_history before
        // dispatching here.
        // Save & clear errflag around the parse so a fresh syntax
        // error is distinguishable from one already in flight. Mirrors
        // Src/init.c loop()'s pre-parse `errflag &= ~ERRFLAG_ERROR;`.
        let saved_errflag = errflag.load(Ordering::Relaxed);
        errflag.fetch_and(!ERRFLAG_ERROR, Ordering::Relaxed);
        crate::ported::parse::parse_init(script);
        let program = crate::ported::parse::parse();
        let parse_failed = (errflag.load(Ordering::Relaxed) & ERRFLAG_ERROR) != 0;
        errflag.store(saved_errflag, Ordering::Relaxed);
        if parse_failed {
            return Err("parse error".to_string());
        }

        let compiler = crate::compile_zsh::ZshCompiler::new();
        let chunk = compiler.compile(&program);

        if chunk.ops.is_empty() {
            return Ok(self.last_status());
        }

        crate::fusevm_disasm::maybe_print_stdout("execute_script_zsh_pipeline", &chunk);
        let mut vm = fusevm::VM::new(chunk);
        register_builtins(&mut vm);
        {
            let _ctx = ExecutorContext::enter(self);
            match vm.run() {
                fusevm::VMResult::Ok(_) | fusevm::VMResult::Halted => {
                    self.set_last_status(vm.last_status);
                }
                fusevm::VMResult::Error(e) => return Err(format!("VM error: {}", e)),
            }
        }

        // Fire EXIT trap if set. Same logic as execute_script's old path:
        // remove first to prevent infinite recursion, then run.
        if let Some(action) = self.traps.remove("EXIT") {
            tracing::debug!("firing EXIT trap (new pipeline)");
            let _ = self.execute_script_zsh_pipeline(&action);
        }

        Ok(self.last_status())
    }

    #[tracing::instrument(skip(self, script), fields(len = script.len()))]
    pub fn execute_script(&mut self, script: &str) -> Result<i32, String> {
        // lex+parse free fns + ZshCompiler is the only execution path.
        self.execute_script_zsh_pipeline(script)
    }

    /// Whether `name` is a known function. Checks the compiled-functions
    /// table and the autoload-pending registry — `autoload foo` should
    /// make `whence foo`/`type foo`/`functions foo` recognize `foo` as
    /// a function before it's actually loaded. Doesn't trigger autoload
    /// itself; use `maybe_autoload` first if you need to load before
    /// introspecting.
    pub fn function_exists(&self, name: &str) -> bool {
        // Either compiled (already loaded) or shfunctab has an
        // autoload stub with PM_UNDEFINED set (pending). Matches C's
        // `lookupshfunc(name)` semantics at `Src/exec.c:5215`.
        if self.functions_compiled.contains_key(name) {
            return true;
        }
        crate::ported::hashtable::shfunctab_lock().read().ok()
            .map(|t| t.get(name).is_some())
            .unwrap_or(false)
    }

    /// Canonical source text for a function. Returns from `function_source`
    /// (populated by autoload paths and runtime FuncDef registration via
    /// BUILTIN_REGISTER_COMPILED_FN with body_source). Returns `None` if
    /// no canonical source is on file.
    pub fn function_definition_text(&self, name: &str) -> Option<String> {
        self.function_source.get(name).cloned()
    }

    /// Remove a function from both tables (compiled chunk + canonical
    /// source). Returns true iff at least one table held it.
    pub fn remove_function(&mut self, name: &str) -> bool {
        let a = self.functions_compiled.remove(name).is_some();
        let c = self.function_source.remove(name).is_some();
        let _ = self.function_line_base.remove(name);
        let _ = self.function_def_file.remove(name);
        a || c
    }

    /// Sorted list of every known function name (union of compiled + source).
    pub fn function_names(&self) -> Vec<String> {
        let mut set: std::collections::BTreeSet<String> = std::collections::BTreeSet::new();
        for k in self.functions_compiled.keys() {
            set.insert(k.clone());
        }
        for k in self.function_source.keys() {
            set.insert(k.clone());
        }
        set.into_iter().collect()
    }

    /// Dispatch a function by name through the new (compiled) pipeline.
    /// Mirrors `ZshrsHost::call_function`'s resolution order — checks
    /// `functions_compiled` first, triggers autoload if needed, then falls
    /// back to the legacy AST recompile path. Returns `None` if the name
    /// isn't a function (caller falls back to external dispatch).
    ///
    /// This is the synchronous-side replacement for the legacy
    /// `call_function(&ShellCommand, args)`. It avoids the AST detour when
    /// the new pipeline already has a Chunk for the function.
    pub fn dispatch_function_call(&mut self, name: &str, args: &[String]) -> Option<i32> {
        // maybe_autoload / autoload_function were deleted with the
        // old exec.c stubs. Until canonical autoload is wired,
        // resolve from functions_compiled directly.
        let chunk = self.functions_compiled.get(name).cloned()?;

        // FUNCNEST guard — see `call_function` for the lower-than-
        // zsh ceiling rationale. Cap at 100 by default (matches
        // call_function's ceiling).
        let funcnest_limit: usize = self
            .scalar("FUNCNEST")
            .and_then(|s| s.parse().ok())
            .unwrap_or(100);
        if self.local_scope_depth >= funcnest_limit {
            eprintln!(
                "{}: maximum nested function level reached; increase FUNCNEST?",
                name
            );
            return Some(1);
        }
        // Save and replace positional params + local-scope save/restore,
        // mirroring the legacy `call_function(&ShellCommand, args)` and
        // ZshrsHost::call_function.
        let saved_params = self.pparams();
        self.set_pparams(args.to_vec());
        // FUNCTION_ARGZERO: zsh sets `\$0` inside a function to the
        // function name (default-on option). The bytecode-level
        // call_function path already does this; the dispatch path
        // used by dynamic-command-name dispatch (`f=hook; \$f`)
        // didn't, so plugin code reading `\$0` saw the binary path
        // instead. Save and install the function name; restore on
        // exit. Anonymous functions get the cosmetic `(anon)` per
        // call_function above.
        let display_name = if name.starts_with("_zshrs_anon_") {
            "(anon)".to_string()
        } else {
            name.to_string()
        };
        let saved_zero = crate::ported::params::getsparam("0");
        self.set_scalar("0".to_string(), display_name);
        self.local_scope_depth += 1;
        // c:Src/exec.c doshfunc startparamscope(): bump canonical
        // `locallevel` so any `local`/`typeset` inside the body
        // installs Params at the correct scope. endparamscope at
        // exit decrements + restores Param.old chain.
        crate::ported::params::locallevel.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
        let line_base = self
            .function_line_base
            .get(name)
            .copied()
            .unwrap_or(0);
        let def_file = self.function_def_file.get(name).cloned().flatten();
        self.prompt_funcstack
            .push((name.to_string(), line_base, def_file));

        crate::fusevm_disasm::maybe_print_stdout(&format!("function:{name}"), &chunk);
        let mut vm = fusevm::VM::new(chunk);
        register_builtins(&mut vm);
        let _ctx = ExecutorContext::enter(self);
        let _ = vm.run();
        let status = vm.last_status;
        drop(_ctx);

        self.set_pparams(saved_params);
        self.prompt_funcstack.pop();
        // c:Src/exec.c doshfunc → endparamscope(). Decrements
        // canonical locallevel and walks paramtab restoring the
        // Param.old chain for every entry installed at this depth.
        crate::ported::params::endparamscope();
        self.local_scope_depth -= 1;
        match saved_zero {
            Some(v) => {
                self.set_scalar("0".to_string(), v);
            }
            None => {
                self.unset_scalar("0");
            }
        }

        // Honor explicit `return N` from inside the function body.
        if let Some(ret) = self.returning.take() {
            self.set_last_status(ret);
            Some(ret)
        } else {
            self.set_last_status(status);
            Some(status)
        }
    }

    pub(crate) fn execute_external(
        &mut self,
        cmd: &str,
        args: &[String],
        redirects: &[Redirect],
    ) -> Result<i32, String> {
        self.execute_external_bg(cmd, args, redirects, false)
    }

    fn execute_external_bg(
        &mut self,
        cmd: &str,
        args: &[String],
        _redirects: &[Redirect],
        background: bool,
    ) -> Result<i32, String> {
        tracing::trace!(cmd, bg = background, "exec external");
        let mut command = Command::new(cmd);
        command.args(args);

        // Redirect handling moved entirely to fusevm's WithRedirectsBegin/End
        // ops at compile time; the `_redirects` slice arrives empty in every
        // production code path. The legacy `for redir in redirects { ... }`
        // block (~120 LOC of file/pipe/heredoc/herestring/fd_var handling)
        // is gone.

        if background {
            match command.spawn() {
                Ok(child) => {
                    let pid = child.id();
                    let cmd_str = format!("{} {}", cmd, args.join(" "));
                    let job_id = self.jobs.add_job(child, cmd_str, JobState::Running);
                    println!("[{}] {}", job_id, pid);
                    Ok(0)
                }
                Err(e) => {
                    if e.kind() == io::ErrorKind::NotFound {
                        // zsh: absolute paths emit "no such file or
                        // directory" (the OS error, since the path was
                        // tried directly), not "command not found"
                        // (which implies PATH search).
                        if cmd.starts_with('/') {
                            eprintln!("zshrs:1: no such file or directory: {}", cmd);
                        } else {
                            eprintln!("zshrs:1: command not found: {}", cmd);
                        }
                        Ok(127)
                    } else {
                        Err(format!("zshrs: {}: {}", cmd, e))
                    }
                }
            }
        } else {
            match command.status() {
                Ok(status) => Ok(status.code().unwrap_or(1)),
                Err(e) => {
                    if e.kind() == io::ErrorKind::NotFound {
                        // zsh: absolute paths emit "no such file or
                        // directory" (the OS error, since the path was
                        // tried directly), not "command not found"
                        // (which implies PATH search).
                        if cmd.starts_with('/') {
                            eprintln!("zshrs:1: no such file or directory: {}", cmd);
                        } else {
                            eprintln!("zshrs:1: command not found: {}", cmd);
                        }
                        Ok(127)
                    } else if e.kind() == io::ErrorKind::PermissionDenied {
                        // zsh: non-executable file → "permission denied"
                        // on stderr and exit 126 (POSIX convention for
                        // "command found but not executable"). zshrs
                        // previously bubbled the IO error up via Err
                        // and the surrounding code converted to 127
                        // with no diagnostic.
                        eprintln!("zshrs:1: permission denied: {}", cmd);
                        Ok(126)
                    } else {
                        Err(format!("zshrs: {}: {}", cmd, e))
                    }
                }
            }
        }
    }

    pub(crate) fn collect_until_paren(chars: &mut std::iter::Peekable<std::str::Chars>) -> String {
        let mut result = String::new();
        let mut depth = 1;

        for c in chars.by_ref() {
            if c == '(' {
                depth += 1;
                result.push(c);
            } else if c == ')' {
                depth -= 1;
                if depth == 0 {
                    break;
                }
                result.push(c);
            } else {
                result.push(c);
            }
        }

        result
    }

    pub(crate) fn collect_until_double_paren(
        chars: &mut std::iter::Peekable<std::str::Chars>,
    ) -> String {
        let mut result = String::new();
        let mut arith_depth = 1; // Tracks $(( ... )) nesting
        let mut paren_depth = 0; // Tracks ( ... ) nesting within expression

        while let Some(c) = chars.next() {
            if c == '(' {
                if paren_depth == 0 && chars.peek() == Some(&'(') {
                    // Nested $(( - but we need to see if it's really another arithmetic
                    // For simplicity, track inner parens
                    paren_depth += 1;
                    result.push(c);
                } else {
                    paren_depth += 1;
                    result.push(c);
                }
            } else if c == ')' {
                if paren_depth > 0 {
                    // Inside nested parens, just close one level
                    paren_depth -= 1;
                    result.push(c);
                } else if chars.peek() == Some(&')') {
                    // At top level and seeing )) - this closes our arithmetic
                    chars.next();
                    arith_depth -= 1;
                    if arith_depth == 0 {
                        break;
                    }
                    result.push_str("))");
                } else {
                    // Single ) at top level - shouldn't happen in valid expression
                    result.push(c);
                }
            } else {
                result.push(c);
            }
        }

        result
    }

    /// Parse `cmd_str` via parse_init+parse and pull out the first Simple
    /// command's words, untokenized + variable-expanded, ready to spawn
    /// as argv. Used by process-substitution where we need raw argv to
    /// hand to `Command::new`. Returns empty vec if the cmd isn't a
    /// simple shape — pipelines / compound forms aren't process-sub
    /// friendly anyway.
    fn simple_cmd_words(&mut self, cmd_str: &str) -> Vec<String> {
        // Mirror Src/init.c-style errflag save/clear/check around the
        // parse. Process-sub argv extraction silently bails on syntax
        // errors (matches zsh's behavior when the inner command can't
        // be parsed).
        let saved_errflag = errflag.load(Ordering::Relaxed);
        errflag.fetch_and(!ERRFLAG_ERROR, Ordering::Relaxed);
        crate::ported::parse::parse_init(cmd_str);
        let prog = crate::ported::parse::parse();
        let parse_failed = (errflag.load(Ordering::Relaxed) & ERRFLAG_ERROR) != 0;
        errflag.store(saved_errflag, Ordering::Relaxed);
        if parse_failed {
            return Vec::new();
        }
        let first = match prog.lists.first() {
            Some(l) => l,
            None => return Vec::new(),
        };
        let pipe = &first.sublist.pipe;
        if let crate::parse::ZshCommand::Simple(simple) = &pipe.cmd {
            simple
                .words
                .iter()
                .map(|w| {
                    // Untokenize then variable-expand — text-based
                    // word expansion for the spawned argv.
                    let untoked = crate::lex::untokenize(w);
                    crate::ported::subst::singsub(&untoked)
                })
                .collect()
        } else {
            Vec::new()
        }
    }

    pub(crate) fn run_process_sub_in(&mut self, cmd_str: &str) -> String {

        // Phase 2: parse via parse_init+parse. Extract the first Simple cmd's
        // words (untokenized), pre-expand to argv strings, spawn.
        let words = self.simple_cmd_words(cmd_str);

        // Create a unique FIFO in temp directory
        let fifo_path = format!("/tmp/zshrs_psub_{}", std::process::id());
        let fifo_counter = self.process_sub_counter;
        self.process_sub_counter += 1;
        let fifo_path = format!("{}_{}", fifo_path, fifo_counter);

        // Remove if exists, then create FIFO
        let _ = fs::remove_file(&fifo_path);
        if nix::unistd::mkfifo(fifo_path.as_str(), nix::sys::stat::Mode::S_IRWXU).is_err() {
            return String::new();
        }

        // Spawn command that writes to the FIFO
        let fifo_clone = fifo_path.clone();
        if !words.is_empty() {
            let cmd_name = words[0].clone();
            let args: Vec<String> = words[1..].to_vec();

            self.worker_pool.submit(move || {
                // Open FIFO for writing (will block until reader connects)
                if let Ok(fifo) = fs::OpenOptions::new().write(true).open(&fifo_clone) {
                    let _ = Command::new(&cmd_name)
                        .args(&args)
                        .stdout(fifo)
                        .stderr(Stdio::inherit())
                        .status();
                }
                // Clean up FIFO after command completes
                let _ = fs::remove_file(&fifo_clone);
            });
        }

        fifo_path
    }

    pub(crate) fn run_process_sub_out(&mut self, cmd_str: &str) -> String {

        let words = self.simple_cmd_words(cmd_str);

        // Create a unique FIFO in temp directory
        let fifo_path = format!("/tmp/zshrs_psub_{}", std::process::id());
        let fifo_counter = self.process_sub_counter;
        self.process_sub_counter += 1;
        let fifo_path = format!("{}_{}", fifo_path, fifo_counter);

        // Remove if exists, then create FIFO
        let _ = fs::remove_file(&fifo_path);
        if nix::unistd::mkfifo(fifo_path.as_str(), nix::sys::stat::Mode::S_IRWXU).is_err() {
            return String::new();
        }

        // Spawn command that reads from the FIFO
        let fifo_clone = fifo_path.clone();
        if !words.is_empty() {
            let cmd_name = words[0].clone();
            let args: Vec<String> = words[1..].to_vec();

            self.worker_pool.submit(move || {
                // Open FIFO for reading (will block until writer connects)
                if let Ok(fifo) = fs::File::open(&fifo_clone) {
                    let _ = Command::new(&cmd_name)
                        .args(&args)
                        .stdin(fifo)
                        .stdout(Stdio::inherit())
                        .stderr(Stdio::inherit())
                        .status();
                }
                // Clean up FIFO after command completes
                let _ = fs::remove_file(&fifo_clone);
            });
        }

        fifo_path
    }

    pub fn run_command_substitution(&mut self, cmd_str: &str) -> String {
        // `$(< FILE)` — zsh shorthand for "read FILE contents". Faster
        // than spawning `cat`. The leading `<` (after stripping
        // whitespace) means "read this file". Trailing newline is
        // stripped (same as command-substitution).
        let trimmed = cmd_str.trim_start();
        // Only treat as `$(<file)` shorthand when the SINGLE leading `<`
        // is followed by a filename, not another `<`. `$(<<<"hi" cat)`
        // starts with `<<<` (here-string) and must go through the full
        // parse path, not the read-file shortcut.
        if let Some(rest) = trimmed.strip_prefix('<').filter(|s| !s.starts_with('<')) {
            let filename = rest.trim();
            // Expand any leading $ / tilde in the filename so
            // `$(< $f)` and `$(< ~/x)` work.
            let resolved = if filename.contains('$') || filename.starts_with('~') {
                crate::ported::subst::singsub(filename)
            } else {
                filename.to_string()
            };
            let resolved = resolved.to_string();
            match std::fs::read_to_string(&resolved) {
                Ok(contents) => {
                    return contents.trim_end_matches('\n').to_string();
                }
                Err(_) => {
                    eprintln!("zshrs:1: no such file or directory: {}", resolved);
                    return String::new();
                }
            }
        }

        // Port of getoutput(char *cmd, int qt) from Src/exec.c. Parse and compile via
        // the lex+parse free fns + ZshCompiler pipeline, run on a
        // sub-VM with the host wired up. Stdout is captured through
        // an in-process pipe via dup2 — no fork.
        //
        // This single path replaces the prior "internal vs external"
        // fast-path split: the sub-VM emits Op::Exec for unknown
        // command names, which forks/execs through the host.

        // Set up the stdout-capture pipe. We dup the original stdout
        // so post-run we can restore it; the write end is dup2'd onto
        // STDOUT_FILENO so all output the sub-VM emits (including from
        // forked children, which inherit fd 1) lands in the pipe.
        let (read_fd, write_fd) = {
            let mut fds = [0i32; 2];
            if unsafe { libc::pipe(fds.as_mut_ptr()) } != 0 {
                return String::new();
            }
            (fds[0], fds[1])
        };
        let saved_stdout = unsafe { libc::dup(libc::STDOUT_FILENO) };
        if saved_stdout < 0 {
            unsafe {
                libc::close(read_fd);
                libc::close(write_fd);
            }
            return String::new();
        }
        unsafe {
            libc::dup2(write_fd, libc::STDOUT_FILENO);
            libc::close(write_fd);
        }

        // Parse + compile + run.
        // Push CS_CMDSUBST for `%_` xtrace prefix — direct port of
        // Src/exec.c:4783 `cmdpush(CS_CMDSUBST);` around execode().
        // Trace lines emitted by the inner program inherit this token
        // so their PS4 prefix shows "cmdsubst" matching zsh -x.
        crate::ported::prompt::cmdpush(crate::ported::zsh_h::CS_CMDSUBST as u8); // c:zsh.h:2799
        // Save LINENO so the inner cmdsubst's line counter doesn't
        // leak into the outer trace — direct port of Src/exec.c:1407
        // `oldlineno = lineno;` followed by `lineno = oldlineno;`
        // restore at line 1640. Inner program parses fresh as line 1
        // and increments from there; once it returns, the outer
        // line at the `$(…)` site must read the original outer
        // lineno (so xtrace renders `+:5:> echo …` not `+:1:> …`).
        let saved_lineno = crate::ported::params::getsparam("LINENO");
        // Anchor the inner program's lineno to the outer's current
        // $LINENO so xtrace inside the cmdsubst renders the outer
        // line. zsh's execlist preserves lineno across the inner
        // exec — for our sub-VM (fresh compile) we use lineno_addend
        // to shift inner's line N → outer_lineno + (N - 1).
        let outer_lineno: u64 = self
            .scalar("LINENO")
            .and_then(|s| s.parse::<u64>().ok())
            .unwrap_or(0);
        // Mirror Src/init.c errflag save/clear/check pattern around
        // the nested parse so an inner syntax error doesn't bleed into
        // the outer execution.
        let saved_errflag = errflag.load(Ordering::Relaxed);
        errflag.fetch_and(!ERRFLAG_ERROR, Ordering::Relaxed);
        crate::ported::parse::parse_init(cmd_str);
        let parsed = crate::ported::parse::parse();
        let parse_failed = (errflag.load(Ordering::Relaxed) & ERRFLAG_ERROR) != 0;
        errflag.store(saved_errflag, Ordering::Relaxed);
        let prog = if parse_failed { None } else { Some(parsed) };
        let mut cmd_status: Option<i32> = None;
        if let Some(prog) = prog {
            let mut compiler = crate::compile_zsh::ZshCompiler::new();
            compiler.lineno_addend = outer_lineno.saturating_sub(1);
            let chunk = compiler.compile(&prog);
            if !chunk.ops.is_empty() {
                crate::fusevm_disasm::maybe_print_stdout("run_command_substitution", &chunk);
                let mut vm = fusevm::VM::new(chunk);
                register_builtins(&mut vm);
                vm.set_shell_host(Box::new(ZshrsHost));
                // Seed inner $? with the outer's last_status so the
                // sub-shell inherits the parent's exit code. Direct
                // port of Src/exec.c:4783 around execcmd_exec — the
                // child inherits `lastval` at fork time, so `false;
                // echo $(echo $?)` reads 1, not the freshly-zeroed
                // sub-VM default. Without this, every cmd-subst
                // started with $?==0 regardless of the parent's
                // last command.
                vm.last_status = self.last_status();
                let _ctx = ExecutorContext::enter(self);
                let _ = vm.run();
                cmd_status = Some(vm.last_status);
            }
        }
        // Restore LINENO so outer xtrace sees the outer line.
        if let Some(ln) = saved_lineno {
            self.set_scalar("LINENO".to_string(), ln);
        }
        crate::ported::prompt::cmdpop();
        // Propagate the inner cmd's status to the parent shell. zsh:
        // `a=$(false); echo $?` → 1 because cmd-subst status leaks to
        // $?. Set last_status on the executor so $? reads the right
        // value for callers that don't have a SetStatus(0) overwrite
        // (echo, test, etc.). Bare assignment paths still get the
        // SetStatus(0) from compile_simple — that's a separate gap.
        // Empty cmd-subst (`\`\``, `$()`) resets status to 0 per
        // Src/exec.c — the inner ran no command so the "last
        // command's exit" is the implicit success of "did nothing".
        // Without this branch, a prior command's non-zero status
        // leaked through the empty cmd-subst.
        if let Some(status) = cmd_status {
            self.set_last_status(status);
        } else {
            self.set_last_status(0);
        }

        // Flush any buffered Rust-side stdout so it reaches the pipe
        // before we restore.
        let _ = io::stdout().flush();

        // Restore stdout and read what was captured.
        unsafe {
            libc::dup2(saved_stdout, libc::STDOUT_FILENO);
            libc::close(saved_stdout);
        }
        let read_file = unsafe { std::fs::File::from_raw_fd(read_fd) };
        let mut output = String::new();
        let _ = std::io::BufReader::new(read_file).read_to_string(&mut output);

        // POSIX: trailing newlines stripped from cmd-sub result.
        while output.ends_with('\n') {
            output.pop();
        }
        output
    }

    // ksh_autoload_body moved to src/ported/builtin.rs
}

impl Default for ShellExecutor {
    fn default() -> Self {
        Self::new()
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_simple_echo() {
        let mut exec = ShellExecutor::new();
        let status = exec.execute_script("true").unwrap();
        assert_eq!(status, 0);
    }

    #[test]
    fn test_if_true() {
        let mut exec = ShellExecutor::new();
        let status = exec.execute_script("if true; then true; fi").unwrap();
        assert_eq!(status, 0);
    }

    #[test]
    fn test_if_false() {
        let mut exec = ShellExecutor::new();
        let status = exec
            .execute_script("if false; then true; else false; fi")
            .unwrap();
        assert_eq!(status, 1);
    }

    #[test]
    fn test_for_loop() {
        let mut exec = ShellExecutor::new();
        exec.execute_script("for i in a b c; do true; done")
            .unwrap();
        assert_eq!(exec.last_status(), 0);
    }

    #[test]
    fn test_and_list() {
        let mut exec = ShellExecutor::new();
        let status = exec.execute_script("true && true").unwrap();
        assert_eq!(status, 0);

        let status = exec.execute_script("true && false").unwrap();
        assert_eq!(status, 1);
    }

    #[test]
    fn test_or_list() {
        let mut exec = ShellExecutor::new();
        let status = exec.execute_script("false || true").unwrap();
        assert_eq!(status, 0);
    }

    /// Pin: `forklevel` matches the C global declared at
    /// `Src/exec.c:1052` (`int forklevel;`). Like `int` in C, the
    /// Rust port is an AtomicI32 starting at 0 (no fork has occurred
    /// at process start). Per `Src/exec.c:1221` (`forklevel =
    /// locallevel;`), every subshell entry copies `locallevel` into
    /// the global; the SIGPIPE handler at `Src/signals.c:808` reads
    /// it back to distinguish the top-level shell from a subshell.
    #[test]
    fn test_forklevel_default_zero_and_roundtrip() {
        use std::sync::atomic::Ordering;
        let prev = FORKLEVEL.load(Ordering::Relaxed);
        // Default state at process start: zero (matches C's BSS init
        // of `int forklevel;` to 0).
        FORKLEVEL.store(0, Ordering::Relaxed);
        assert_eq!(FORKLEVEL.load(Ordering::Relaxed), 0);
        // Simulate the c:1221 store: `forklevel = locallevel;`.
        FORKLEVEL.store(3, Ordering::Relaxed);
        assert_eq!(FORKLEVEL.load(Ordering::Relaxed), 3);
        FORKLEVEL.store(prev, Ordering::Relaxed);
    }
}

// Plugin-Framework-Agnostic State-Modification Recorder hook helpers.
/// Recorder helper: emit one record for an array/scalar mutation
/// targeting a path-family parameter (path/fpath/manpath/module_path/
/// cdpath, lower- or upper-cased), or one `assign` record for any
/// other name. Centralises the path-family list so `BUILTIN_SET_ARRAY`,
/// `BUILTIN_APPEND_ARRAY`, and `BUILTIN_APPEND_SCALAR_OR_PUSH` share
/// the same routing.
///
/// `is_append` distinguishes `arr=(...)` from `arr+=(...)` so the
/// emitted event carries the APPEND attr bit and replay can choose
/// between fresh-set and extend semantics.
///
/// `attrs` carries any pre-existing type info from
/// `recorder_attrs_for(name)` (readonly/export/global) — array shape
/// and APPEND get OR'd in by emit_array_assign.
#[cfg(feature = "recorder")]
pub(crate) fn emit_path_or_assign(
    name: &str,
    values: &[String],
    attrs: crate::recorder::ParamAttrs,
    is_append: bool,
    ctx: &crate::recorder::RecordCtx,
) {
    let lower = name.to_ascii_lowercase();
    let kind_name: Option<&'static str> = match lower.as_str() {
        "path" => Some("path"),
        "fpath" => Some("fpath"),
        "manpath" => Some("manpath"),
        "module_path" => Some("module_path"),
        "cdpath" => Some("cdpath"),
        _ => None,
    };
    match kind_name {
        Some(k) => {
            for v in values {
                crate::recorder::emit_path_mod(v, k, ctx.clone());
                // Each fpath addition also surfaces every `_completion`
                // file inside the directory — matches zinit-report's
                // per-plugin "Completions:" listing. Only fpath dirs
                // get this treatment; PATH dirs hold executables, not
                // completion functions.
                if k == "fpath" {
                    crate::recorder::discover_completions_in_fpath_dir(v, ctx);
                }
            }
        }
        None => {
            // Non-path arrays: emit ONE `assign` event with the
            // ordered element list preserved in value_array. Replay
            // reconstructs `name=(elem1 elem2 ...)` exactly without
            // having to re-split a joined string.
            crate::recorder::emit_array_assign(
                name,
                values.to_vec(),
                attrs,
                is_append,
                ctx.clone(),
            );
        }
    }
}

// Whole impl block is `#[cfg(feature = "recorder")]` so the default
// build sees no recorder symbols on `ShellExecutor`.
#[cfg(feature = "recorder")]
impl ShellExecutor {}

#[cfg(feature = "recorder")]
impl ShellExecutor {}

impl ShellExecutor {
    /// `add-zsh-hook` registration stub. The hooks-machinery file was
    /// removed from extensions/; these no-ops preserve the call sites
    /// in `ext_builtins.rs::builtin_add_zsh_hook` and `plugin_cache.rs`.
    pub(crate) fn add_hook(&mut self, _hook: &str, _func: &str) {}

    /// `add-zsh-hook -d` removal — same stub rationale as `add_hook`.
    pub(crate) fn delete_hook(&mut self, _hook: &str, _func: &str) {}

    // ═══════════════════════════════════════════════════════════════════
    // AOP INTERCEPT — the killer builtin
    // ═══════════════════════════════════════════════════════════════════

    // ═══════════════════════════════════════════════════════════════════
    // CONCURRENT PRIMITIVES — ship work to the worker pool from shell
    // No stryke dependency. Pure zshrs. Thin binary gets full parallelism.
    // ═══════════════════════════════════════════════════════════════════
}


impl ShellExecutor {
    // ═══════════════════════════════════════════════════════════════════════════
    // Additional zsh builtins
    // ═══════════════════════════════════════════════════════════════════════════

    /// Helper to check if name is a builtin. Consults the canonical
    /// `BUILTINS` table (`src/ported/builtin.rs:122`, the 1:1 port of
    /// `static struct builtin builtins[]` at `Src/builtin.c:40-137`).
    /// Earlier implementation hardcoded a separate `BUILTIN_SET`
    /// HashSet of 130+ names — duplicated state that drifts when new
    /// builtins land in the canonical table. The cached lookup set
    /// below is built once from `BUILTINS` so the O(1) cost stays
    /// without a separate authoritative list.
    pub(crate) fn is_builtin(&self, name: &str) -> bool {
        BUILTIN_NAMES.contains(name) || name.starts_with('_')
    }

    /// Helper to find command in PATH. The fast path consults the
    /// `command_hash` table (rebuilt by `rehash` per `Src/Modules/
    /// hashed.c`); the slow path delegates to the canonical port of
    /// `findcmd()` (`Src/exec.c:5260`, ported at
    /// `src/ported/builtin.rs:4047`). Earlier inline PATH walk
    /// duplicated findcmd's logic without honoring `name.contains('/')`
    /// (the C source returns the literal path for slashed names
    /// without walking $PATH).
    pub(crate) fn find_in_path(&self, name: &str) -> Option<String> {
        // Canonical command-hash lives in `cmdnamtab`. `get_full_path`
        // returns the resolved path for HASHED entries.
        if let Some(p) = crate::ported::hashtable::cmdnamtab_lock()
            .read().ok()
            .and_then(|t| t.get_full_path(name))
        {
            return Some(p.display().to_string());
        }
        crate::ported::builtin::findcmd(name, 0, 0)                          // c:exec.c:5260
    }

    // ═══════════════════════════════════════════════════════════════════════════
    // zsh module builtins
    // ═══════════════════════════════════════════════════════════════════════════

    // =========================================================================
    // Process control functions - Port from exec.c
    // =========================================================================

    /// Fork a new process
    /// Port of zfork(struct timespec *ts) from exec.c
    pub fn zfork(&mut self, flags: ForkFlags) -> std::io::Result<ForkResult> {
        // Check for job control
        let can_background = crate::ported::options::opt_state_get("monitor").unwrap_or(false);

        unsafe {
            match libc::fork() {
                -1 => Err(std::io::Error::last_os_error()),
                0 => {
                    // Child process
                    if !flags.contains(ForkFlags::NOJOB) && can_background {
                        // Set up job control
                        let pid = libc::getpid();
                        if flags.contains(ForkFlags::NEWGRP) {
                            libc::setpgid(0, 0);
                        }
                        if flags.contains(ForkFlags::FGTTY) {
                            libc::tcsetpgrp(0, pid);
                        }
                    }

                    // Reset signal handlers
                    if !flags.contains(ForkFlags::KEEPSIGS) {
                        self.reset_signals();
                    }

                    Ok(ForkResult::Child)
                }
                pid => {
                    // Parent process
                    if !flags.contains(ForkFlags::NOJOB) {
                        // Add to job table
                        self.add_child_process(pid);
                    }
                    Ok(ForkResult::Parent(pid))
                }
            }
        }
    }

    /// Add a child process to tracking
    fn add_child_process(&mut self, pid: i32) {
        // Would track in job table
        self.set_scalar("!".to_string(), pid.to_string());
    }

    /// Reset signal handlers to defaults
    fn reset_signals(&self) {
        unsafe {
            libc::signal(libc::SIGINT, libc::SIG_DFL);
            libc::signal(libc::SIGQUIT, libc::SIG_DFL);
            libc::signal(libc::SIGTERM, libc::SIG_DFL);
            libc::signal(libc::SIGTSTP, libc::SIG_DFL);
            libc::signal(libc::SIGTTIN, libc::SIG_DFL);
            libc::signal(libc::SIGTTOU, libc::SIG_DFL);
            libc::signal(libc::SIGCHLD, libc::SIG_DFL);
        }
    }

    /// Execute a command in the current process (exec family)
    /// Port of zexecve(char *pth, char **argv, char **newenvp) from exec.c
    pub fn zexecve(&self, cmd: &str, args: &[String]) -> ! {

        let c_cmd = CString::new(cmd).expect("CString::new failed");

        // Build argv
        let c_args: Vec<CString> = std::iter::once(c_cmd.clone())
            .chain(args.iter().map(|s| CString::new(s.as_str()).unwrap()))
            .collect();

        let c_argv: Vec<*const libc::c_char> = c_args
            .iter()
            .map(|s| s.as_ptr())
            .chain(std::iter::once(std::ptr::null()))
            .collect();

        // Build envp from current environment
        let env_vars: Vec<CString> = std::env::vars()
            .map(|(k, v)| CString::new(format!("{}={}", k, v)).unwrap())
            .collect();

        let c_envp: Vec<*const libc::c_char> = env_vars
            .iter()
            .map(|s| s.as_ptr())
            .chain(std::iter::once(std::ptr::null()))
            .collect();

        unsafe {
            libc::execve(c_cmd.as_ptr(), c_argv.as_ptr(), c_envp.as_ptr());
            // If we get here, exec failed
            eprintln!(
                "zshrs: exec failed: {}: {}",
                cmd,
                std::io::Error::last_os_error()
            );
            std::process::exit(127);
        }
    }

    /// Enter a subshell
    /// Port of entersubsh(int flags, struct entersubsh_ret *retp) from exec.c
    pub fn entersubsh(&mut self, flags: SubshellFlags) {
        // Increment subshell level
        let level = self
            .get_variable("ZSH_SUBSHELL")
            .parse::<i32>()
            .unwrap_or(0);
        self.set_scalar("ZSH_SUBSHELL".to_string(), (level + 1).to_string());

        // Handle job control
        if flags.contains(SubshellFlags::NOMONITOR) {
            crate::ported::options::opt_state_set("monitor", false);
        }

        // Close unneeded fds
        if !flags.contains(SubshellFlags::KEEPFDS) {
            self.close_extra_fds();
        }

        // Reset traps
        if !flags.contains(SubshellFlags::KEEPTRAPS) {
            self.reset_traps();
        }

        // c:1221 — `forklevel = locallevel;` at the tail of entersubsh.
        // Records the locallevel depth at this subshell entry so the
        // SIGPIPE handler (signals.c:808) and the WARNCREATEGLOBAL
        // nest-depth check (params.c:3724) can distinguish parent vs
        // child shell contexts.
        let cur_local = crate::ported::params::locallevel
            .load(std::sync::atomic::Ordering::Relaxed);
        FORKLEVEL.store(cur_local, std::sync::atomic::Ordering::Relaxed);     // c:1221 (Src/exec.c)
    }

    /// Close extra file descriptors
    fn close_extra_fds(&self) {
        // Close fds > 10 (common shell convention)
        for fd in 10..256 {
            unsafe {
                libc::close(fd);
            }
        }
    }

    fn reset_traps(&mut self) {
        self.traps.clear();
    }


    // ═══════════════════════════════════════════════════════════════════════
    // Coreutils builtins (anti-fork) — only active when !posix_mode
    // ═══════════════════════════════════════════════════════════════════════

    // nproc-equivalent already exists via builtin_nproc.
}

use std::os::unix::fs::MetadataExt;

bitflags::bitflags! {
    /// Flags for zfork()
    #[derive(Debug, Clone, Copy, Default)]
    pub struct ForkFlags: u32 {
        const NOJOB = 1 << 0;    // Don't add to job table
        const NEWGRP = 1 << 1;   // Create new process group
        const FGTTY = 1 << 2;    // Take foreground terminal
        const KEEPSIGS = 1 << 3; // Keep signal handlers
    }
}

bitflags::bitflags! {
    /// Flags for entersubsh()
    #[derive(Debug, Clone, Copy, Default)]
    pub struct SubshellFlags: u32 {
        const NOMONITOR = 1 << 0; // Disable job control
        const KEEPFDS = 1 << 1;   // Keep file descriptors
        const KEEPTRAPS = 1 << 2; // Keep trap handlers
    }
}

/// Result of fork operation
#[derive(Debug)]
/// `fork()` outcome (parent / child / error).
/// Mirrors the integer return of `zfork()` from Src/exec.c:349.
pub enum ForkResult {
    Parent(i32), // Contains child PID
    Child,
}

/// Redirection mode
#[derive(Debug, Clone, Copy)]
/// File-redirection mode (`>` / `>>` / `<` / etc.).
/// Mirrors the `REDIR_*` enum from Src/zsh.h.
pub enum RedirMode {
    Dup,
    Close,
}

/// Builtin command type
#[derive(Debug, Clone, Copy)]
/// Builtin classification.
/// Mirrors the `BINF_*` flag set Src/builtin.c uses to
/// classify special vs regular builtins.
pub enum BuiltinType {
    Normal,
    Disabled,
}

// =====================================================================
// Builtin dispatch stubs.
//
// These methods used to live in `src/ported/builtin.rs` inside
// `impl ShellExecutor` blocks. Per user feedback ("each of those
// bin_* is fake anyways"), the impl blocks were deleted from the
// port tree. The methods are recreated here as stubs so existing
// callers (fusevm_bridge, ext_builtins, exec.rs's own dispatch loop)
// keep compiling. Each stub delegates to the canonical free-fn port
// at `crate::ported::builtin::bin_X` when one exists, or returns 0.
//
// The recorder hooks the original methods carried are preserved as
// commented snippets at the bottom of `src/ported/builtin.rs` —
// they will be re-wired here once the canonical bin_* ports are
// true to C.
// =====================================================================
#[allow(unused_variables, dead_code)]
impl ShellExecutor {
    fn _empty_ops() -> crate::ported::zsh_h::options {
        options { ind: [0u8; MAX_OPS], args: Vec::new(),
                  argscount: 0, argsalloc: 0 }
    }

    pub(crate) fn dispatch_pending_traps(&mut self) {}
    // Note: `recorder_ctx()` lives in src/extensions/recorder.rs
    // (gated behind --features recorder). Do not stub it here or
    // you'll get a duplicate-definition error when the recorder
    // feature is enabled.

    pub(crate) fn builtin_pwd_with_args(&mut self, args: &[String]) -> i32 {
        let ops = Self::_empty_ops();
        crate::ported::builtin::bin_pwd("pwd", args, &ops, 0)
    }
    pub(crate) fn bin_zcompile(&mut self, args: &[String]) -> i32 {
        // C-faithful dispatch via the canonical port in
        // `src/ported/parse.rs::bin_zcompile` (port of `Src/parse.c:3180`).
        // The caller's argv is the full builtin command line, e.g.
        // `["zcompile", "-t", "/path/file.zwc"]`. Parse option chars
        // into an `options` ind[] bitmap and pass positionals.
        let mut ops = options {
            ind: [0u8; MAX_OPS],
            args: Vec::new(),
            argscount: 0,
            argsalloc: 0,
        };
        let mut positional: Vec<String> = Vec::new();
        let mut consume_opts = true;
        // `args` from pop_args holds positional + option words only —
        // no leading builtin name (matches what `bin_*` entry points
        // get from C's `bin_X(char *nam, char **args, ...)` arg vector).
        for a in args.iter() {
            if consume_opts && a == "--" { consume_opts = false; continue; }
            if consume_opts && a.starts_with('-') && a.len() > 1 {
                for c in a.bytes().skip(1) {
                    let idx = c as usize;
                    if idx < MAX_OPS {
                        ops.ind[idx] |= 1; // bit 1 = OPT_MINUS (set as `-X`)
                    }
                }
                continue;
            }
            consume_opts = false;
            positional.push(a.clone());
        }
        crate::ported::parse::bin_zcompile("zcompile", &positional, &ops, 0)
    }

    // zsh implements echo/printf via funcid dispatch into shared
    // `bin_print` (Src/builtin.c:4587 — BIN_ECHO and BIN_PRINTF
    // funcids route through the same handler). Route through
    // `execbuiltin` (Src/builtin.c:250) so flag parsing matches C
    // — earlier impl was `println!("{}", args.join(" "))` which
    // ignored `-n` / `-e` flags and didn't interpret escape
    // sequences.
    pub(crate) fn builtin_echo(&mut self, args: &[String], _redir: &[crate::parse::Redirect]) -> i32 {
        let bn_idx = crate::ported::builtin::BUILTINS.iter()
            .position(|b| b.node.nam == "echo");
        match bn_idx {
            Some(idx) => {
                let bn_static: &'static crate::ported::zsh_h::builtin =
                    &crate::ported::builtin::BUILTINS[idx];
                let bn_ptr = bn_static as *const _ as *mut _;
                crate::ported::builtin::execbuiltin(args.to_vec(), Vec::new(), bn_ptr)
            }
            None => {
                let ops = Self::_empty_ops();
                crate::ported::builtin::bin_print("echo", args, &ops,
                    crate::ported::builtin::BIN_ECHO)
            }
        }
    }
    pub(crate) fn builtin_printf(&mut self, args: &[String]) -> i32 {
        let bn_idx = crate::ported::builtin::BUILTINS.iter()
            .position(|b| b.node.nam == "printf");
        match bn_idx {
            Some(idx) => {
                let bn_static: &'static crate::ported::zsh_h::builtin =
                    &crate::ported::builtin::BUILTINS[idx];
                let bn_ptr = bn_static as *const _ as *mut _;
                crate::ported::builtin::execbuiltin(args.to_vec(), Vec::new(), bn_ptr)
            }
            None => {
                let ops = Self::_empty_ops();
                crate::ported::builtin::bin_print("printf", args, &ops,
                    crate::ported::builtin::BIN_PRINTF)
            }
        }
    }
    pub(crate) fn builtin_local(&mut self, args: &[String]) -> i32 {
        self.dispatch_typeset_as("local", args)
    }
    pub(crate) fn builtin_export(&mut self, args: &[String]) -> i32 {
        self.dispatch_typeset_as("export", args)
    }
    pub(crate) fn builtin_readonly(&mut self, args: &[String]) -> i32 {
        self.dispatch_typeset_as("readonly", args)
    }
    pub(crate) fn builtin_declare(&mut self, args: &[String]) -> i32 {
        self.dispatch_typeset_as("declare", args)
    }
    pub(crate) fn builtin_typeset_named(&mut self, name: &str, args: &[String]) -> i32 {
        self.dispatch_typeset_as(name, args)
    }
    pub(crate) fn builtin_integer(&mut self, args: &[String]) -> i32 {
        self.dispatch_typeset_as("integer", args)
    }
    pub(crate) fn builtin_float(&mut self, args: &[String]) -> i32 {
        self.dispatch_typeset_as("float", args)
    }
    /// Route `local`/`export`/`readonly`/`declare`/`integer`/`float`
    /// through canonical `bin_typeset` via `execbuiltin` so the
    /// BUILTIN("…") entry's optstr is parsed and the `nm0` char in
    /// `bin_typeset` picks up the PM_LOCAL implicit-scope path
    /// (`l` → local, `r`+func → PM_READONLY etc.). The old stub
    /// only `env::set_var`-d which gave no local scoping or
    /// type-flag effect.
    fn dispatch_typeset_as(&mut self, name: &str, args: &[String]) -> i32 {
        let bn_idx = crate::ported::builtin::BUILTINS.iter()
            .position(|b| b.node.nam == name);
        if let Some(idx) = bn_idx {
            let bn_static: &'static crate::ported::zsh_h::builtin =
                &crate::ported::builtin::BUILTINS[idx];
            let bn_ptr = bn_static as *const _ as *mut _;
            return crate::ported::builtin::execbuiltin(args.to_vec(), Vec::new(), bn_ptr);
        }
        // Fallback: best-effort env mirror.
        for a in args {
            if let Some(eq) = a.find('=') {
                std::env::set_var(&a[..eq], &a[eq+1..]);
            }
        }
        0
    }
    // Stubs deleted — these were leftover from an old zshrs port aligned to
    // `Src/exec.c` before fusevm replaced that path. Each was a `{ 0 }` / `{ None }` / `{ false }` no-op
    // pretending to implement a builtin while silently succeeding.
    // Removed: builtin_pushd, builtin_popd, builtin_history,
    // builtin_unalias, builtin_unfunction, builtin_autoload,
    // builtin_command, builtin_builtin, builtin_exec, builtin_noglob,
    // builtin_type, builtin_which, builtin_where, builtin_r,
    // builtin_getln, builtin_pushln, builtin_source_named,
    // autoload_function, maybe_autoload, find_function_file,
    // ksh_autoload_body, findcmd (shadow), get_builtin_names.
    // Callers must route to canonical ports in `src/ported/builtin.rs`
    // or fail loudly so the gap is visible.

    // zutil.rs orphan stubs — moved here after `impl ShellExecutor`
    // was ripped out of src/ported/modules/zutil.rs. The canonical
    // bin_zstyle/bin_zparseopts/bin_zformat/bin_zregexparse free-fn
    // ports (Src/Modules/zutil.c) will land in zutil.rs at module
    // level; until then these stubs unblock callers.
}

// === DISSOLVED FROM src/exec_shims.rs ===
use crate::ported::utils::{zwarn, zwarnnam, zerr, zerrnam};
use crate::ported::params::*;
use crate::ported::options::*;
use crate::ported::hist::*;
use crate::ported::pattern::*;
use crate::ported::prompt::*;
use crate::ported::subst::*;
use crate::ported::math::*;
use crate::ported::jobs::*;
use crate::ported::glob::*;
use crate::ported::module::*;
use crate::ported::signals::*;
use crate::ported::modules::cap::*;
use crate::ported::modules::tcp::bin_ztcp;
use crate::ported::modules::termcap::bin_echotc;
use crate::ported::modules::terminfo::*;
use crate::fusevm_bridge::with_executor;
use ::regex::{Regex, RegexBuilder, Error as RegexError};

// =====================================================================
// MOVED FROM: src/ported/pattern.rs
// =====================================================================

impl crate::ported::exec::ShellExecutor {
    /// Check if pattern contains extended glob syntax
    pub(crate) fn has_extglob_pattern(&self, pattern: &str) -> bool {
        let chars: Vec<char> = pattern.chars().collect();
        for i in 0..chars.len().saturating_sub(1) {
            if (chars[i] == '?'
                || chars[i] == '*'
                || chars[i] == '+'
                || chars[i] == '@'
                || chars[i] == '!')
                && chars[i + 1] == '('
            {
                return true;
            }
        }
        false
    }
    /// Extract the inner part of an extglob pattern (until closing paren)
    pub(crate) fn extract_extglob_inner(&self, chars: &[char], start: usize) -> (String, usize) {
        let mut inner = String::new();
        let mut depth = 1;
        let mut i = start;

        while i < chars.len() && depth > 0 {
            if chars[i] == '(' {
                depth += 1;
            } else if chars[i] == ')' {
                depth -= 1;
                if depth == 0 {
                    return (inner, i);
                }
            }
            inner.push(chars[i]);
            i += 1;
        }

        (inner, i)
    }
    /// Convert the inner part of extglob (handles | for alternation)
    pub(crate) fn extglob_inner_to_regex(&self, inner: &str) -> String {
        // Split by | and convert each alternative
        let alternatives: Vec<String> = inner
            .split('|')
            .map(|alt| {
                let mut result = String::new();
                for c in alt.chars() {
                    match c {
                        '*' => result.push_str(".*"),
                        '?' => result.push('.'),
                        '.' => result.push_str("\\."),
                        '^' | '$' | '(' | ')' | '{' | '}' | '\\' => {
                            result.push('\\');
                            result.push(c);
                        }
                        _ => result.push(c),
                    }
                }
                result
            })
            .collect();

        alternatives.join("|")
    }
}


// =====================================================================
// MOVED FROM: src/ported/options.rs
// =====================================================================

impl crate::ported::exec::ShellExecutor {
    /// Returns every option name in `ZSH_OPTIONS_SET` (canonical port
    /// of `optns[]` at `Src/options.c:79+`). Replaces a 200-line
    /// hardcoded `&[...]` duplicate that drifted from upstream.
    pub(crate) fn all_zsh_options() -> Vec<&'static str> {
        crate::ported::options::ZSH_OPTIONS_SET.iter().copied().collect()
    }
    pub(crate) fn default_options() -> HashMap<String, bool> {
        let mut opts = HashMap::new();
        // Initialize all options to false first
        for opt in Self::all_zsh_options() {
            opts.insert(opt.to_string(), false);
        }
        // Set zsh defaults (options marked with <D> or <Z> in zshoptions man page)
        let defaults_on = [
            "aliases",
            "alwayslastprompt",
            "appendhistory",
            "autolist",
            "automenu",
            "autoparamkeys",
            "autoparamslash",
            "autoremoveslash",
            "badpattern",
            "banghist",
            "bareglobqual",
            "beep",
            "bgnice",
            "caseglob",
            "casematch",
            "checkjobs",
            "checkrunningjobs",
            "clobber",
            "debugbeforecmd",
            "equals",
            "evallineno",
            "exec",
            "flowcontrol",
            "functionargzero",
            "glob",
            "globalexport",
            "globalrcs",
            "hashcmds",
            "hashdirs",
            "hashlistall",
            "histbeep",
            "histsavebycopy",
            "hup",
            // INTERACTIVE is NOT default-on in zsh — C init sets it
            // from isatty(0). Marking it default-on here makes the
            // lexer's `!interact() || unset(SHINSTDIN)` comment gate
            // (lex.c:678) false for non-tty script runs, so every
            // `#`-line was re-lexed as a command. Drop from defaults;
            // tty-driven init can flip it back on for real terminals.
            "listambiguous",
            "listbeep",
            "listtypes",
            "monitor",
            "multibyte",
            "multifuncdef",
            "multios",
            "nomatch",
            "notify",
            "promptcr",
            "promptpercent",
            "promptsp",
            "rcs",
            // SHINSTDIN — same story. Default off; init sets when
            // stdin is the real interactive source.
            "shortloops",
            "unset",
            "zle",
        ];
        for opt in defaults_on {
            opts.insert(opt.to_string(), true);
        }
        opts
    }

    pub(crate) fn default_on_options() -> &'static [&'static str] {
        &[
            "aliases",
            "alwayslastprompt",
            "appendhistory",
            "autolist",
            "automenu",
            "autoparamkeys",
            "autoparamslash",
            "autoremoveslash",
            "badpattern",
            "banghist",
            "bareglobqual",
            "beep",
            "bgnice",
            "caseglob",
            "casematch",
            "checkjobs",
            "checkrunningjobs",
            "clobber",
            "debugbeforecmd",
            "equals",
            "evallineno",
            "exec",
            "flowcontrol",
            "functionargzero",
            "glob",
            "globalexport",
            "globalrcs",
            "hashcmds",
            "hashdirs",
            "hashlistall",
            "histbeep",
            "histsavebycopy",
            "hup",
            // INTERACTIVE / SHINSTDIN intentionally absent — see the
            // matching note in `default_options()` above. C init
            // computes these from isatty(0), not from the static
            // emulation-default table.
            "listambiguous",
            "listbeep",
            "listtypes",
            "monitor",
            "multibyte",
            "multifuncdef",
            "multios",
            "nomatch",
            "notify",
            "promptcr",
            "promptpercent",
            "promptsp",
            "rcs",
            "shortloops",
            "unset",
            "zle",
        ]
    }
}

// =====================================================================
// MOVED FROM: src/ported/options.rs
// =====================================================================

impl crate::ported::exec::ShellExecutor {

}

// =====================================================================
// MOVED FROM: src/ported/params.rs
// =====================================================================

impl crate::ported::exec::ShellExecutor {
    /// Parse subscript range like "1" or "1,5" or "-1" or "1,-1"
    pub(crate) fn parse_subscript_range(&self, s: &str, len: usize) -> Option<(usize, usize)> {
        if s.is_empty() || len == 0 {
            return None;
        }

        let parts: Vec<&str> = s.split(',').collect();

        let parse_idx = |idx_str: &str| -> Option<usize> {
            let idx: i64 = idx_str.trim().parse().ok()?;
            if idx < 0 {
                // Negative index from end
                let abs = (-idx) as usize;
                if abs > len {
                    None
                } else {
                    Some(len - abs)
                }
            } else if idx == 0 {
                Some(0)
            } else {
                // 1-indexed
                Some((idx as usize).saturating_sub(1).min(len))
            }
        };

        match parts.len() {
            1 => {
                // Single element [n]
                let idx = parse_idx(parts[0])?;
                Some((idx, idx + 1))
            }
            2 => {
                // Range [n,m]
                let start = parse_idx(parts[0])?;
                let end = parse_idx(parts[1])?.saturating_add(1);
                Some((start.min(end), start.max(end)))
            }
            _ => None,
        }
    }
    /// Get value from zsh/parameter special arrays (options, commands, functions, etc.)
    /// Returns Some(value) if this is a special array access, None otherwise
    pub fn get_special_array_value(&self, array_name: &str, key: &str) -> Option<String> {
        match array_name {
            // === ZSH/MAPFILE module ===
            // `${mapfile[/path]}` reads the file's contents. Direct
            // port of `getpmmapfile(UNUSED(HashTable ht), const char *name)` (Src/Modules/mapfile.c:217)
            // which calls `get_contents()` (line 167) on the path.
            // Splice (`@`/`*`) returns the CWD entry list per
            // `scanpmmapfile()` (line 240).
            "mapfile" => {
                if key == "@" || key == "*" {
                    // Inline readdir loop — direct port of
                    // scanpmmapfile (Src/Modules/mapfile.c:241).
                    let mut files: Vec<String> = Vec::new();
                    if let Ok(rd) = std::fs::read_dir(".") {
                        for entry in rd.flatten() {
                            let path = entry.path();
                            if path.is_file() {
                                if let Some(name) =
                                    path.file_name().and_then(|n| n.to_str())
                                {
                                    files.push(name.to_string());
                                }
                            }
                        }
                    }
                    return Some(files.join(" "));
                }
                Some(crate::modules::mapfile::get_contents(key).unwrap_or_default())
            }
            // === ZSH/SYSTEM — errnos / sysparams ===
            "errnos" => {
                let table = crate::modules::system::ERRNO_NAMES;
                if key == "@" || key == "*" {
                    return Some(
                        table
                            .iter()
                            .map(|(n, _)| (*n).to_string())
                            .collect::<Vec<_>>()
                            .join(" "),
                    );
                }
                if let Ok(n) = key.parse::<i64>() {
                    let len = table.len() as i64;
                    let pos = if n > 0 {
                        (n - 1) as usize
                    } else if n < 0 {
                        let p = len + n;
                        if p < 0 {
                            return Some(String::new());
                        }
                        p as usize
                    } else {
                        return Some(String::new());
                    };
                    if let Some((name, _)) = table.get(pos) {
                        return Some((*name).to_string());
                    }
                }
                Some(String::new())
            }
            "sysparams" => {
                let pid = std::process::id().to_string();
                let ppid = unsafe { libc::getppid() }.to_string();
                if key == "@" || key == "*" {
                    return Some(format!("{} {}", pid, ppid));
                }
                Some(match key {
                    "pid" => pid,
                    "ppid" => ppid,
                    "procsubstpid" => "0".to_string(),
                    _ => String::new(),
                })
            }
            // === SHELL OPTIONS ===
            "options" => {
                if key == "@" || key == "*" {
                    // Return all options as "name=on/off" pairs.
                    let opts: Vec<String> = crate::ported::options::opt_state_snapshot()
                        .iter()
                        .map(|(k, v)| format!("{}={}", k, if *v { "on" } else { "off" }))
                        .collect();
                    return Some(opts.join(" "));
                }
                let opt_name = key.to_lowercase().replace('_', "");
                let is_on = crate::ported::options::opt_state_get(&opt_name).unwrap_or(false);
                Some(if is_on {
                    "on".to_string()
                } else {
                    "off".to_string()
                })
            }

            // === ALIASES ===
            // ${aliases[@]} returns values in sorted-name order.
            // Iterating HashMap::values() gave random order; tests
            // and prompt code that snapshot ${(v)aliases} flickered.
            "aliases" => {
                // Read from canonical `aliastab` (`Src/hashtable.c:1210`,
                // ported at `src/ported/hashtable.rs::aliastab_lock`).
                // bin_alias writes through `aliastab.add()` — the local
                // `exec.aliases` HashMap is a stale init-time snapshot.
                if let Ok(tab) = crate::ported::hashtable::aliastab_lock().read() {
                    if key == "@" || key == "*" {
                        let mut names: Vec<&String> = tab.iter().map(|(n, _)| n).collect();
                        names.sort();
                        let vals: Vec<String> = names.iter()
                            .filter_map(|n| tab.get(n).map(|a| a.text.clone()))
                            .collect();
                        return Some(vals.join(" "));
                    }
                    return Some(tab.get(key).map(|a| a.text.clone()).unwrap_or_default());
                }
                Some(self.alias(key).unwrap_or_default())
            }
            "galiases" => {
                if key == "@" || key == "*" {
                    let entries = self.global_alias_entries();
                    let vals: Vec<String> = entries.into_iter().map(|(_, v)| v).collect();
                    return Some(vals.join(" "));
                }
                Some(self.global_alias(key).unwrap_or_default())
            }
            "saliases" => {
                if key == "@" || key == "*" {
                    let entries = self.suffix_alias_entries();
                    let vals: Vec<String> = entries.into_iter().map(|(_, v)| v).collect();
                    return Some(vals.join(" "));
                }
                Some(self.suffix_alias(key).unwrap_or_default())
            }

            // === TERMINFO (zsh/terminfo module) ===
            // `${terminfo[capname]}` returns the escape sequence for
            // capability `capname`. Direct port of zsh/Src/Modules/
            // terminfo.c — the C version calls `tigetstr(name)` from
            // ncurses; we map the common-subset capability names to
            // standard xterm/VT escape sequences inline. Covers the
            // function-keys / cursor-motion / clear / color set that
            // user keymaps query (`key[F1]=$terminfo[kf1]` etc.).
            "terminfo" => {
                // Lazy lookup via ncurses tigetstr/tigetnum/tigetflag
                // — the pre-populated assoc init seeds the common
                // subset, but a script may query any cap by name
                // (`$terminfo[acsc]`, `$terminfo[colors]`). Mirror
                // zsh's terminfo.c::getterminfo lazy-resolve path.
                Some(crate::modules::terminfo::getterminfo(key).unwrap_or_default())
            }
            // `termcap` is dispatched in the `magic_assoc_lookup`
            // function (the primary special-array path) so that
            // ${termcap[cl]} resolves before this fallback runs.
            // Keeping a no-op arm here avoids a spurious "unknown
            // assoc" diagnostic if a caller bypasses
            // magic_assoc_lookup.
            "termcap" => Some(crate::modules::termcap::gettermcap(key).unwrap_or_default()),

            // === FUNCTIONS ===
            "functions" => {
                if key == "@" || key == "*" {
                    return Some(self.function_names().join(" "));
                }
                // Apply zsh's getfn_functions formatter — leading-tab
                // body, no trailing `;`. Direct port of Src/exec.c
                // shipped via compile_zsh's fast path; this branch
                // is the slow-path/subst_port entry that previously
                // returned the raw user-typed source. Keeps
                // `${functions[foo]:0:20}` (substring extraction)
                // consistent with the fast-path `\$functions[foo]`.
                let text = self.function_definition_text(key)?;
                let formatted = FuncBodyFmt::render(text.trim());
                Some(format!("\t{}", formatted))
            }
            "functions_source" => {
                // ${functions_source[name]} → file path where the
                // function was defined. zsh/Src/Modules/parameter.c
                // exposes this as an assoc keyed by function name.
                // For autoload functions we recover the source path
                // via the same fpath walk that loads them; for inline
                // functions we don't yet track the defining file, so
                // emit empty in that case.
                // find_function_file deleted with old exec.c stubs.
                if key == "@" || key == "*" {
                    let _ = self.function_names();
                    return Some(String::new());
                }
                { let _ = key; Some(String::new()) }
            }

            // === COMMANDS (command hash table) ===
            // ${commands[name]} → full path (or empty), per
            // zsh/Modules/parameter.c. The @/* expansion enumerates
            // every command on PATH (deduplicated, first-wins).
            "commands" => {
                if key == "@" || key == "*" {
                    let path_var = env::var("PATH").unwrap_or_default();
                    let mut seen: std::collections::HashSet<String> =
                        std::collections::HashSet::new();
                    let mut names: Vec<String> = Vec::new();
                    // Hashed entries first (rehash population) — read
                    // from canonical `cmdnamtab` (Src/exec.c:5260).
                    if let Ok(tab) = crate::ported::hashtable::cmdnamtab_lock().read() {
                        for (k, _) in tab.iter() {
                            if seen.insert(k.clone()) {
                                names.push(k.clone());
                            }
                        }
                    }
                    for dir in path_var.split(':') {
                        if dir.is_empty() {
                            continue;
                        }
                        if let Ok(entries) = std::fs::read_dir(dir) {
                            for entry in entries.flatten() {
                                if let Ok(name) = entry.file_name().into_string() {
                                    if seen.insert(name.clone()) {
                                        names.push(name);
                                    }
                                }
                            }
                        }
                    }
                    names.sort();
                    return Some(names.join(" "));
                }
                if let Some(path) = self.find_in_path(key) {
                    Some(path)
                } else {
                    Some(String::new())
                }
            }

            // === BUILTINS ===
            "builtins" => {
                let builtins: Vec<&str> = crate::exec::BUILTIN_NAMES
                    .iter().map(|s| s.as_str()).collect();
                if key == "@" || key == "*" {
                    return Some(builtins.join(" "));
                }
                if builtins.iter().any(|b| *b == key) {
                    Some("defined".to_string())
                } else {
                    Some(String::new())
                }
            }

            // === PARAMETERS ===
            // ${parameters[name]} → full attribute string per
            // VarAttr::format_zsh (e.g. 'integer-readonly-export').
            // @/* enumerates every parameter name, sorted+deduped.
            "parameters" => {
                if key == "@" || key == "*" {
                    let mut names: std::collections::BTreeSet<String> =
                        if let Ok(tab) = crate::ported::params::paramtab().read() {
                            tab.keys().cloned().collect()
                        } else {
                            std::collections::BTreeSet::new()
                        };
                    if let Ok(m) = crate::ported::params::paramtab_hashed_storage().lock() {
                        names.extend(m.keys().cloned());
                    }
                    let v: Vec<String> = names.into_iter().collect();
                    return Some(v.join(" "));
                }
                // Read PM_TYPE from paramtab Param flags first
                // (canonical). PM_INTEGER → "integer", PM_FFLOAT|
                // PM_EFLOAT → "float", PM_HASHED → "association",
                // PM_ARRAY → "array", scalar default. Append PM_LOWER
                // / PM_UPPER / PM_READONLY / PM_EXPORTED suffixes.
                let flags = self.param_flags(key) as u32;
                if flags != 0 || self.array(key).is_some() || self.assoc(key).is_some() {
                    let base = if flags & PM_INTEGER != 0 { "integer" }
                        else if flags & (PM_EFLOAT | PM_FFLOAT) != 0 { "float" }
                        else if flags & PM_HASHED != 0 || self.assoc(key).is_some() { "association" }
                        else if flags & PM_ARRAY != 0 || self.array(key).is_some() { "array" }
                        else { "scalar" };
                    let mut out = String::from(base);
                    if flags & PM_LEFT != 0 { out.push_str("-left"); }
                    if flags & PM_RIGHT_B != 0 { out.push_str("-right_blanks"); }
                    if flags & PM_RIGHT_Z != 0 { out.push_str("-right_zeros"); }
                    if flags & PM_LOWER != 0 { out.push_str("-lower"); }
                    if flags & PM_UPPER != 0 { out.push_str("-upper"); }
                    if flags & PM_READONLY != 0 { out.push_str("-readonly"); }
                    if flags & PM_EXPORTED != 0 { out.push_str("-export"); }
                    return Some(out);
                }
                if self.has_assoc(key) {
                    Some("association".to_string())
                } else if self.has_array(key) {
                    Some("array".to_string())
                } else if self.has_scalar(key) || std::env::var(key).is_ok() {
                    Some("scalar".to_string())
                } else {
                    Some(String::new())
                }
            }

            // === NAMED DIRECTORIES ===
            // ${nameddirs[@]} returns paths in sorted-name order (was
            // HashMap::values() with random iteration).
            "nameddirs" => {
                // Canonical `nameddirtab` lives in
                // `src/ported/hashnameddir.rs` (port of `Src/hashnameddir.c`).
                let tab = crate::ported::hashnameddir::nameddirtab();
                if key == "@" || key == "*" {
                    let snapshot: Vec<(String, String)> = tab.lock().ok()
                        .map(|g| g.iter().map(|(k, v)| (k.clone(), v.dir.clone())).collect())
                        .unwrap_or_default();
                    let mut keys: Vec<&(String, String)> = snapshot.iter().collect();
                    keys.sort_by(|a, b| a.0.cmp(&b.0));
                    let vals: Vec<String> = keys.iter().map(|(_, v)| v.clone()).collect();
                    return Some(vals.join(" "));
                }
                Some(
                    tab.lock().ok()
                        .and_then(|g| g.get(key).map(|nd| nd.dir.clone()))
                        .unwrap_or_default(),
                )
            }

            // === USER DIRECTORIES ===
            // ${userdirs[name]} → home directory of user `name` per
            // zsh/Modules/parameter.c userdirs_*. With @/* expansion,
            // walk getpwent(3) to enumerate every passwd entry's
            // home directory.
            "userdirs" => {
                #[cfg(unix)]
                {
                    if key == "@" || key == "*" {
                        let mut homes: Vec<String> = Vec::new();
                        unsafe {
                            libc::setpwent();
                            loop {
                                let pwd = libc::getpwent();
                                if pwd.is_null() {
                                    break;
                                }
                                let dir = CStr::from_ptr((*pwd).pw_dir);
                                homes.push(dir.to_string_lossy().to_string());
                            }
                            libc::endpwent();
                        }
                        homes.sort();
                        homes.dedup();
                        return Some(homes.join(" "));
                    }
                    if let Ok(name) = CString::new(key) {
                        unsafe {
                            let pwd = libc::getpwnam(name.as_ptr());
                            if !pwd.is_null() {
                                let dir = CStr::from_ptr((*pwd).pw_dir);
                                return Some(dir.to_string_lossy().to_string());
                            }
                        }
                    }
                }
                Some(String::new())
            }

            // === USER GROUPS ===
            // ${usergroups[name]} → GID of group `name`. With @/*
            // expansion, walk getgrent(3) to enumerate every group's
            // gid.
            "usergroups" => {
                #[cfg(unix)]
                {
                    if key == "@" || key == "*" {
                        let mut gids: Vec<String> = Vec::new();
                        unsafe {
                            libc::setgrent();
                            loop {
                                let grp = libc::getgrent();
                                if grp.is_null() {
                                    break;
                                }
                                let name = CStr::from_ptr((*grp).gr_name);
                                gids.push(name.to_string_lossy().to_string());
                            }
                            libc::endgrent();
                        }
                        gids.sort();
                        gids.dedup();
                        return Some(gids.join(" "));
                    }
                    if let Ok(name) = CString::new(key) {
                        unsafe {
                            let grp = libc::getgrnam(name.as_ptr());
                            if !grp.is_null() {
                                return Some((*grp).gr_gid.to_string());
                            }
                        }
                    }
                }
                Some(String::new())
            }

            // === DIRECTORY STACK ===
            // Canonical `dirstack` lives in `modules/parameter.rs::DIRSTACK`
            // — mirror of the C `dirstack` global (`Src/builtin.c:1456`).
            "dirstack" => {
                let dirs = crate::ported::modules::parameter::DIRSTACK
                    .lock()
                    .map(|g| g.clone())
                    .unwrap_or_default();
                if key == "@" || key == "*" {
                    return Some(dirs.join(" "));
                }
                if let Ok(idx) = key.parse::<usize>() {
                    Some(dirs.get(idx).cloned().unwrap_or_default())
                } else {
                    Some(String::new())
                }
            }

            // === JOBS ===
            "jobstates" => {
                if key == "@" || key == "*" {
                    let states: Vec<String> = self
                        .jobs
                        .iter()
                        .map(|(id, job)| format!("{}:{:?}", id, job.state))
                        .collect();
                    return Some(states.join(" "));
                }
                if let Ok(id) = key.parse::<usize>() {
                    if let Some(job) = self.jobs.get(id) {
                        return Some(format!("{:?}", job.state));
                    }
                }
                Some(String::new())
            }
            "jobtexts" => {
                if key == "@" || key == "*" {
                    let texts: Vec<String> = self
                        .jobs
                        .iter()
                        .map(|(_, job)| job.command.clone())
                        .collect();
                    return Some(texts.join(" "));
                }
                if let Ok(id) = key.parse::<usize>() {
                    if let Some(job) = self.jobs.get(id) {
                        return Some(job.command.clone());
                    }
                }
                Some(String::new())
            }
            "jobdirs" => {
                // ${jobdirs[N]}: cwd at the time job N was launched.
                // We don't yet capture per-job cwd at launch (would
                // need a JobInfo.cwd field plumbed through add_job),
                // so use the current PWD as a best-effort proxy. With
                // @/* expansion, return one entry per active job so
                // arr-length math (${#jobdirs}) matches ${#jobtexts}.
                let pwd = self
                    .scalar("PWD")
                    .or_else(|| env::var("PWD").ok())
                    .unwrap_or_default();
                if key == "@" || key == "*" {
                    let n = self.jobs.iter().count();
                    return Some(vec![pwd; n].join(" "));
                }
                if let Ok(id) = key.parse::<usize>() {
                    if self.jobs.get(id).is_some() {
                        return Some(pwd);
                    }
                }
                Some(String::new())
            }

            // === HISTORY ===
            "history" => {
                if key == "@" || key == "*" {
                    // Return recent history
                    if let Some(ref engine) = self.history {
                        if let Ok(entries) = engine.recent(100) {
                            let cmds: Vec<String> =
                                entries.iter().map(|e| e.command.clone()).collect();
                            return Some(cmds.join("\n"));
                        }
                    }
                    return Some(String::new());
                }
                if let Ok(num) = key.parse::<usize>() {
                    if let Some(ref engine) = self.history {
                        if let Ok(Some(entry)) = engine.get_by_offset(num.saturating_sub(1)) {
                            return Some(entry.command);
                        }
                    }
                }
                Some(String::new())
            }
            "historywords" => {
                // $historywords: flat list of words from recent history
                // entries (zsh/Modules/parameter.c historywords_*).
                // Each command is split on whitespace; the words are
                // collected newest-first across the recent window.
                if let Some(ref engine) = self.history {
                    if let Ok(entries) = engine.recent(100) {
                        let words: Vec<String> = entries
                            .iter()
                            .flat_map(|e| {
                                e.command
                                    .split_whitespace()
                                    .map(|s| s.to_string())
                                    .collect::<Vec<_>>()
                            })
                            .collect();
                        if key == "@" || key == "*" {
                            return Some(words.join(" "));
                        }
                        if let Ok(idx) = key.parse::<usize>() {
                            if idx >= 1 && idx <= words.len() {
                                return Some(words[idx - 1].clone());
                            }
                        }
                    }
                }
                Some(String::new())
            }

            // === MODULES ===
            // ${modules[name]} → "loaded" / "" per
            // zsh/Src/Modules/parameter.c modules_*. zshrs tracks
            // loaded modules via `_module_<name>` keys in
            // self.options (see bin_zmodload). Always-loaded
            // built-in modules are surfaced unconditionally so
            // compsys's `[[ ${+modules[zsh/zutil]} ]]` gating works.
            "modules" => {
                const ALWAYS_LOADED: &[&str] = &[
                    "zsh/parameter",
                    "zsh/zutil",
                    "zsh/complete",
                    "zsh/complist",
                    "zsh/zle",
                    "zsh/main",
                    "zsh/files",
                ];
                let user_loaded: Vec<String> = crate::ported::options::opt_state_snapshot()
                    .iter()
                    .filter_map(|(k, v)| {
                        if *v {
                            k.strip_prefix("_module_").map(|s| s.to_string())
                        } else {
                            None
                        }
                    })
                    .collect();
                if key == "@" || key == "*" {
                    let mut all: Vec<String> = ALWAYS_LOADED
                        .iter()
                        .map(|s| s.to_string())
                        .chain(user_loaded.iter().cloned())
                        .collect();
                    all.sort();
                    all.dedup();
                    return Some(all.join(" "));
                }
                if ALWAYS_LOADED.contains(&key)
                    || crate::ported::options::opt_state_get(&format!("_module_{}", key))
                        .unwrap_or(false)
                {
                    Some("loaded".to_string())
                } else {
                    Some(String::new())
                }
            }

            // === RESERVED WORDS ===
            "reswords" => {
                let reswords = [
                    "do",
                    "done",
                    "esac",
                    "then",
                    "elif",
                    "else",
                    "fi",
                    "for",
                    "case",
                    "if",
                    "while",
                    "function",
                    "repeat",
                    "time",
                    "until",
                    "select",
                    "coproc",
                    "nocorrect",
                    "foreach",
                    "end",
                    "in",
                ];
                if key == "@" || key == "*" {
                    return Some(reswords.join(" "));
                }
                if let Ok(idx) = key.parse::<usize>() {
                    Some(reswords.get(idx).map(|s| s.to_string()).unwrap_or_default())
                } else {
                    Some(String::new())
                }
            }

            // === PATCHARS (characters with special meaning in patterns) ===
            "patchars" => {
                let patchars = ["?", "*", "[", "]", "^", "#", "~", "(", ")", "|"];
                if key == "@" || key == "*" {
                    return Some(patchars.join(" "));
                }
                if let Ok(idx) = key.parse::<usize>() {
                    Some(patchars.get(idx).map(|s| s.to_string()).unwrap_or_default())
                } else {
                    Some(String::new())
                }
            }

            // === FUNCTION CALL STACK ===
            // $funcstack: array of function names in the current call
            // chain (innermost first). Already maintained by the
            // function-call code at exec.rs:7828-7835. Surface it here
            // so `${funcstack[1]}` / `${funcstack[@]}` reads work.
            // funcfiletrace / funcsourcetrace need separate tables (file
            // and definition tracking) which we don't yet wire; emit
            // empty for those until they're populated.
            "funcstack" => {
                if let Some(stack) = self.array("funcstack") {
                    if key == "@" || key == "*" {
                        return Some(stack.join(" "));
                    }
                    if let Ok(idx) = key.parse::<usize>() {
                        // zsh subscripts are 1-based.
                        if idx >= 1 && idx <= stack.len() {
                            return Some(stack[idx - 1].clone());
                        }
                    }
                }
                Some(String::new())
            }
            "functrace" => {
                // $functrace: `caller_name:callsite_lineno` for each
                // frame. We don't yet track call-site line numbers, so
                // synthesize from funcstack with a `:0` placeholder
                // line. This still lets scripts that test
                // `[[ -n $functrace[1] ]]` work without false-empty.
                if let Some(stack) = self.array("funcstack") {
                    let synth: Vec<String> = stack.iter().map(|n| format!("{}:0", n)).collect();
                    if key == "@" || key == "*" {
                        return Some(synth.join(" "));
                    }
                    if let Ok(idx) = key.parse::<usize>() {
                        if idx >= 1 && idx <= synth.len() {
                            return Some(synth[idx - 1].clone());
                        }
                    }
                }
                Some(String::new())
            }
            "funcfiletrace" | "funcsourcetrace" => {
                // Would need file:line where each function was called
                // from / defined in. Per-frame file tracking is not yet
                // wired — return empty.
                Some(String::new())
            }

            // === DISABLED VARIANTS (dis_*) ===
            // ${dis_builtins[name]} → "defined" if the builtin was
            // disabled via `disable name`. Tracked through
            // self.options['_disabled_<name>']. The other dis_*
            // variants (aliases/functions/reswords/patchars) lose
            // their entries entirely on disable in zshrs's table
            // model (see do_enable_disable at exec.rs:31371) so the
            // disabled list isn't recoverable post-disable; emit
            // empty for those.
            "dis_builtins" => {
                let disabled: Vec<String> = crate::ported::options::opt_state_snapshot()
                    .iter()
                    .filter_map(|(k, v)| {
                        if *v {
                            k.strip_prefix("_disabled_").map(|s| s.to_string())
                        } else {
                            None
                        }
                    })
                    .collect();
                if key == "@" || key == "*" {
                    let mut sorted = disabled.clone();
                    sorted.sort();
                    return Some(sorted.join(" "));
                }
                if disabled.iter().any(|d| d == key) {
                    Some("defined".to_string())
                } else {
                    Some(String::new())
                }
            }
            "dis_aliases"
            | "dis_galiases"
            | "dis_saliases"
            | "dis_functions"
            | "dis_functions_source"
            | "dis_reswords"
            | "dis_patchars" => Some(String::new()),

            // === ZLE WIDGETS ===
            // ${widgets[name]} → widget-type prefix per
            // zsh/Src/Zle/zleparameter.c widgets_*: "builtin",
            // "user:<funcname>", or "completion:<funcname>".
            // Distinguishes builtin vs user-defined so
            // ${(t)widgets[name]} works.
            "widgets" => {
                if key == "@" || key == "*" {
                    let mut names = listwidgets();
                    names.sort();
                    return Some(names.join(" "));
                }
                if let Some(target) = getwidgettarget(key) {
                    if target == key {
                        Some("builtin".to_string())
                    } else {
                        Some(format!("user:{}", target))
                    }
                } else {
                    Some(String::new())
                }
            }

            // === ZLE KEYMAPS ===
            // ${keymaps[N]} per zleparameter.c keymaps_*: list of
            // available keymap names. Single-key lookup returns 1
            // ("set") if the keymap exists, "" otherwise.
            "keymaps" => {
                const KEYMAPS: &[&str] = &[
                    "main",
                    "emacs",
                    "viins",
                    "vicmd",
                    "isearch",
                    "command",
                    "menuselect",
                ];
                if key == "@" || key == "*" {
                    return Some(KEYMAPS.join(" "));
                }
                if KEYMAPS.contains(&key) {
                    Some("1".to_string())
                } else {
                    Some(String::new())
                }
            }

            // === SIGNAL NAMES ===
            // $signals: array indexed by signal number (1-based) where
            // each slot holds the bare signal name. Direct port of
            // zsh/Modules/parameter.c signals_*. zshrs uses libc signal
            // constants so the mapping matches the host platform
            // (macOS USR1=30, Linux USR1=10).
            "signals" => {
                let map: &[(i32, &str)] = &[
                    (libc::SIGHUP, "HUP"),
                    (libc::SIGINT, "INT"),
                    (libc::SIGQUIT, "QUIT"),
                    (libc::SIGILL, "ILL"),
                    (libc::SIGTRAP, "TRAP"),
                    (libc::SIGABRT, "ABRT"),
                    #[cfg(target_os = "macos")]
                    (libc::SIGEMT, "EMT"),
                    (libc::SIGFPE, "FPE"),
                    (libc::SIGKILL, "KILL"),
                    (libc::SIGBUS, "BUS"),
                    (libc::SIGSEGV, "SEGV"),
                    (libc::SIGSYS, "SYS"),
                    (libc::SIGPIPE, "PIPE"),
                    (libc::SIGALRM, "ALRM"),
                    (libc::SIGTERM, "TERM"),
                    (libc::SIGURG, "URG"),
                    (libc::SIGSTOP, "STOP"),
                    (libc::SIGTSTP, "TSTP"),
                    (libc::SIGCONT, "CONT"),
                    (libc::SIGCHLD, "CHLD"),
                    (libc::SIGTTIN, "TTIN"),
                    (libc::SIGTTOU, "TTOU"),
                    (libc::SIGIO, "IO"),
                    (libc::SIGXCPU, "XCPU"),
                    (libc::SIGXFSZ, "XFSZ"),
                    (libc::SIGVTALRM, "VTALRM"),
                    (libc::SIGPROF, "PROF"),
                    (libc::SIGWINCH, "WINCH"),
                    #[cfg(target_os = "macos")]
                    (libc::SIGINFO, "INFO"),
                    (libc::SIGUSR1, "USR1"),
                    (libc::SIGUSR2, "USR2"),
                ];
                if key == "@" || key == "*" {
                    // Return one entry per signal in numeric order (1..N).
                    let max = map.iter().map(|(n, _)| *n).max().unwrap_or(0) as usize;
                    let mut slots: Vec<String> = vec![String::new(); max];
                    for (n, name) in map {
                        if (*n as usize) >= 1 && (*n as usize) <= max {
                            slots[*n as usize - 1] = (*name).to_string();
                        }
                    }
                    return Some(slots.join(" "));
                }
                // Numeric subscript -> name; name -> empty (zsh's
                // $signals is keyed by number).
                if let Ok(n) = key.parse::<i32>() {
                    for (sig_num, name) in map {
                        if *sig_num == n {
                            return Some((*name).to_string());
                        }
                    }
                }
                Some(String::new())
            }

            // Not a special array
            _ => None,
        }
    }
    pub(crate) fn get_variable(&self, name: &str) -> String {
        // Handle special parameters
        match name {
            "" => String::new(), // Empty name returns empty
            "$" => std::process::id().to_string(),
            "@" | "*" => {
                // $* joins by the first char of $IFS (POSIX). Default
                // IFS is " \t\n\0" so the join char is " "; with a
                // custom IFS like `:` the joined string uses `:`.
                // $@ technically does the same in scalar context but
                // is usually quoted-spliced — both fall through here.
                let sep = self
                    .scalar("IFS")
                    .and_then(|s| s.chars().next())
                    .unwrap_or(' ');
                self.pparams().join(&sep.to_string())
            }
            "#" | "#@" | "#*" => self.pparams().len().to_string(),
            // zsh alias: $ARGC also equals $#.
            "ARGC" => self.pparams().len().to_string(),
            "?" | "status" => self.last_status().to_string(),
            "!" => self
                .scalar("!")
                .unwrap_or_else(|| "0".to_string()),
            // `$-` returns the concatenated single-letter flags of options
            // currently set. zsh always emits a baseline "569X" prefix
            // (internal-letter options that are on by default in -f mode)
            // followed by user-controllable flags. Match the prefix
            // verbatim so existing scripts that do `[[ $- == *e* ]]` /
            // `case $- in *x*) … esac` see consistent letters.
            "-" => {
                let mut letters = String::from("569X");
                let opt = |n: &str| crate::ported::options::opt_state_get(n).unwrap_or(false);
                // `e` comes BEFORE `f` in zsh's letter ordering: `set -e`
                // in -f mode produces "569Xef", not "569Xfe".
                if opt("errexit") {
                    letters.push('e');
                }
                if !opt("rcs") {
                    letters.push('f');
                }
                if opt("login") {
                    letters.push('l');
                }
                // i/m are present only when *truly* interactive; zsh's `-c`
                // path leaves them off, so we mirror that and don't surface
                // them just because `options.interactive` happens to be set
                // by the executor's default-options init.
                if opt("nounset") {
                    letters.push('u');
                }
                if opt("xtrace") {
                    letters.push('x');
                }
                if opt("verbose") {
                    letters.push('v');
                }
                if opt("noexec") {
                    letters.push('n');
                }
                if opt("hashall") {
                    letters.push('h');
                }
                letters
            }
            "EUID" => unsafe { libc::geteuid() }.to_string(),
            "UID" => unsafe { libc::getuid() }.to_string(),
            "EGID" => unsafe { libc::getegid() }.to_string(),
            "GID" => unsafe { libc::getgid() }.to_string(),
            "PPID" => unsafe { libc::getppid() }.to_string(),
            "ZSH_SUBSHELL" => self
                .scalar("ZSH_SUBSHELL")
                .unwrap_or_else(|| "0".to_string()),
            "HOST" => {
                // libc gethostname → up to 256 bytes.
                let mut buf = [0u8; 256];
                let r = unsafe { libc::gethostname(buf.as_mut_ptr() as *mut _, buf.len()) };
                if r == 0 {
                    let nul = buf.iter().position(|&b| b == 0).unwrap_or(buf.len());
                    String::from_utf8_lossy(&buf[..nul]).into_owned()
                } else {
                    String::new()
                }
            }
            // OS / machine identity vars. zsh hardcodes these from build-time
            // detection; we synthesize at runtime from libc uname(). Without
            // these arms `$OSTYPE` returned empty even though zle_params wrote
            // them into the params table — the executor's get_variable bypasses
            // that table for special names.
            "OSTYPE" => {
                let mut u: libc::utsname = unsafe { std::mem::zeroed() };
                if unsafe { libc::uname(&mut u) } == 0 {
                    let sysname = unsafe { std::ffi::CStr::from_ptr(u.sysname.as_ptr()) }
                        .to_string_lossy()
                        .to_lowercase();
                    let release = unsafe { std::ffi::CStr::from_ptr(u.release.as_ptr()) }
                        .to_string_lossy()
                        .to_string();
                    format!("{}{}", sysname, release)
                } else {
                    std::env::consts::OS.to_string()
                }
            }
            "MACHTYPE" => {
                let mut u: libc::utsname = unsafe { std::mem::zeroed() };
                if unsafe { libc::uname(&mut u) } == 0 {
                    let m = unsafe { std::ffi::CStr::from_ptr(u.machine.as_ptr()) }
                        .to_string_lossy()
                        .to_string();
                    // zsh shortens common machines: aarch64 → arm, x86_64
                    // stays x86_64. Mirror that for the common cases.
                    if m == "aarch64" || m == "arm64" {
                        "arm".to_string()
                    } else {
                        m
                    }
                } else {
                    std::env::consts::ARCH.to_string()
                }
            }
            "CPUTYPE" => {
                let mut u: libc::utsname = unsafe { std::mem::zeroed() };
                if unsafe { libc::uname(&mut u) } == 0 {
                    unsafe { std::ffi::CStr::from_ptr(u.machine.as_ptr()) }
                        .to_string_lossy()
                        .to_string()
                } else {
                    std::env::consts::ARCH.to_string()
                }
            }
            "VENDOR" => {
                // No portable libc query for vendor; pick by OS family.
                if cfg!(target_os = "macos") {
                    "apple".to_string()
                } else if cfg!(target_os = "linux") {
                    "unknown".to_string()
                } else {
                    "pc".to_string()
                }
            }
            "HOSTNAME" => {
                let mut buf = [0u8; 256];
                let r = unsafe { libc::gethostname(buf.as_mut_ptr() as *mut _, buf.len()) };
                if r == 0 {
                    let nul = buf.iter().position(|&b| b == 0).unwrap_or(buf.len());
                    String::from_utf8_lossy(&buf[..nul]).into_owned()
                } else {
                    String::new()
                }
            }
            "RANDOM" => {
                // zsh/bash: pseudo-random unsigned 16-bit integer per
                // expansion. We use process+nano for a cheap, OS-portable
                // source — not cryptographically secure, but matches zsh's
                // "noise" semantics.
                let nanos = SystemTime::now()
                    .duration_since(UNIX_EPOCH)
                    .map(|d| d.subsec_nanos() as u64)
                    .unwrap_or(0);
                let pid = std::process::id() as u64;
                let r = (nanos.wrapping_mul(2654435761).wrapping_add(pid)) as u32;
                ((r as u16) & 0x7fff).to_string()
            }
            "SECONDS" => {
                // Seconds since shell start. We approximate via the
                // tracked `shell_start_time` if present; otherwise 0.
                crate::ported::params::getsparam("SECONDS").unwrap_or_else(|| {
                    let now = SystemTime::now()
                        .duration_since(UNIX_EPOCH)
                        .map(|d| d.as_secs())
                        .unwrap_or(0);
                    let start = self
                        .scalar("__zshrs_start_secs")
                        .and_then(|s| s.parse::<u64>().ok())
                        .unwrap_or(now);
                    now.saturating_sub(start).to_string()
                })
            }
            "EPOCHSECONDS" => {
                SystemTime::now()
                    .duration_since(UNIX_EPOCH)
                    .map(|d| d.as_secs().to_string())
                    .unwrap_or_else(|_| "0".to_string())
            }
            "EPOCHREALTIME" => {
                // zsh/datetime: fractional seconds since the epoch with
                // microsecond resolution. Format: SECS.UUUUUU.
                match SystemTime::now().duration_since(UNIX_EPOCH) {
                    Ok(d) => format!("{}.{:06}", d.as_secs(), d.subsec_micros()),
                    Err(_) => "0.000000".to_string(),
                }
            }
            "argv" => self.pparams().join(" "),
            "HISTCMD" => {
                // zsh: HISTCMD = current history-event number. With -f
                // (no rc loading) and history-tracking off, zsh shows
                // 0. We mirror by returning the current session count
                // (or 0 when history isn't engaged).
                self.session_history_ids.len().to_string()
            }
            "TTY" => {
                // Path to the controlling terminal (`$TTY` in zsh).
                // ttyname(0) gives the device path. Returns "" if no tty.
                let ptr = unsafe { libc::ttyname(0) };
                if ptr.is_null() {
                    String::new()
                } else {
                    unsafe { std::ffi::CStr::from_ptr(ptr) }
                        .to_string_lossy()
                        .into_owned()
                }
            }
            "TTYIDLE" => {
                // Idle time of stdin TTY in seconds — stat the tty, return
                // (now - st_atime). Returns "-1" if not a tty per zsh docs.
                let ptr = unsafe { libc::ttyname(0) };
                if ptr.is_null() {
                    return "-1".to_string();
                }
                let path = unsafe { std::ffi::CStr::from_ptr(ptr) };
                let path_str = path.to_string_lossy().into_owned();
                match std::fs::metadata(&path_str) {
                    Ok(meta) => {
                        if let Ok(atime) = meta.accessed() {
                            let now = SystemTime::now();
                            let idle = now.duration_since(atime).unwrap_or_default();
                            return idle.as_secs().to_string();
                        }
                        "0".to_string()
                    }
                    Err(_) => "-1".to_string(),
                }
            }
            "TRY_BLOCK_ERROR" => {
                // Set by `{ … } always { … }` — last status of the try
                // block. Lives in self.variables under the same name when
                // the try arm assigns it; default 0.
                self.scalar("TRY_BLOCK_ERROR")
                    .unwrap_or_else(|| "0".to_string())
            }
            "patchars" => "*?[]<>(){}|^&;".to_string(),
            "RANDOM_FILE" => {
                // Path to entropy source. Mainline zsh leaves empty
                // unless `zmodload zsh/random` set it; we expose
                // /dev/urandom as a useful default — matches the
                // platform's actual entropy source.
                if std::path::Path::new("/dev/urandom").exists() {
                    "/dev/urandom".to_string()
                } else {
                    String::new()
                }
            }
            "LINENO" => {
                // Tracked elsewhere; default to 1 if not populated.
                self.scalar("LINENO")
                    .unwrap_or_else(|| "1".to_string())
            }
            "0" => self
                .scalar("0")
                .unwrap_or_else(|| env::args().next().unwrap_or_default()),
            n if !n.is_empty() && n.chars().all(|c| c.is_ascii_digit()) => {
                let idx: usize = n.parse().unwrap_or(0);
                if idx == 0 {
                    env::args().next().unwrap_or_default()
                } else {
                    self.pparams()
                        .get(idx - 1)
                        .cloned()
                        .unwrap_or_default()
                }
            }
            _ => {
                // Bare-assoc bypass: `declare -A h; h=(a 1 b 2); ${h}`
                // expects the joined values. The `declare -A` sets
                // variables["h"]="" as a side effect, which would
                // satisfy the variables lookup with empty. Skip the
                // variables lookup when an assoc with the same name
                // exists AND has entries.
                let assoc_has_entries = self
                    .assoc(name)
                    .map(|h| !h.is_empty())
                    .unwrap_or(false);
                // GSU dispatch first — `$USERNAME` / `$IFS` / `$HOME`
                // / etc. route through their getfn callback. Mirrors
                // C zsh's `Param.gsu->getfn` lookup. Without this,
                // get_variable bypassed the GSU table entirely and
                // returned empty for usernamegetfn-backed reads.
                let resolved = lookup_special_var(name)
                    .or_else(|| {
                        if !assoc_has_entries {
                            crate::ported::params::getsparam(name)
                        } else {
                            None
                        }
                    })
                    .or_else(|| self.array(name).map(|a| a.join(" ")))
                    .or_else(|| {
                        self.assoc(name).map(|h| {
                            if h.is_empty() {
                                String::new()
                            } else {
                                h.values().cloned().collect::<Vec<_>>().join(" ")
                            }
                        })
                    })
                    .or_else(|| env::var(name).ok());
                match resolved {
                    Some(v) => v,
                    None => {
                        // zsh stores the option as "unset" (default ON =
                        // silently empty). `set -u` / `setopt nounset` /
                        // `set -o nounset` all turn it OFF. Different
                        // code paths in zshrs persist either key, so
                        // honor either signal.
                        let nounset_on = crate::ported::options::opt_state_get("nounset").unwrap_or(false)
                            || !crate::ported::options::opt_state_get("unset").unwrap_or(true);
                        if nounset_on {
                            zerr(&format!("{}: parameter not set", name));
                            std::process::exit(1);
                        }
                        String::new()
                    }
                }
            }
        }
    }
    pub(crate) fn pre_resolve_array_subscripts(&self, expr: &str) -> String {
        let bytes: Vec<char> = expr.chars().collect();
        let mut out = String::with_capacity(expr.len());
        let mut i = 0;
        while i < bytes.len() {
            let c = bytes[i];
            // `$@`, `$*`, `$NAME` followed by `[…]` — zinit's
            // `(( $@[(I)-*] ))` and similar arith uses this. Strip
            // the leading `$` and route through the same name+[key]
            // resolver as bare identifiers. Without this the `$@`
            // gets variable-expanded to its joined form before
            // arith eval, dropping the subscript flag entirely.
            if c == '$' && i + 1 < bytes.len() {
                let next = bytes[i + 1];
                let is_special_at = next == '@' || next == '*';
                let is_ident_start = next.is_ascii_alphabetic() || next == '_';
                if (is_special_at || is_ident_start) && i + 2 < bytes.len() {
                    // Look-ahead: must be followed by `[` to qualify
                    // as a subscript form. Bare `$@` without `[` is
                    // left alone (downstream substitution handles it).
                    let mut probe = i + 1;
                    if is_special_at {
                        probe += 1;
                    } else {
                        while probe < bytes.len()
                            && (bytes[probe].is_ascii_alphanumeric() || bytes[probe] == '_')
                        {
                            probe += 1;
                        }
                    }
                    if probe < bytes.len() && bytes[probe] == '[' {
                        // Drop the `$` and re-enter the bare-ident
                        // path on the next iteration.
                        i += 1;
                        continue;
                    }
                }
            }
            // Identifier start?
            if c.is_ascii_alphabetic() || c == '_' || c == '@' || c == '*' {
                let start = i;
                i += 1;
                if !(bytes[start] == '@' || bytes[start] == '*') {
                    while i < bytes.len() && (bytes[i].is_ascii_alphanumeric() || bytes[i] == '_') {
                        i += 1;
                    }
                }
                let name: String = bytes[start..i].iter().collect();
                if i < bytes.len() && bytes[i] == '[' {
                    // Collect balanced [...]
                    i += 1;
                    let key_start = i;
                    let mut depth = 1;
                    while i < bytes.len() && depth > 0 {
                        match bytes[i] {
                            '[' => depth += 1,
                            ']' => {
                                depth -= 1;
                                if depth == 0 {
                                    break;
                                }
                            }
                            _ => {}
                        }
                        i += 1;
                    }
                    let key_str: String = bytes[key_start..i].iter().collect();
                    if i < bytes.len() {
                        i += 1; // skip closing ]
                    }
                    // Resolve sub-key (it may itself be an arith expr or
                    // string literal); strip surrounding quotes and
                    // expand $-refs.
                    let key_resolved: String = if key_str.starts_with('"') && key_str.ends_with('"')
                        || key_str.starts_with('\'') && key_str.ends_with('\'')
                    {
                        key_str[1..key_str.len() - 1].to_string()
                    } else {
                        key_str.clone()
                    };
                    // Subscript-flag form `(I)pat` / `(i)pat` etc. —
                    // route through array_subscript_flag so zinit's
                    // `(( $@[(I)-*] ))` and `(( OPTS[opt_-h,…] ))`
                    // patterns yield an index/key as zsh does.
                    let trimmed_key = key_resolved.trim_start();
                    let resolved = if trimmed_key.starts_with('(') {
                        // getarg with the right storage gives back the
                        // matched value or the all-matches join — see
                        // params.c:1581-1719 inside getarg.
                        let scalar_val = crate::ported::params::getsparam(&name);
                        let result = if let Some(assoc) = self.assoc(&name) {
                            getarg(trimmed_key, None, Some(&assoc), None)
                        } else if name == "@" || name == "*" {
                            let pos = self.pparams();
                            getarg(trimmed_key, Some(&pos), None, None)
                        } else if let Some(arr) = self.array(&name) {
                            getarg(trimmed_key, Some(&arr), None, None)
                        } else if let Some(ref s) = scalar_val {
                            getarg(trimmed_key, None, None, Some(s.as_str()))
                        } else {
                            None
                        };
                        match result {
                            Some(getarg_out::Value(v)) => v.to_str(),
                            _ => "0".to_string(),
                        }
                    } else if let Some(assoc) = self.assoc(&name) {
                        assoc
                            .get(&key_resolved)
                            .cloned()
                            .unwrap_or_else(|| "0".to_string())
                    } else if let Some(arr) = self.array(&name) {
                        // Numeric subscript — can be a literal or an
                        // expression. For simple int literals only here;
                        // complex exprs are uncommon in real scripts.
                        if let Ok(idx) = key_resolved.trim().parse::<i64>() {
                            let len = arr.len() as i64;
                            let pos = if idx < 0 { len + idx } else { idx - 1 };
                            if pos >= 0 && (pos as usize) < arr.len() {
                                arr[pos as usize].clone()
                            } else {
                                "0".to_string()
                            }
                        } else {
                            "0".to_string()
                        }
                    } else {
                        // Unrecognised — emit the original text so the
                        // evaluator can complain naturally.
                        format!("{}[{}]", name, key_str)
                    };
                    out.push_str(&resolved);
                } else {
                    out.push_str(&name);
                }
                continue;
            }
            out.push(c);
            i += 1;
        }
        out
    }
}

// =====================================================================
// MOVED FROM: src/ported/hist.rs
// =====================================================================

impl crate::ported::exec::ShellExecutor {
    /// Split a command string into words for word designators, respecting quotes.
    pub(crate) fn history_split_words(cmd: &str) -> Vec<String> {
        let mut words = Vec::new();
        let mut current = String::new();
        let mut in_sq = false;
        let mut in_dq = false;
        let mut escaped = false;

        for c in cmd.chars() {
            if escaped {
                current.push(c);
                escaped = false;
                continue;
            }
            if c == '\\' {
                current.push(c);
                escaped = true;
                continue;
            }
            if c == '\'' && !in_dq {
                in_sq = !in_sq;
                current.push(c);
                continue;
            }
            if c == '"' && !in_sq {
                in_dq = !in_dq;
                current.push(c);
                continue;
            }
            if c.is_whitespace() && !in_sq && !in_dq {
                if !current.is_empty() {
                    words.push(std::mem::take(&mut current));
                }
                continue;
            }
            current.push(c);
        }
        if !current.is_empty() {
            words.push(current);
        }
        words
    }
    /// Parse a word range like 0, 1, ^, $, *, n-m, n-
    pub(crate) fn history_parse_word_range(
        &self,
        chars: &[char],
        mut i: usize,
        argc: usize,
    ) -> (Option<usize>, Option<usize>, usize) {
        if i >= chars.len() {
            return (None, None, i);
        }

        // Check for modifiers that aren't word designators
        match chars[i] {
            'h' | 't' | 'r' | 'e' | 's' | 'S' | 'g' | 'p' | 'q' | 'Q' | 'l' | 'u' | 'a' | 'A'
            | '&' => {
                // This is a modifier, not a word designator — back up
                return (None, None, i - 1); // -1 to re-read the ':'
            }
            _ => {}
        }

        let farg = if chars[i] == '^' {
            i += 1;
            Some(1usize)
        } else if chars[i] == '$' {
            i += 1;
            return (Some(argc), Some(argc), i);
        } else if chars[i] == '*' {
            i += 1;
            return (Some(1), Some(argc), i);
        } else if chars[i].is_ascii_digit() {
            let start = i;
            while i < chars.len() && chars[i].is_ascii_digit() {
                i += 1;
            }
            let n: usize = chars[start..i]
                .iter()
                .collect::<String>()
                .parse()
                .unwrap_or(0);
            Some(n)
        } else {
            None
        };

        // Check for range: n-m or n-
        if i < chars.len() && chars[i] == '-' {
            i += 1;
            if i < chars.len() && chars[i] == '$' {
                i += 1;
                return (farg, Some(argc), i);
            } else if i < chars.len() && chars[i].is_ascii_digit() {
                let start = i;
                while i < chars.len() && chars[i].is_ascii_digit() {
                    i += 1;
                }
                let m: usize = chars[start..i]
                    .iter()
                    .collect::<String>()
                    .parse()
                    .unwrap_or(0);
                return (farg, Some(m), i);
            } else {
                // n- means n to argc-1
                return (farg, Some(argc.saturating_sub(1)), i);
            }
        }

        if farg.is_some() {
            (farg, farg, i)
        } else {
            (None, None, i)
        }
    }
}

// =====================================================================
// MOVED FROM: src/ported/signals.rs
// =====================================================================

impl crate::ported::exec::ShellExecutor {
    /// Execute trap handlers for a signal
    pub fn run_trap(&mut self, signal: &str) {
        if let Some(action) = self.traps.get(signal).cloned() {
            // Empty action = signal-ignore. Don't try to execute "".
            if !action.is_empty() {
                let _ = self.execute_script(&action);
            }
        }
    }
}

// =====================================================================
// MOVED FROM: src/ported/prompt.rs
// =====================================================================

impl crate::ported::exec::ShellExecutor {
    /// Expand prompt escape sequences using the full prompt module.
    /// `expand_prompt` itself now reads C globals (paramtab / LASTVAL /
    /// curhist / JOBTAB / scriptname) so no per-executor sync is
    /// needed — the executor's state already mirrors those globals.
    pub(crate) fn expand_prompt_string(&self, s: &str) -> String {
        expand_prompt(s)
    }
    pub(crate) fn apply_prompt_theme(&mut self, theme: &str, preview: bool) {
        let (ps1, rps1) = match theme {
            "minimal" => ("%# ", ""),
            "off" => ("$ ", ""),
            "adam1" => (
                "%B%F{cyan}%n@%m %F{blue}%~%f%b %# ",
                "%F{yellow}%D{%H:%M}%f",
            ),
            "redhat" => ("[%n@%m %~]$ ", ""),
            _ => ("%n@%m %~ %# ", ""),
        };
        if preview {
            println!("PS1={:?}", ps1);
            println!("RPS1={:?}", rps1);
        } else {
            self.set_scalar("PS1".to_string(), ps1.to_string());
            self.set_scalar("RPS1".to_string(), rps1.to_string());
            self.set_scalar("prompt_theme".to_string(), theme.to_string());
        }
    }
}

// =====================================================================
// MOVED FROM: src/ported/glob.rs
// =====================================================================

impl crate::ported::exec::ShellExecutor {
    /// Expand glob pattern to matching files
    pub fn expand_glob(&self, pattern: &str) -> Vec<String> {
        // Glob alternation `(a|b|c)` is a primary zsh feature
        // (no extendedglob needed, unlike `~` exclusion). Direct
        // port of zsh's pattern.c handling of P_BRANCH | inside
        // grouping parens — at the path level, `/etc/(passwd|
        // hostname)` matches multiple alternative paths. zshrs's
        // glob crate (and earlier hand-rolled code) didn't expand
        // the `(...|...)` form, so the literal parens reached the
        // OS glob and produced no matches.
        //
        // Pre-expand by splitting top-level `(...|...)` groups
        // into separate patterns and recursing — same shape as
        // brace expansion at this layer. Skip when extendedglob
        // is on AND the pattern is `(#flag)` (inline pattern flag,
        // handled by the regex compiler downstream).
        if let Some(alternatives) = expand_glob_alternation(pattern) {
            // For each alternative, treat as a GLOB pattern: if it
            // contains other glob chars, recurse through expand_glob
            // (which handles `*`/`?`/`[`/qualifier suffixes); if
            // it's a literal path, only include it if the path
            // EXISTS — zsh's pattern.c behavior is "alternation
            // produces matching paths, not literal alternatives".
            // Without the exists-check, `/etc/(passwd|nonexistent)`
            // would output both.
            let mut out: Vec<String> = Vec::new();
            for alt in alternatives {
                let has_meta = alt.chars().any(|c| matches!(c, '*' | '?' | '[' | '('));
                if has_meta {
                    out.extend(self.expand_glob(&alt));
                } else if std::path::Path::new(&alt).exists() {
                    out.push(alt);
                }
            }
            let mut seen = std::collections::HashSet::new();
            out.retain(|p| seen.insert(p.clone()));
            // zsh sorts glob results alphabetically by default.
            // Without sorting, the alternation order leaks
            // through (`/etc/(passwd|group)` would output
            // `passwd group` instead of zsh's `group passwd`).
            out.sort();
            if !out.is_empty() {
                return out;
            }
            // No matches — fall through to NOMATCH semantics
            // below (zsh: error if `nomatch` is on, else literal).
        }
        // extendedglob `~` exclusion: `*.txt~b.txt` matches `*.txt`
        // and excludes paths that also match `b.txt`. Detect a
        // top-level `~` (not inside brackets/parens) when extendedglob
        // is on and split. Recursively expand both halves and remove
        // the RHS matches from the LHS list.
        let extglob_on = crate::ported::options::opt_state_get("extendedglob").unwrap_or(false);
        if extglob_on {
            // extendedglob `^pat` (negation): match everything that
            // does NOT match `pat`. The lexer leaves `^` as a literal
            // char, so we detect a leading `^` here and convert to a
            // directory-walk-then-filter. Only applies at the start
            // of the LAST path component (zsh: `^pat` only negates
            // the basename portion).
            let last_seg_start = pattern.rfind('/').map(|i| i + 1).unwrap_or(0);
            let last_seg = &pattern[last_seg_start..];
            if last_seg.starts_with('^') && last_seg.len() > 1 {
                let prefix = &pattern[..last_seg_start];
                let neg = &last_seg[1..];
                let dir = if prefix.is_empty() {
                    ".".to_string()
                } else {
                    prefix.trim_end_matches('/').to_string()
                };
                let mut out = Vec::new();
                if let Ok(entries) = std::fs::read_dir(&dir) {
                    for entry in entries.flatten() {
                        let name = entry.file_name().to_string_lossy().to_string();
                        if name.starts_with('.') {
                            continue;
                        }
                        if !crate::exec::glob_match_static(&name, neg) {
                            let path = if prefix.is_empty() {
                                name
                            } else {
                                format!("{}{}", prefix, name)
                            };
                            out.push(path);
                        }
                    }
                }
                out.sort();
                if !out.is_empty() {
                    return out;
                }
                let nullglob = crate::ported::options::opt_state_get("nullglob").unwrap_or(false);
                if nullglob {
                    return Vec::new();
                }
                let nomatch = crate::ported::options::opt_state_get("nomatch").unwrap_or(true);
                if nomatch {
                    zerr(&format!("no matches found: {}", pattern));
                    std::process::exit(1);
                }
                return vec![pattern.to_string()];
            }
            // Find a top-level `~` outside brackets.
            let chars: Vec<char> = pattern.chars().collect();
            let mut depth_b = 0i32;
            let mut depth_p = 0i32;
            let mut split_at: Option<usize> = None;
            for (i, &c) in chars.iter().enumerate() {
                match c {
                    '[' => depth_b += 1,
                    ']' => depth_b -= 1,
                    '(' => depth_p += 1,
                    ')' => depth_p -= 1,
                    '~' if depth_b == 0 && depth_p == 0 && i > 0 => {
                        // Skip `~` at start (tilde expansion) and `~` adjacent
                        // to space (zsh treats those as expansion).
                        split_at = Some(i);
                        break;
                    }
                    _ => {}
                }
            }
            if let Some(pos) = split_at {
                let lhs: String = chars[..pos].iter().collect();
                let rhs: String = chars[pos + 1..].iter().collect();
                let lhs_matches = self.expand_glob(&lhs);
                // zsh pattern.c: `~` is an exclusion operator that matches
                // RHS as a PATTERN against each LHS candidate, not a
                // separate glob expansion in CWD. Match RHS against each
                // result's basename and full path.
                let filtered: Vec<String> = lhs_matches
                    .into_iter()
                    .filter(|p| {
                        let basename = p.rsplit('/').next().unwrap_or(p);
                        !crate::exec::glob_match_static(basename, &rhs)
                            && !crate::exec::glob_match_static(p, &rhs)
                    })
                    .collect();
                if !filtered.is_empty() {
                    return filtered;
                }
                // Empty after exclusion — fall through so NOMATCH
                // semantics fire if no nullglob.
                let nullglob = crate::ported::options::opt_state_get("nullglob").unwrap_or(false);
                if nullglob {
                    return Vec::new();
                }
                let nomatch = crate::ported::options::opt_state_get("nomatch").unwrap_or(true);
                if nomatch && Self::looks_like_glob(pattern) {
                    zerr(&format!("no matches found: {}", pattern));
                    std::process::exit(1);
                }
                return vec![pattern.to_string()];
            }
        }
        // Check for zsh glob qualifiers at end: *(.) *(/) *(@) etc.
        let (glob_pattern, qualifiers) = self.parse_glob_qualifiers(pattern);
        // Pre-process `[^...]` → `[!...]` so the `glob` crate (which
        // only accepts `!` for class negation per fnmatch) works for
        // zsh's `^` form too. Walk the pattern and only translate
        // inside `[...]` regions (so a literal `^` outside brackets
        // stays literal — extendedglob handles those separately).
        let glob_pattern = if glob_pattern.contains("[^") {
            let mut out = String::with_capacity(glob_pattern.len());
            let mut chars = glob_pattern.chars().peekable();
            while let Some(c) = chars.next() {
                if c == '[' {
                    out.push('[');
                    if chars.peek() == Some(&'^') {
                        chars.next();
                        out.push('!');
                    }
                    for cc in chars.by_ref() {
                        out.push(cc);
                        if cc == ']' {
                            break;
                        }
                    }
                } else {
                    out.push(c);
                }
            }
            out
        } else {
            glob_pattern
        };

        // POSIX character classes: `[[:alpha:]]`, `[[:digit:]]` etc.
        // The `glob` crate doesn't recognise the `[:class:]` syntax —
        // convert each known class to its enumerated char range so
        // the underlying matcher sees a plain char-class. Done here
        // (not at the lexer) so the substitution survives all the
        // way to glob::glob_with(). Tracks: alnum, alpha, blank,
        // cntrl, digit, graph, lower, print, punct, space, upper,
        // xdigit. Each translates to ranges like `0-9`/`a-zA-Z`.
        let glob_pattern = if glob_pattern.contains("[:") {
            // Inline expansion of `[[:alpha:]]` → `[a-zA-Z]` etc.
            // Mirrors the inline `[:class:]` switch the C source does
            // in pattern.c::patmatchrange. Each known class translates
            // to its standard ASCII range; unknown classes pass through.
            let s = &glob_pattern;
            let mut out = String::with_capacity(s.len());
            let chars: Vec<char> = s.chars().collect();
            let mut i = 0;
            while i < chars.len() {
                if chars[i] == '[' && i + 2 < chars.len() && chars[i + 1] == ':' {
                    let mut j = i + 2;
                    while j + 1 < chars.len() && !(chars[j] == ':' && chars[j + 1] == ']') {
                        j += 1;
                    }
                    if j + 1 < chars.len() && chars[j] == ':' && chars[j + 1] == ']' {
                        let name: String = chars[i + 2..j].iter().collect();
                        let range = match name.as_str() {
                            "alpha" => "a-zA-Z",
                            "alnum" => "a-zA-Z0-9",
                            "digit" => "0-9",
                            "xdigit" => "0-9a-fA-F",
                            "lower" => "a-z",
                            "upper" => "A-Z",
                            "space" => " \\t\\n\\r\\v\\f",
                            "blank" => " \\t",
                            "cntrl" => "\\x00-\\x1f\\x7f",
                            "print" => "\\x20-\\x7e",
                            "graph" => "\\x21-\\x7e",
                            "punct" => "!-/:-@\\[-`{-~",
                            _ => "",
                        };
                        if !range.is_empty() {
                            out.push_str(range);
                            i = j + 2;
                            continue;
                        }
                    }
                }
                out.push(chars[i]);
                i += 1;
            }
            out
        } else {
            glob_pattern
        };

        // zsh numeric range glob `<N-M>`, `<N->`, `<-M>`, `<->`.
        // The `glob` crate has no equivalent — match by replacing the
        // range with `*` and post-filtering by extracting the digit
        // sequence at that position and verifying it falls in [N, M].
        // Only fires when the pattern actually contains a `<…-…>` shape
        // — guard with a fast contains() before the regex.
        let numeric_ranges = if glob_pattern.contains('<') {
            extract_numeric_ranges(&glob_pattern)
        } else {
            Vec::new()
        };
        let glob_pattern = if !numeric_ranges.is_empty() {
            numeric_ranges_to_star(&glob_pattern)
        } else {
            glob_pattern
        };

        // Check for extended glob patterns: ?(pat), *(pat), +(pat), @(pat), !(pat)
        if self.has_extglob_pattern(&glob_pattern) {
            let expanded = self.expand_glob(&glob_pattern);
            return self.filter_by_qualifiers(expanded, &qualifiers);
        }

        let nullglob = crate::ported::options::opt_state_get("nullglob").unwrap_or(false);
        // `(D)` glob qualifier — per-pattern dotglob. Same effect as
        // `setopt dotglob` but scoped to this expansion only.
        // Also: when the LAST path component starts with literal `.`,
        // treat as if dotglob was on (zsh: `.*` matches dotfiles even
        // without setopt dotglob, because the leading `.` is literal).
        let last_seg = glob_pattern.rsplit('/').next().unwrap_or(&glob_pattern);
        let pattern_starts_with_dot = last_seg.starts_with('.');
        // `globdots` is the zsh canonical name; `dotglob` is the bash
        // alias. Both end up stored under their own key by setopt — read
        // both so either spelling works.
        let dotglob = crate::ported::options::opt_state_get("dotglob").unwrap_or(false)
            || crate::ported::options::opt_state_get("globdots").unwrap_or(false)
            || qualifiers.contains('D')
            || pattern_starts_with_dot;
        // `setopt nocaseglob` normalizes to `caseglob=false` in the
        // options table (the `no` prefix is the negation marker).
        // Read both forms so user code that flips either key works:
        //   - `caseglob=false` → case-INSENSITIVE
        //   - `nocaseglob=true` → case-INSENSITIVE (legacy / direct)
        let nocaseglob = !crate::ported::options::opt_state_get("caseglob").unwrap_or(true)
            || crate::ported::options::opt_state_get("nocaseglob").unwrap_or(false);

        // Parallel recursive glob: when pattern contains **/ we split the
        // directory walk across worker pool threads — one thread per top-level
        // subdirectory.  zsh does this single-threaded via fork+exec which is
        // why `echo **/*.rs` is painfully slow on large trees.
        let mut expanded = if !numeric_ranges.is_empty() {
            // `<N-M>` numeric range glob — handle via direct directory
            // walk so the digit-count semantics survive (the glob crate
            // can't express "one or more digits" precisely).
            self.expand_glob_with_numeric_range(pattern, &numeric_ranges, dotglob, nocaseglob)
        } else if glob_pattern.contains("**/") {
            self.expand_glob_parallel(&glob_pattern, dotglob, nocaseglob)
        } else {
            let options = glob::MatchOptions {
                case_sensitive: !nocaseglob,
                require_literal_separator: false,
                require_literal_leading_dot: !dotglob,
            };
            match glob::glob_with(&glob_pattern, options) {
                Ok(paths) => paths
                    .filter_map(|p| p.ok())
                    .map(|p| p.to_string_lossy().to_string())
                    .collect(),
                Err(_) => vec![],
            }
        };

        // zsh always excludes "." and ".." from glob results, even
        // with `dotglob` set or when the pattern is `.*`. The Rust
        // glob crate includes them. `Path::file_name` returns None
        // for these (treats them as cur/parent-dir components), so
        // check the trailing path segment textually.
        expanded.retain(|p| {
            let last = p.rsplit('/').next().unwrap_or(p);
            last != "." && last != ".."
        });

        let expanded = self.filter_by_qualifiers(expanded, &qualifiers);
        let mut expanded = expanded;
        // zsh: `echo */` outputs each directory with a trailing
        // slash. The Rust glob crate strips trailing slashes from
        // matches, so re-append when the pattern ended in `/`.
        if glob_pattern.ends_with('/') {
            for p in expanded.iter_mut() {
                if !p.ends_with('/') {
                    p.push('/');
                }
            }
        }
        // Locale-aware sort: under a Unicode locale, zsh folds case
        // (`Aaa bbb Ccc Ddd` not `Aaa Ccc Ddd bbb`). Fallback to byte
        // order under C/POSIX. Sort by basename so directory components
        // don't dominate the comparison and produce ASCII-style output.
        // Skip when the qualifier requested an explicit sort (`o*`/`O*`)
        // — those reorder by mtime/size/etc and the alpha sort would
        // clobber the result.
        let user_sort = qualifiers.contains('o') || qualifiers.contains('O');
        if !user_sort {
            // For `**/...` recursive globs, sort by the FULL path so
            // depth-first / breadth-first walk order is preserved
            // (zsh's natural recursive order: `dir/f sub sub/g`, not
            // basename-sorted `f g sub`). For plain (non-recursive)
            // globs, sort by BASENAME to match zsh's locale-aware
            // case-folded output.
            // Locale-aware compare via canonical `zstrcmp` (sort.c:191).
            // C's `gmatchcmp` (glob.c:936) calls `zstrcmp(b->uname,
            // a->uname, gf_numsort ? SORTIT_NUMERICALLY : 0)` for the
            // GS_NAME arm — same path here at the callsite.
            if glob_pattern.contains("**/") {
                expanded.sort_by(|a, b| crate::ported::sort::zstrcmp(a, b, 0));
            } else {
                expanded.sort_by(|a, b| {
                    let an = a.rsplit('/').next().unwrap_or(a);
                    let bn = b.rsplit('/').next().unwrap_or(b);
                    crate::ported::sort::zstrcmp(an, bn, 0)
                });
            }
        }

        if expanded.is_empty() {
            // The `(N)` per-pattern qualifier is the local equivalent of
            // `setopt nullglob` — when present on this glob, no-match
            // collapses to an empty list (silent) instead of the literal
            // pattern. Mirrors zsh's `*(N)` semantics.
            if nullglob || qualifiers.contains('N') {
                return vec![];
            }
            // zsh's default is `setopt nomatch`: an unmatched glob
            // emits "no matches found" on stderr and aborts the command
            // (the shell exits in -c mode). bash-style "pass literal
            // through" is the opt-out via `unsetopt nomatch`.
            let nomatch = crate::ported::options::opt_state_get("nomatch").unwrap_or(true);
            if nomatch && Self::looks_like_glob(pattern) {
                zerr(&format!("no matches found: {}", pattern));
                // zsh: command is aborted (skipped) with status 1,
                // script continues. Set the flag the simple-command
                // dispatcher checks; it returns early before exec.
                self.current_command_glob_failed.set(true);
                return Vec::new();
            }
            vec![pattern.to_string()]
        } else {
            expanded
        }
    }
    /// True iff the literal `pattern` actually contains a glob metachar
    /// in a position that would have triggered globbing. Used to avoid
    /// spurious "no matches" errors when expand_glob is called on a
    /// plain path that happened to route through this code (e.g. some
    /// fast paths bridge unconditionally).
    pub(crate) fn looks_like_glob(pattern: &str) -> bool {
        // A trailing `(qualifier)` is itself a glob trigger — e.g.
        // `path(L+10)` should be treated as a glob even when the
        // body has no `*`/`?`/`[...]`.
        let has_qual_suffix = if let Some(open) = pattern.rfind('(') {
            pattern.ends_with(')') && open + 1 < pattern.len() - 1
        } else {
            false
        };
        // Strip trailing `(...)` qualifier so we test the pattern body.
        let body = if let Some(open) = pattern.rfind('(') {
            if pattern.ends_with(')') {
                &pattern[..open]
            } else {
                pattern
            }
        } else {
            pattern
        };
        // Walk character-by-character so escaped metachars (`\*`, `\?`,
        // `\[`) are NOT counted as glob triggers. zsh: `echo \*` prints
        // a literal `*`; without the unescaped check, looks_like_glob
        // returned true on the bare `*` and the runtime glob expansion
        // aborted with NOMATCH.
        let chars: Vec<char> = body.chars().collect();
        let mut i = 0;
        let mut has_unescaped_star = false;
        let mut has_unescaped_question = false;
        let mut has_unescaped_bracket_open: Option<usize> = None;
        while i < chars.len() {
            let c = chars[i];
            if c == '\\' && i + 1 < chars.len() {
                // Escaped char — skip both.
                i += 2;
                continue;
            }
            match c {
                '*' => has_unescaped_star = true,
                '?' => has_unescaped_question = true,
                '[' if has_unescaped_bracket_open.is_none() => {
                    has_unescaped_bracket_open = Some(i);
                }
                _ => {}
            }
            i += 1;
        }
        // `[` only counts when there's a matching `]` after it.
        let has_bracket_class = has_unescaped_bracket_open
            .map(|i| body[i + 1..].contains(']'))
            .unwrap_or(false);
        // `<N-M>` numeric range glob is also a trigger — match shape
        // `<` + optional digits + `-` + optional digits + `>` outside
        // any bracket expression.
        let has_numeric_range =
            body.contains('<') && body.contains('>') && !extract_numeric_ranges(body).is_empty();
        has_unescaped_star
            || has_unescaped_question
            || has_bracket_class
            || has_qual_suffix
            || has_numeric_range
    }
    /// Direct directory walk for numeric-range glob `<N-M>`.
    ///
    /// Split the pattern at the last `/` so the dir component can stay
    /// concrete (or be globbed normally) and the basename gets a custom
    /// regex match. Numeric range groups capture `(\d+)` and each
    /// capture must fall inside its declared `[lo, hi]` range — open
    /// ends mean unbounded on that side.
    pub(crate) fn expand_glob_with_numeric_range(
        &self,
        pattern: &str,
        ranges: &[(usize, usize, Option<i64>, Option<i64>)],
        dotglob: bool,
        nocaseglob: bool,
    ) -> Vec<String> {
        let (dir_part, file_part) = match pattern.rfind('/') {
            Some(idx) => (&pattern[..idx], &pattern[idx + 1..]),
            None => ("", pattern),
        };
        // Build the basename regex: glob → regex, with each `<N-M>`
        // becoming a numbered capture group `(\d+)`.
        let mut rx = String::from("^");
        let chars: Vec<char> = file_part.chars().collect();
        let mut i = 0;
        let mut in_bracket = false;
        while i < chars.len() {
            let c = chars[i];
            if c == '[' && !in_bracket {
                in_bracket = true;
                rx.push('[');
                i += 1;
                continue;
            }
            if c == ']' && in_bracket {
                in_bracket = false;
                rx.push(']');
                i += 1;
                continue;
            }
            if in_bracket {
                rx.push(c);
                i += 1;
                continue;
            }
            if c == '<' {
                let mut j = i + 1;
                while j < chars.len() && chars[j].is_ascii_digit() {
                    j += 1;
                }
                if j < chars.len() && chars[j] == '-' {
                    j += 1;
                    while j < chars.len() && chars[j].is_ascii_digit() {
                        j += 1;
                    }
                    if j < chars.len() && chars[j] == '>' {
                        rx.push_str("(\\d+)");
                        i = j + 1;
                        continue;
                    }
                }
            }
            match c {
                '*' => rx.push_str(".*"),
                '?' => rx.push('.'),
                '.' | '+' | '(' | ')' | '|' | '^' | '$' | '\\' | '{' | '}' => {
                    rx.push('\\');
                    rx.push(c);
                }
                _ => rx.push(c),
            }
            i += 1;
        }
        rx.push('$');
        let re = match if nocaseglob {
            regex::RegexBuilder::new(&rx).case_insensitive(true).build()
        } else {
            regex::Regex::new(&rx).map_err(|e| regex::Error::Syntax(e.to_string()))
        } {
            Ok(r) => r,
            Err(_) => return Vec::new(),
        };

        // Resolve dir_part: it may itself contain glob chars (e.g.
        // `**/file<2-4>`). For now require the dir part to be either
        // empty (cwd) or a literal path; defer recursive ranges.
        let mut dirs: Vec<String> = if dir_part.is_empty() {
            vec![".".to_string()]
        } else if dir_part.contains('*')
            || dir_part.contains('?')
            || dir_part.contains('[')
            || dir_part.contains('<')
        {
            // Glob the dir component first, keeping only directories.
            let opts = glob::MatchOptions {
                case_sensitive: !nocaseglob,
                require_literal_separator: false,
                require_literal_leading_dot: !dotglob,
            };
            match glob::glob_with(dir_part, opts) {
                Ok(paths) => paths
                    .filter_map(|p| p.ok())
                    .filter(|p| p.is_dir())
                    .map(|p| p.to_string_lossy().to_string())
                    .collect(),
                Err(_) => return Vec::new(),
            }
        } else {
            vec![dir_part.to_string()]
        };
        if dirs.is_empty() {
            dirs.push(dir_part.to_string());
        }

        let mut out = Vec::new();
        for dir in &dirs {
            let read = match std::fs::read_dir(if dir.is_empty() { "." } else { dir }) {
                Ok(r) => r,
                Err(_) => continue,
            };
            for entry in read.flatten() {
                let name = entry.file_name().to_string_lossy().to_string();
                if !dotglob && name.starts_with('.') && !file_part.starts_with('.') {
                    continue;
                }
                let caps = match re.captures(&name) {
                    Some(c) => c,
                    None => continue,
                };
                let mut ok = true;
                for (idx, range) in ranges.iter().enumerate() {
                    let cap = match caps.get(idx + 1) {
                        Some(m) => m.as_str(),
                        None => {
                            ok = false;
                            break;
                        }
                    };
                    let val: i64 = match cap.parse() {
                        Ok(v) => v,
                        Err(_) => {
                            ok = false;
                            break;
                        }
                    };
                    // Tuple shape: (_start, _end, lo, hi).
                    if !numeric_range_contains(range.2, range.3, val) {
                        ok = false;
                        break;
                    }
                }
                if !ok {
                    continue;
                }
                let full = if dir == "." || dir.is_empty() {
                    name
                } else if dir.ends_with('/') {
                    format!("{}{}", dir, name)
                } else {
                    format!("{}/{}", dir, name)
                };
                out.push(full);
            }
        }
        out.sort();
        out
    }
    /// Parallel recursive glob using the worker pool.
    ///
    /// Splits `base/**/file_pattern` into per-subdirectory walks, each
    /// running on a pool thread via walkdir.  Results merge via channel.
    /// This is why `echo **/*.rs` will be 5-10x faster than zsh.
    pub(crate) fn expand_glob_parallel(&self, pattern: &str, dotglob: bool, nocaseglob: bool) -> Vec<String> {

        // Split pattern at the first **/ into (base_dir, file_glob)
        // e.g. "src/**/*.rs" → ("src", "*.rs")
        //      "**/*.rs"     → (".", "*.rs")
        //      "**/"         → (".", "")  with dirs_only=true
        //      "**/*"        → (".", "*") with both files+dirs
        let (base, file_glob) = if let Some(pos) = pattern.find("**/") {
            let base = if pos == 0 {
                "."
            } else {
                &pattern[..pos.saturating_sub(1)]
            };
            let rest = &pattern[pos + 3..]; // skip "**/", get "*.rs" or "foo/**/*.rs"
            (base.to_string(), rest.to_string())
        } else {
            return vec![];
        };

        // Trailing-slash form `**/`: zsh enumerates matching directories
        // (with the trailing slash preserved). Empty file_glob means
        // "match every dir under base, no file mask".
        let dirs_only = file_glob.is_empty();

        // If file_glob itself contains **/, fall back to single-threaded glob
        // (nested recursive patterns are rare, not worth the complexity)
        if file_glob.contains("**/") {
            let options = glob::MatchOptions {
                case_sensitive: !nocaseglob,
                require_literal_separator: false,
                require_literal_leading_dot: !dotglob,
            };
            return match glob::glob_with(pattern, options) {
                Ok(paths) => paths
                    .filter_map(|p| p.ok())
                    .map(|p| p.to_string_lossy().to_string())
                    .collect(),
                Err(_) => vec![],
            };
        }

        // Build the glob::Pattern for matching filenames. For
        // `dirs_only` (trailing-slash `**/`) we don't have a file mask
        // — every directory matches.
        let match_opts = glob::MatchOptions {
            case_sensitive: !nocaseglob,
            require_literal_separator: false,
            require_literal_leading_dot: !dotglob,
        };
        let file_pat = if dirs_only {
            None
        } else {
            match glob::Pattern::new(&file_glob) {
                Ok(p) => Some(p),
                Err(_) => return vec![],
            }
        };
        // For `**/*` (file_glob = "*"), zsh matches both files and
        // directories. For `**/foo` (specific file pattern), still
        // match either type — zsh doesn't restrict to file-type unless
        // a `(.)` qualifier is appended.
        let match_dirs_too = !dirs_only;

        // Enumerate top-level entries in base dir to fan out across workers
        let top_entries: Vec<std::path::PathBuf> = match std::fs::read_dir(&base) {
            Ok(rd) => rd.filter_map(|e| e.ok()).map(|e| e.path()).collect(),
            Err(_) => return vec![],
        };

        // Also check files (and dirs in dirs_only / match_dirs_too mode)
        // directly in base (not in subdirs).
        let mut results: Vec<String> = Vec::new();
        for entry in &top_entries {
            let is_dir = entry.is_dir();
            let is_file = entry.is_file() || entry.is_symlink();
            let want = if dirs_only {
                is_dir
            } else {
                is_file || (match_dirs_too && is_dir)
            };
            if want {
                if let Some(name) = entry.file_name().and_then(|n| n.to_str()) {
                    let matches = match &file_pat {
                        None => true,
                        Some(p) => p.matches_with(name, match_opts),
                    };
                    if matches {
                        let mut s = entry.to_string_lossy().to_string();
                        if dirs_only {
                            s.push('/');
                        }
                        results.push(s);
                    }
                }
            }
        }

        // Fan out subdirectory walks to worker pool
        let subdirs: Vec<std::path::PathBuf> = top_entries
            .into_iter()
            .filter(|p| p.is_dir())
            .filter(|p| {
                dotglob
                    || !p
                        .file_name()
                        .and_then(|n| n.to_str())
                        .map(|n| n.starts_with('.'))
                        .unwrap_or(false)
            })
            .collect();

        if subdirs.is_empty() {
            return results;
        }

        let (tx, rx) = std::sync::mpsc::channel::<Vec<String>>();

        for subdir in &subdirs {
            let tx = tx.clone();
            let subdir = subdir.clone();
            let file_pat = file_pat.clone();
            let skip_dot = !dotglob;
            let dirs_only_w = dirs_only;
            let match_dirs_too_w = match_dirs_too;
            self.worker_pool.submit(move || {
                let mut matches = Vec::new();
                let walker = WalkDir::new(&subdir)
                    .follow_links(false)
                    .into_iter()
                    .filter_entry(move |e| {
                        // Skip hidden dirs if !dotglob
                        if skip_dot {
                            if let Some(name) = e.file_name().to_str() {
                                if name.starts_with('.') && e.depth() > 0 {
                                    return false;
                                }
                            }
                        }
                        true
                    });
                for entry in walker.filter_map(|e| e.ok()) {
                    let is_file = entry.file_type().is_file() || entry.file_type().is_symlink();
                    let is_dir = entry.file_type().is_dir();
                    // Skip the subdir root itself — it was already added
                    // by the top-level loop.
                    if entry.depth() == 0 {
                        continue;
                    }
                    let want = if dirs_only_w {
                        is_dir
                    } else {
                        is_file || (match_dirs_too_w && is_dir)
                    };
                    if want {
                        if let Some(name) = entry.file_name().to_str() {
                            let matches_pat = match &file_pat {
                                None => true,
                                Some(p) => p.matches_with(name, match_opts),
                            };
                            if matches_pat {
                                let mut s = entry.path().to_string_lossy().to_string();
                                if dirs_only_w {
                                    s.push('/');
                                }
                                matches.push(s);
                            }
                        }
                    }
                }
                let _ = tx.send(matches);
            });
        }

        // Drop our sender so rx knows when all workers are done
        drop(tx);

        // Collect results from all workers
        for batch in rx {
            results.extend(batch);
        }

        // When base was the implicit "." (the user wrote `**/...`,
        // not `./**/...`), zsh emits relative paths without the `./`
        // prefix. Strip it here for parity.
        if base == "." {
            results = results
                .into_iter()
                .map(|s| s.strip_prefix("./").map(|t| t.to_string()).unwrap_or(s))
                .collect();
        }

        // zsh sorts the recursive-glob result lexicographically. Without
        // this, the parallel-walker order leaks through and `**/*`
        // returns paths in worker-completion order (`f sub/g sub`
        // instead of `f sub sub/g`).
        results.sort();

        results
    }
    /// Parse zsh glob qualifiers from the end of a pattern
    /// Returns (pattern_without_qualifiers, qualifiers_string)
    pub(crate) fn parse_glob_qualifiers(&self, pattern: &str) -> (String, String) {
        // Check if pattern ends with (...) that looks like qualifiers
        // Qualifiers are single chars like . / @ * % or combinations
        if !pattern.ends_with(')') {
            return (pattern.to_string(), String::new());
        }

        // Find matching opening paren
        let chars: Vec<char> = pattern.chars().collect();
        let mut depth = 0;
        let mut qual_start = None;

        for i in (0..chars.len()).rev() {
            match chars[i] {
                ')' => depth += 1,
                '(' => {
                    depth -= 1;
                    if depth == 0 {
                        qual_start = Some(i);
                        break;
                    }
                }
                _ => {}
            }
        }

        if let Some(start) = qual_start {
            let qual_content: String = chars[start + 1..chars.len() - 1].iter().collect();

            // Check if this looks like glob qualifiers (not extglob)
            // Qualifiers are things like: . / @ * % r w x ^ - etc.
            // Extglob would have | inside
            if !qual_content.contains('|') && self.looks_like_glob_qualifiers(&qual_content) {
                let base_pattern: String = chars[..start].iter().collect();
                return (base_pattern, qual_content);
            }
        }

        (pattern.to_string(), String::new())
    }
    /// Check if string looks like glob qualifiers
    //WARNING FAKE AND MUST BE DELETED
    pub(crate) fn looks_like_glob_qualifiers(&self, s: &str) -> bool {
        if s.is_empty() {
            return false;
        }
        // Valid qualifier chars (zsh glob qualifier set):
        //   type/perm: . / @ = p * % b r w x s A I E R W X
        //   sort:      o O n L l a m c d N
        //   time qual: a m c — followed by unit (s h m M d w) and op (+ -)
        //   user/grp:  u g
        //   nullglob:  N
        //   dotglob:   D
        //   T (path component)
        //   numeric ranges and digits for depth/uid/gid: 0-9 + - , [ ] :
        // Previously missing: `h` (hours unit), `g` (group qualifier),
        // `H` (non-empty-dir alt), `U` (owned-by-user) — adding them
        // unlocks `(mh-N)`, `(g+N)`, `(U)`, etc.
        // `O` (reverse-sort prefix, complementing `o`) was missing —
        // `*(Om)` was being treated as a literal pattern instead of a
        // qualifier set, leaving the trailing `)` unmatched. Added.
        let valid_chars = "./@=p*%bghilrwxAIERWXsStfHedDLNnMmcaouUYHTk^-+:0123456789,[]FO";
        s.chars()
            .all(|c| valid_chars.contains(c) || c.is_whitespace())
    }

    //WARNING FAKE AND MUST BE DELETED
    pub(crate) fn filter_by_qualifiers(&self, files: Vec<String>, qualifiers: &str) -> Vec<String> {
        if qualifiers.is_empty() {
            return files;
        }

        // Top-level `,` in the qualifier list is OR (zsh: `*(.,/)`
        // = files OR dirs). Direct port of zsh's pattern.c
        // qualifier parsing — comma splits at clause boundary,
        // each clause runs its own AND filter, the results are
        // UNIONed and de-duplicated. Single-clause (no comma)
        // path is unchanged.
        let has_or = {
            let mut depth_b = 0;
            let mut depth_p = 0;
            let mut found = false;
            for c in qualifiers.chars() {
                match c {
                    '[' => depth_b += 1,
                    ']' if depth_b > 0 => depth_b -= 1,
                    '(' if depth_b == 0 => depth_p += 1,
                    ')' if depth_b == 0 && depth_p > 0 => depth_p -= 1,
                    ',' if depth_b == 0 && depth_p == 0 => {
                        found = true;
                        break;
                    }
                    _ => {}
                }
            }
            found
        };
        if has_or {
            // Split at top-level commas, recurse for each clause,
            // union the results in original-file order. Each
            // clause re-runs the full filter so qualifier flags
            // (`L+0`, `om`, etc.) inside one clause stay scoped.
            let mut clauses: Vec<String> = Vec::new();
            let mut current = String::new();
            let mut depth_b = 0;
            let mut depth_p = 0;
            for c in qualifiers.chars() {
                match c {
                    '[' => {
                        depth_b += 1;
                        current.push(c);
                    }
                    ']' if depth_b > 0 => {
                        depth_b -= 1;
                        current.push(c);
                    }
                    '(' if depth_b == 0 => {
                        depth_p += 1;
                        current.push(c);
                    }
                    ')' if depth_b == 0 && depth_p > 0 => {
                        depth_p -= 1;
                        current.push(c);
                    }
                    ',' if depth_b == 0 && depth_p == 0 => {
                        clauses.push(std::mem::take(&mut current));
                    }
                    _ => current.push(c),
                }
            }
            clauses.push(current);
            let mut seen: std::collections::HashSet<String> = std::collections::HashSet::new();
            let mut out: Vec<String> = Vec::new();
            for clause in &clauses {
                let matched = self.filter_by_qualifiers(files.clone(), clause);
                for m in matched {
                    if seen.insert(m.clone()) {
                        out.push(m);
                    }
                }
            }
            return out;
        }

        // Parallel metadata prefetch — all stat syscalls happen on pool threads,
        // then filter/sort uses cached metadata with zero syscalls.
        let meta_cache = self.prefetch_metadata(&files);

        let mut result = files;
        let mut negate = false;
        // (M) mark-dirs and (T) list-types qualifiers — direct port of
        // zsh/Src/glob.c:1557-1566. zsh appends a single char to each
        // output (or only to dirs for `M`). We collect the flags during
        // the filter loop and apply marking AFTER all filtering is done
        // so the suffix sticks on the final result, not midway. `^M`
        // disables (toggles negate to clear the flag) — same as zsh.
        let mut mark_dirs = false;
        let mut list_types = false;
        let mut chars = qualifiers.chars().peekable();

        while let Some(c) = chars.next() {
            match c {
                // Negation
                '^' => negate = !negate,
                // (M) mark dirs with `/`. negate=true (`^M`) clears.
                'M' => {
                    mark_dirs = !negate;
                    negate = false;
                }
                // (T) list types (ls -F style: /, *, @, |, =, #, %).
                'T' => {
                    list_types = !negate;
                    negate = false;
                }

                // History modifier `:r` / `:e` / `:t` / `:h` /
                // `:s/pat/repl/` etc. applied to each match. Direct
                // port of zsh's pattern.c qualifier modifier
                // handling — `:NAME` consumes through the next
                // qualifier-list-end (next `,` or `)`) and
                // dispatches each modifier to apply_history_modifiers
                // per element.
                ':' => {
                    // Collect the modifier chain — consume until
                    // we hit another qualifier-flag char or end.
                    // For simplicity, consume to end since the
                    // qualifier-end already strips the trailing
                    // `)`. The apply_history_modifiers helper
                    // tolerates a leading `:`.
                    let mut mods = String::from(":");
                    // Consume to end — qualifier-end already stripped
                    // the trailing `)`, so no internal delimiter check
                    // is needed (apply_history_modifiers tolerates the
                    // leading `:`).
                    while chars.peek().is_some() {
                        mods.push(chars.next().unwrap());
                    }
                    let modref = mods.as_str();
                    result = result
                        .into_iter()
                        .map(|p| crate::ported::hist::apply_history_modifiers(&p, modref))
                        .collect();
                }

                // File types — all use prefetched metadata cache
                '.' => {
                    // zsh: `.` is "plain regular file" — excludes
                    // symlinks (use `@` for those). The `-`
                    // qualifier modifier (`(-.)`) inverts this:
                    // follow the symlink before testing, so a link
                    // to a regular file IS included. Direct port of
                    // zsh pattern.c QUAL_NULL → stat-not-lstat
                    // toggle.
                    let follow_links = qualifiers.contains('-');
                    result.retain(|f| {
                        let is_plain_file = meta_cache
                            .get(f)
                            .map(|(m, sm)| {
                                let is_link = sm
                                    .as_ref()
                                    .map(|m| m.file_type().is_symlink())
                                    .unwrap_or(false);
                                let is_reg = m.as_ref().map(|m| m.is_file()).unwrap_or(false);
                                if follow_links {
                                    is_reg
                                } else {
                                    is_reg && !is_link
                                }
                            })
                            .unwrap_or(false);
                        if negate {
                            !is_plain_file
                        } else {
                            is_plain_file
                        }
                    });
                    negate = false;
                }
                '/' => {
                    result.retain(|f| {
                        let is_dir = meta_cache
                            .get(f)
                            .and_then(|(m, _)| m.as_ref())
                            .map(|m| m.is_dir())
                            .unwrap_or(false);
                        if negate {
                            !is_dir
                        } else {
                            is_dir
                        }
                    });
                    negate = false;
                }
                '@' => {
                    result.retain(|f| {
                        let is_link = meta_cache
                            .get(f)
                            .and_then(|(_, sm)| sm.as_ref())
                            .map(|m| m.file_type().is_symlink())
                            .unwrap_or(false);
                        if negate {
                            !is_link
                        } else {
                            is_link
                        }
                    });
                    negate = false;
                }
                '=' => {
                    // Sockets
                    result.retain(|f| {
                        let is_socket = meta_cache
                            .get(f)
                            .and_then(|(_, sm)| sm.as_ref())
                            .map(|m| m.file_type().is_socket())
                            .unwrap_or(false);
                        if negate {
                            !is_socket
                        } else {
                            is_socket
                        }
                    });
                    negate = false;
                }
                'p' => {
                    // Named pipes (FIFOs)
                    result.retain(|f| {
                        let is_fifo = meta_cache
                            .get(f)
                            .and_then(|(_, sm)| sm.as_ref())
                            .map(|m| m.file_type().is_fifo())
                            .unwrap_or(false);
                        if negate {
                            !is_fifo
                        } else {
                            is_fifo
                        }
                    });
                    negate = false;
                }
                '*' => {
                    // Executable files
                    result.retain(|f| {
                        let is_exec = meta_cache
                            .get(f)
                            .and_then(|(m, _)| m.as_ref())
                            .map(|m| m.is_file() && (m.permissions().mode() & 0o111) != 0)
                            .unwrap_or(false);
                        if negate {
                            !is_exec
                        } else {
                            is_exec
                        }
                    });
                    negate = false;
                }
                '%' => {
                    // Device files
                    let next = chars.peek().copied();
                    result.retain(|f| {
                        let is_device = meta_cache
                            .get(f)
                            .and_then(|(_, sm)| sm.as_ref())
                            .map(|m| match next {
                                Some('b') => m.file_type().is_block_device(),
                                Some('c') => m.file_type().is_char_device(),
                                _ => {
                                    m.file_type().is_block_device()
                                        || m.file_type().is_char_device()
                                }
                            })
                            .unwrap_or(false);
                        if negate {
                            !is_device
                        } else {
                            is_device
                        }
                    });
                    if next == Some('b') || next == Some('c') {
                        chars.next();
                    }
                    negate = false;
                }

                // L[+-]N[k|m|g|p] — size qualifier. Default unit is 512-byte
                // blocks; suffix 'k'/'K' = kilobytes, 'm'/'M' = megabytes,
                // 'g'/'G' = gigabytes, 'p'/'P' = bytes (POSIX). +N matches
                // larger, -N smaller, N matches exactly. e.g. L0 = exactly
                // 0 bytes; L+10k = larger than 10 KB.
                'L' => {
                    let mut cmp = '=';
                    if let Some(&peek) = chars.peek() {
                        if peek == '+' || peek == '-' {
                            cmp = peek;
                            chars.next();
                        }
                    }
                    let mut num_str = String::new();
                    while let Some(&peek) = chars.peek() {
                        if peek.is_ascii_digit() {
                            num_str.push(peek);
                            chars.next();
                        } else {
                            break;
                        }
                    }
                    let n: u64 = num_str.parse().unwrap_or(0);
                    let unit_mult: u64 = match chars.peek().copied() {
                        Some('k') | Some('K') => {
                            chars.next();
                            1024
                        }
                        Some('m') | Some('M') => {
                            chars.next();
                            1024 * 1024
                        }
                        Some('g') | Some('G') => {
                            chars.next();
                            1024 * 1024 * 1024
                        }
                        Some('p') | Some('P') => {
                            chars.next();
                            1
                        }
                        // zsh's default for L is BYTES (not 512-byte
                        // blocks). `(L+3)` means "more than 3 bytes".
                        _ => 1,
                    };
                    let target = n * unit_mult;
                    result.retain(|f| {
                        // zsh's L qualifier uses lstat size —
                        // for symlinks, that's the path-string
                        // length (NOT the target's size).
                        // Direct port: prefer the symlink
                        // metadata `sm` when present, fall
                        // back to the followed metadata.
                        let size = meta_cache
                            .get(f)
                            .map(|(m, sm)| {
                                sm.as_ref()
                                    .map(|m| m.len())
                                    .unwrap_or_else(|| m.as_ref().map(|m| m.len()).unwrap_or(0))
                            })
                            .unwrap_or(0);
                        let pass = match cmp {
                            '+' => size > target,
                            '-' => size < target,
                            _ => size == target,
                        };
                        if negate {
                            !pass
                        } else {
                            pass
                        }
                    });
                    negate = false;
                }

                // l[+-]N — link-count qualifier. zsh: `*(l2)` = files
                // with exactly 2 hard links (e.g. one regular + one
                // hardlink). `+N` matches more, `-N` matches fewer.
                'l' => {
                    let mut cmp = '=';
                    if let Some(&peek) = chars.peek() {
                        if peek == '+' || peek == '-' {
                            cmp = peek;
                            chars.next();
                        }
                    }
                    let mut num_str = String::new();
                    while let Some(&peek) = chars.peek() {
                        if peek.is_ascii_digit() {
                            num_str.push(peek);
                            chars.next();
                        } else {
                            break;
                        }
                    }
                    let target: u64 = num_str.parse().unwrap_or(0);
                    result.retain(|f| {
                        let nlink = meta_cache
                            .get(f)
                            .and_then(|(m, _)| m.as_ref())
                            .map(|m| m.nlink())
                            .unwrap_or(0);
                        let matches = match cmp {
                            '+' => nlink > target,
                            '-' => nlink < target,
                            _ => nlink == target,
                        };
                        if negate {
                            !matches
                        } else {
                            matches
                        }
                    });
                    negate = false;
                }

                // Permission qualifiers — all use prefetched metadata cache
                'r' => {
                    result = self.filter_by_permission(result, 0o400, negate, &meta_cache);
                    negate = false;
                }
                'w' => {
                    result = self.filter_by_permission(result, 0o200, negate, &meta_cache);
                    negate = false;
                }
                'x' => {
                    result = self.filter_by_permission(result, 0o100, negate, &meta_cache);
                    negate = false;
                }
                'A' => {
                    result = self.filter_by_permission(result, 0o040, negate, &meta_cache);
                    negate = false;
                }
                'I' => {
                    result = self.filter_by_permission(result, 0o020, negate, &meta_cache);
                    negate = false;
                }
                'E' => {
                    result = self.filter_by_permission(result, 0o010, negate, &meta_cache);
                    negate = false;
                }
                'R' => {
                    result = self.filter_by_permission(result, 0o004, negate, &meta_cache);
                    negate = false;
                }
                'W' => {
                    result = self.filter_by_permission(result, 0o002, negate, &meta_cache);
                    negate = false;
                }
                'X' => {
                    result = self.filter_by_permission(result, 0o001, negate, &meta_cache);
                    negate = false;
                }
                's' => {
                    result = self.filter_by_permission(result, 0o4000, negate, &meta_cache);
                    negate = false;
                }
                'S' => {
                    result = self.filter_by_permission(result, 0o2000, negate, &meta_cache);
                    negate = false;
                }
                't' => {
                    result = self.filter_by_permission(result, 0o1000, negate, &meta_cache);
                    negate = false;
                }

                // Full/empty directories
                'F' => {
                    // Non-empty directories
                    result.retain(|f| {
                        let path = std::path::Path::new(f);
                        let is_nonempty = path.is_dir()
                            && std::fs::read_dir(path)
                                .map(|mut d| d.next().is_some())
                                .unwrap_or(false);
                        if negate {
                            !is_nonempty
                        } else {
                            is_nonempty
                        }
                    });
                    negate = false;
                }

                // Ownership — uses prefetched metadata cache
                'U' => {
                    // Owned by effective UID
                    let euid = unsafe { libc::geteuid() };
                    result.retain(|f| {
                        let is_owned = meta_cache
                            .get(f)
                            .and_then(|(m, _)| m.as_ref())
                            .map(|m| m.uid() == euid)
                            .unwrap_or(false);
                        if negate {
                            !is_owned
                        } else {
                            is_owned
                        }
                    });
                    negate = false;
                }
                'G' => {
                    // Owned by effective GID
                    let egid = unsafe { libc::getegid() };
                    result.retain(|f| {
                        let is_owned = meta_cache
                            .get(f)
                            .and_then(|(m, _)| m.as_ref())
                            .map(|m| m.gid() == egid)
                            .unwrap_or(false);
                        if negate {
                            !is_owned
                        } else {
                            is_owned
                        }
                    });
                    negate = false;
                }

                // Sorting modifiers
                'o' => {
                    // Sort by name (ascending) - already default
                    if chars.peek() == Some(&'n') {
                        chars.next();
                        // Sort by name
                        result.sort();
                    } else if chars.peek() == Some(&'L') {
                        chars.next();
                        // Sort by size — uses prefetched metadata
                        result.sort_by_key(|f| {
                            meta_cache
                                .get(f)
                                .and_then(|(m, _)| m.as_ref())
                                .map(|m| m.len())
                                .unwrap_or(0)
                        });
                    } else if chars.peek() == Some(&'m') {
                        chars.next();
                        // zsh: `om` orders by modification time NEWEST
                        // FIRST (the time qualifiers default to
                        // descending; `Om` reverses to oldest-first).
                        // Was sorting ascending which inverted output.
                        result.sort_by_key(|f| {
                            meta_cache
                                .get(f)
                                .and_then(|(m, _)| m.as_ref())
                                .and_then(|m| m.modified().ok())
                                .unwrap_or(std::time::SystemTime::UNIX_EPOCH)
                        });
                        result.reverse();
                    } else if chars.peek() == Some(&'a') {
                        chars.next();
                        // Same time-default-descending for atime.
                        result.sort_by_key(|f| {
                            meta_cache
                                .get(f)
                                .and_then(|(m, _)| m.as_ref())
                                .and_then(|m| m.accessed().ok())
                                .unwrap_or(std::time::SystemTime::UNIX_EPOCH)
                        });
                        result.reverse();
                    } else if chars.peek() == Some(&'c') {
                        chars.next();
                        // ctime — same default-descending semantics.
                        result.sort_by_key(|f| {
                            meta_cache
                                .get(f)
                                .and_then(|(m, _)| m.as_ref())
                                .map(|m| {
                                    std::time::UNIX_EPOCH
                                        + std::time::Duration::from_secs(m.ctime() as u64)
                                })
                                .unwrap_or(std::time::SystemTime::UNIX_EPOCH)
                        });
                        result.reverse();
                    }
                }
                'O' => {
                    // Reverse sort — uses prefetched metadata
                    if chars.peek() == Some(&'n') {
                        chars.next();
                        result.sort();
                        result.reverse();
                    } else if chars.peek() == Some(&'L') {
                        chars.next();
                        result.sort_by_key(|f| {
                            meta_cache
                                .get(f)
                                .and_then(|(m, _)| m.as_ref())
                                .map(|m| m.len())
                                .unwrap_or(0)
                        });
                        result.reverse();
                    } else if chars.peek() == Some(&'m') {
                        chars.next();
                        // `Om` flips the default time-descending — so
                        // `Om` is oldest-first. Just sort ascending.
                        result.sort_by_key(|f| {
                            meta_cache
                                .get(f)
                                .and_then(|(m, _)| m.as_ref())
                                .and_then(|m| m.modified().ok())
                                .unwrap_or(std::time::SystemTime::UNIX_EPOCH)
                        });
                    } else {
                        // Just reverse current order
                        result.reverse();
                    }
                }

                // Subscript range [n] or [n,m]
                '[' => {
                    let mut range_str = String::new();
                    while let Some(&ch) = chars.peek() {
                        if ch == ']' {
                            chars.next();
                            break;
                        }
                        range_str.push(chars.next().unwrap());
                    }

                    if let Some((start, end)) = self.parse_subscript_range(&range_str, result.len())
                    {
                        result = result.into_iter().skip(start).take(end - start).collect();
                    }
                }

                // Depth limit (for **/)
                'D' => {
                    // Include dotfiles (handled by dotglob)
                }
                'N' => {
                    // Nullglob for this pattern
                }

                // Time qualifiers `m` (mtime), `a` (atime), `c` (ctime).
                // Format: <qual><unit><op><N> e.g. `mh-100` =
                //   mtime within last 100 hours. Units: s (sec), m (min,
                //   default), h (hour), d (day, default for none),
                //   w (week), M (month, 30d). Ops: `+N` = older than,
                //   `-N` = newer than, no op = exactly N (within ±1 unit).
                'm' | 'a' | 'c' => {
                    let qual_kind = c;
                    // Unit (optional, default = days)
                    let unit_secs: i64 = match chars.peek().copied() {
                        Some('s') => {
                            chars.next();
                            1
                        }
                        Some('m') => {
                            chars.next();
                            60
                        }
                        Some('h') => {
                            chars.next();
                            3600
                        }
                        Some('d') => {
                            chars.next();
                            86400
                        }
                        Some('w') => {
                            chars.next();
                            7 * 86400
                        }
                        Some('M') => {
                            chars.next();
                            30 * 86400
                        }
                        _ => 86400,
                    };
                    // Op (optional, default = exact)
                    let op = match chars.peek().copied() {
                        Some('+') => {
                            chars.next();
                            '+'
                        }
                        Some('-') => {
                            chars.next();
                            '-'
                        }
                        _ => '=',
                    };
                    // Numeric value
                    let mut nstr = String::new();
                    while let Some(&nc) = chars.peek() {
                        if nc.is_ascii_digit() {
                            nstr.push(nc);
                            chars.next();
                        } else {
                            break;
                        }
                    }
                    let n: i64 = nstr.parse().unwrap_or(0);
                    let cutoff = n * unit_secs;
                    let now = std::time::SystemTime::now()
                        .duration_since(std::time::UNIX_EPOCH)
                        .map(|d| d.as_secs() as i64)
                        .unwrap_or(0);
                    result.retain(|f| {
                        let m = match meta_cache.get(f).and_then(|(m, _)| m.as_ref()) {
                            Some(m) => m,
                            None => return false,
                        };
                        let ts = match qual_kind {
                            'm' => m.mtime(),
                            'a' => m.atime(),
                            'c' => m.ctime(),
                            _ => 0,
                        };
                        let age = now - ts;
                        let pass = match op {
                            '+' => age > cutoff,
                            '-' => age < cutoff,
                            _ => age >= cutoff && age < cutoff + unit_secs,
                        };
                        if negate {
                            !pass
                        } else {
                            pass
                        }
                    });
                    negate = false;
                }

                // Unknown qualifier - ignore
                _ => {}
            }
        }

        // Apply (M) / (T) marking AFTER all filters have run. Direct
        // port of zsh/Src/glob.c:355,372 — output emit consults
        // gf_markdirs / gf_listtypes set by case 'M' / case 'T'.
        if mark_dirs || list_types {
            result = result
                .into_iter()
                .map(|p| {
                    let meta = match std::fs::symlink_metadata(&p) {
                        Ok(m) => m,
                        Err(_) => return p,
                    };
                    let ch = crate::glob::file_type(meta.permissions().mode());
                    if list_types || (mark_dirs && ch == '/') {
                        format!("{}{}", p, ch)
                    } else {
                        p
                    }
                })
                .collect();
        }

        result
    }
}

// =====================================================================
// MOVED FROM: src/ported/glob.rs
// =====================================================================

impl crate::ported::exec::ShellExecutor {
    /// Filter file list by glob qualifiers
    /// Prefetch file metadata in parallel across the worker pool.
    /// Returns a map from path → (metadata, symlink_metadata).
    /// Each batch of files is stat'd on a pool thread.
    pub(crate) fn prefetch_metadata(
        &self,
        files: &[String],
    ) -> HashMap<String, (Option<std::fs::Metadata>, Option<std::fs::Metadata>)> {
        // After fork(), the worker pool's threads don't survive (POSIX:
        // only the calling thread persists). Pipeline children would
        // submit work that never gets picked up, blocking forever or
        // returning empty. Detect via pid mismatch with the original
        // main pid; use serial when forked.
        // Worker-pool-fork detection: compare current pid with the
        // main shell pid cached at handler-install time. After fork()
        // the worker pool's threads don't survive (POSIX leaves only
        // the calling thread), so pipeline children must take the
        // serial path. This is Rust-runtime concern, not a C
        // construct, so the check stays here in `exec_shims.rs`.
        let in_forked_child = {
            static MAIN_PID: AtomicI32 = AtomicI32::new(0);
            let mut main = MAIN_PID.load(Ordering::Relaxed);
            if main == 0 {
                let cur = nix::unistd::getpid().as_raw();
                match MAIN_PID.compare_exchange(0, cur, Ordering::Relaxed, Ordering::Relaxed) {
                    Ok(_) => main = cur,
                    Err(prev) => main = prev,
                }
            }
            nix::unistd::getpid().as_raw() != main
        };
        if files.len() < 32 || in_forked_child {
            // Small list OR forked child — serial stat is the only
            // safe path.
            return files
                .iter()
                .map(|f| {
                    let meta = std::fs::metadata(f).ok();
                    let symlink_meta = std::fs::symlink_metadata(f).ok();
                    (f.clone(), (meta, symlink_meta))
                })
                .collect();
        }

        let pool_size = self.worker_pool.size();
        let chunk_size = files.len().div_ceil(pool_size);
        let (tx, rx) = std::sync::mpsc::channel();

        for chunk in files.chunks(chunk_size) {
            let tx = tx.clone();
            let chunk: Vec<String> = chunk.to_vec();
            self.worker_pool.submit(move || {
                #[allow(clippy::type_complexity)]
                let batch: Vec<(
                    String,
                    (Option<std::fs::Metadata>, Option<std::fs::Metadata>),
                )> = chunk
                    .into_iter()
                    .map(|f| {
                        let meta = std::fs::metadata(&f).ok();
                        let symlink_meta = std::fs::symlink_metadata(&f).ok();
                        (f, (meta, symlink_meta))
                    })
                    .collect();
                let _ = tx.send(batch);
            });
        }
        drop(tx);

        let mut map = HashMap::with_capacity(files.len());
        for batch in rx {
            for (path, metas) in batch {
                map.insert(path, metas);
            }
        }
        map
    }
    /// Filter files by permission bits — uses prefetched metadata cache
    pub(crate) fn filter_by_permission(
        &self,
        files: Vec<String>,
        mode: u32,
        negate: bool,
        meta_cache: &HashMap<String, (Option<std::fs::Metadata>, Option<std::fs::Metadata>)>,
    ) -> Vec<String> {
        files
            .into_iter()
            .filter(|f| {
                let has_perm = meta_cache
                    .get(f)
                    .and_then(|(m, _)| m.as_ref())
                    .map(|m| (m.permissions().mode() & mode) != 0)
                    .unwrap_or(false);
                if negate {
                    !has_perm
                } else {
                    has_perm
                }
            })
            .collect()
    }
}

// =====================================================================
// MOVED FROM: src/ported/utils.rs
// =====================================================================

impl crate::ported::exec::ShellExecutor {
    pub(crate) fn copy_dir_recursive(src: &std::path::Path, dest: &std::path::Path) -> std::io::Result<()> {
        if !dest.exists() {
            std::fs::create_dir_all(dest)?;
        }
        for entry in std::fs::read_dir(src)? {
            let entry = entry?;
            let file_type = entry.file_type()?;
            let src_path = entry.path();
            let dest_path = dest.join(entry.file_name());

            if file_type.is_dir() {
                Self::copy_dir_recursive(&src_path, &dest_path)?;
            } else {
                std::fs::copy(&src_path, &dest_path)?;
            }
        }
        Ok(())
    }
}

// =====================================================================
// MOVED FROM: src/ported/zle/compcore.rs
// =====================================================================

impl crate::ported::exec::ShellExecutor {
    // zsh compadd - add completion matches
    // zsh compset - modify completion prefix/suffix
}

// =====================================================================
// MOVED FROM: src/ported/zle/computil.rs
// =====================================================================

impl crate::ported::exec::ShellExecutor {
}

// =====================================================================
// MOVED FROM: src/ported/zle/zle_main.rs
// =====================================================================

impl crate::ported::exec::ShellExecutor {
    // `vared` shim — parses the `"AaceghM:m:p:r:i:f:"` BUILTIN spec
    // from zle_main.c:2186 into a real `options` struct, then invokes
    // the canonical free-fn port at
    // crate::ported::zle::zle_main::bin_vared which matches the C
    // signature `bin_vared(name, args, ops, func)` exactly.
}

// =====================================================================
// MOVED FROM: src/ported/modules/cap.rs
// =====================================================================

impl crate::ported::exec::ShellExecutor {
    /// `cap` builtin entry. Bridge to `bin_cap()` above.
    pub(crate) fn bin_cap(&self, args: &[String]) -> i32 {
        let ops = crate::ported::zsh_h::options { ind: [0u8; crate::ported::zsh_h::MAX_OPS], args: Vec::new(), argscount: 0, argsalloc: 0 };
        bin_cap("cap", args, &ops, 0)
    }

    /// `getcap` builtin entry. Bridge to `bin_getcap()` above.
    pub(crate) fn bin_getcap(&self, args: &[String]) -> i32 {
        let ops = crate::ported::zsh_h::options { ind: [0u8; crate::ported::zsh_h::MAX_OPS], args: Vec::new(), argscount: 0, argsalloc: 0 };
        bin_getcap("getcap", args, &ops, 0)
    }

    /// `setcap` builtin entry. Bridge to `bin_setcap()` above.
    pub(crate) fn bin_setcap(&self, args: &[String]) -> i32 {
        let ops = crate::ported::zsh_h::options { ind: [0u8; crate::ported::zsh_h::MAX_OPS], args: Vec::new(), argscount: 0, argsalloc: 0 };
        bin_setcap("setcap", args, &ops, 0)
    }
}

// =====================================================================
// MOVED FROM: src/ported/modules/zpty.rs
// =====================================================================

impl crate::ported::exec::ShellExecutor {
    // `zpty` builtin — delegates to canonical port at
    // `src/ported/modules/zpty.rs:367` (`bin_zpty()` from
    // `Src/Modules/zpty.c`). The named-pty table lives on
    // `ShellExecutor` so `zpty -w NAME ...` and `zpty -r NAME` can
    // reach a session started by an earlier `zpty NAME ...` call.
}

// =====================================================================
// MOVED FROM: src/ported/modules/terminfo.rs
// =====================================================================

impl crate::ported::exec::ShellExecutor {
    /// `echoti` shim — delegates to the canonical free-fn port at
    /// `crate::ported::modules::terminfo::bin_echoti` (matching C
    /// `bin_echoti(nam, args, ops, func)` per terminfo.c:64). The
    /// previous shim mapped terminfo→termcap and routed through
    /// bin_echotc; the canonical port now calls libcurses tigetstr/
    /// tigetnum/tigetflag + tparm directly per the C source.
    pub(crate) fn bin_echoti(&mut self, args: &[String]) -> i32 {
        let ops = options { ind: [0u8; MAX_OPS], args: Vec::new(),
                            argscount: 0, argsalloc: 0 };
        crate::ported::modules::terminfo::bin_echoti("echoti", args, &ops, 0)
    }
}

// =====================================================================
// MOVED FROM: src/ported/modules/watch.rs
// =====================================================================

impl crate::ported::exec::ShellExecutor {
    // `log` builtin — delegates to canonical port at
    // `src/ported/modules/watch.rs` (`bin_log()` from
    // `Src/Modules/watch.c`). The watch state lives in
    // `thread_local!`s in the canonical port (mirroring C's
    // `Src/Modules/watch.c:150-156` file-statics) so login/logout
    // edge detection survives across calls without a struct on
    // `ShellExecutor`.
}

// =====================================================================
// MOVED FROM: src/ported/modules/pcre.rs
// =====================================================================

impl crate::ported::exec::ShellExecutor {
    // `pcre_compile` builtin — delegates to canonical port at
    // `src/ported/modules/pcre.rs` (`bin_pcre_compile()` from
    // `Src/Modules/pcre.c:70`). Builds an `options` struct from the
    // `-a/-i/-m/-s/-x` flags so the canonical port reads them via
    // `OPT_ISSET` exactly like C does.
    // `pcre_match` builtin — delegates to canonical port at
    // `src/ported/modules/pcre.rs` (`bin_pcre_match()` from
    // `Src/Modules/pcre.c:328`). Builds the `options` struct from
    // `-v`/`-a` argv (matching C's OPT_ARG reads) and writes the
    // returned capture data into the executor's variable/array
    // tables — that side-effect cannot live in the canonical port
    // because it doesn't own those tables.
    // pcre_study - optimize compiled PCRE (no-op in Rust regex)
}

// =====================================================================
// MOVED FROM: src/ported/modules/tcp.rs
// =====================================================================

impl crate::ported::exec::ShellExecutor {
}

// =====================================================================
// MOVED FROM: src/ported/modules/db_gdbm.rs
// =====================================================================

impl crate::ported::exec::ShellExecutor {
    // Tie a parameter to a GDBM database
    // Usage: ztie -d db/gdbm -f /path/to/db.gdbm [-r] PARAM_NAME
    // Untie a parameter from its GDBM database
    // Usage: zuntie [-u] PARAM_NAME...
    // Get the path of a tied GDBM database
    // Usage: zgdbmpath PARAM_NAME
    // Sets $REPLY to the path
}

// =====================================================================
// MOVED FROM: src/ported/modules/termcap.rs
// =====================================================================

impl crate::ported::exec::ShellExecutor {
    // `echotc` builtin shim — adapts `&[String]` argv to
    // `bin_echotc` over a `[bool; 256]` ops bitmask.
}

// (FAKE `magic_assoc_keys` deleted per user instruction. Callers
// in fusevm_bridge.rs route through the canonical scanpm* dispatch
// in src/ported/modules/parameter.rs — each magic-assoc table has
// its own scanpm* fn that walks the live canonical hashtable
// instead of a unified hard-coded switch.)

// =====================================================================
// Magic-assoc key dispatch — fusevm-bridge aggregator that fans a
// magic-assoc table NAME out into the right scanpm* port from
// src/ported/modules/parameter.rs.
// =====================================================================
//
// The C source (Src/Modules/parameter.c) doesn't have a single
// "scan-by-name" function — each magic-assoc registers its own
// per-table getfn/scanfn pointer in the paramdef[] table at
// c:825-..., and zsh's paramtab dispatch reaches them through that
// table. fusevm_bridge's magic_assoc_lookup needs name → keys
// lookup at the call site; that aggregator is THIS Rust-only
// convenience, parked outside src/ported/ per the rule that
// src/ported/ holds direct C ports only.

use std::cell::RefCell;
thread_local! {
    static SCAN_KEYS: RefCell<Vec<String>> = const { RefCell::new(Vec::new()) };
}

pub fn scan_magic_assoc_keys(name: &str) -> Option<Vec<String>> {
    fn collect<F: FnOnce(Option<crate::ported::zsh_h::ScanFunc>, i32)>(scan: F)
        -> Vec<String>
    {
        SCAN_KEYS.with(|k| k.borrow_mut().clear());
        fn cb(node: &crate::ported::zsh_h::HashNode, _flags: i32) {
            SCAN_KEYS.with(|k| k.borrow_mut().push(node.nam.clone()));
        }
        scan(Some(cb), 0);
        SCAN_KEYS.with(|k| k.borrow().clone())
    }
    let null_ht = std::ptr::null_mut();
    match name {
        "commands"     => Some(collect(|f, fl| scanpmcommands(null_ht, f, fl))),
        "options"      => Some(collect(|f, fl| scanpmoptions(null_ht, f, fl))),
        "builtins"     => Some(collect(|f, fl| scanpmbuiltins(null_ht, f, fl))),
        "dis_builtins" => Some(collect(|f, fl| scanpmdisbuiltins(null_ht, f, fl))),
        "functions"    => Some(collect(|f, fl| scanpmfunctions(null_ht, f, fl))),
        "dis_functions"=> Some(collect(|f, fl| scanpmdisfunctions(null_ht, f, fl))),
        "aliases"      => Some(collect(|f, fl| scanpmraliases(null_ht, f, fl))),
        "dis_aliases"  => Some(collect(|f, fl| scanpmdisraliases(null_ht, f, fl))),
        "galiases"     => Some(collect(|f, fl| scanpmgaliases(null_ht, f, fl))),
        "dis_galiases" => Some(collect(|f, fl| scanpmdisgaliases(null_ht, f, fl))),
        "saliases"     => Some(collect(|f, fl| scanpmsaliases(null_ht, f, fl))),
        "dis_saliases" => Some(collect(|f, fl| scanpmdissaliases(null_ht, f, fl))),
        "reswords" | "dis_reswords" |
        "modules" | "history" | "historywords" |
        "jobtexts" | "jobstates" | "jobdirs" |
        "nameddirs" | "userdirs" | "usergroups" |
        "parameters" | "errnos" | "sysparams" | "dirstack"
            => Some(Vec::new()),
        // `mapfile` — zsh/mapfile module's magic assoc. Keys are
        // discoverable via `scanpmmapfile` (Src/Modules/mapfile.c:241)
        // which walks `.` but uses an empty value list per the
        // comment "grotesquely wasteful to read every file into
        // memory." Routing through here lets `${mapfile[$path]}`
        // hit get_special_array_value's "mapfile" arm and call
        // get_contents() directly.
        "mapfile" => Some(
            crate::modules::mapfile::scanpmmapfile()
                .into_iter()
                .map(|(k, _v)| k)
                .collect(),
        ),
        _ => None,
    }
}

// =====================================================================
// SubstState bridge — DELETED per user directive ("delete SubstState").
//
// `subst_state_from_executor` and `subst_state_commit_to_executor`
// were Rust-only plumbing that snapshotted executor state into a
// `SubstState` struct, then mutated it back out. Both the struct
// and the bridge are gone. subst.rs now reads/writes canonical
// globals (`utils::errflag`, `hist::hsubl/hsubr/hsubpatopt`,
// `options::opt_state_get/set`) and executor state directly via
// `fusevm_bridge::try_with_executor`. The single piece of state
// the bridge guarded — bumping `exec.last_status` on errflag — now
// lives at the per-call site in fusevm_bridge.rs subst_port arms.
// =====================================================================

impl crate::ported::exec::ShellExecutor {
    pub fn enter_posix_mode(&mut self) {
        self.posix_mode = true;
        self.plugin_cache = None;
        self.compsys_cache = None;
        self.compinit_pending = None;
        self.worker_pool = std::sync::Arc::new(crate::worker::WorkerPool::new(1));
        let ops = crate::ported::zsh_h::options {
            ind: [0u8; crate::ported::zsh_h::MAX_OPS],
            args: Vec::new(), argscount: 0, argsalloc: 0,
        };
        crate::ported::builtin::bin_emulate("emulate",
            &["sh".to_string(), "-R".to_string()], &ops, 0);
    }
    pub fn enter_ksh_mode(&mut self) {
        self.plugin_cache = None;
        self.compsys_cache = None;
        self.compinit_pending = None;
        self.worker_pool = std::sync::Arc::new(crate::worker::WorkerPool::new(1));
        let ops = crate::ported::zsh_h::options {
            ind: [0u8; crate::ported::zsh_h::MAX_OPS],
            args: Vec::new(), argscount: 0, argsalloc: 0,
        };
        crate::ported::builtin::bin_emulate("emulate",
            &["ksh".to_string(), "-R".to_string()], &ops, 0);
    }
}

// ─────────────────────────────────────────────────────────
// Static glob match — module-level free fn (no executor state).
// Extracted from impl ShellExecutor per the FAKE DUP audit.
// ─────────────────────────────────────────────────────────
/// Static glob match — same logic as glob_match but callable without &self,
/// needed for Rayon parallel iterators that can't capture &self.
///
/// plus extendedglob preprocessing (`^pat` negation, `(a|b)~(x)`
/// exclusion). The preprocessing is shell-canonical but lives here
/// in exec.rs instead of inside patcompile or a wrapper. To dissolve:
/// move the extendedglob `^` / `~` arm into patcompile (or a thin
/// canonical pre-walker) so callers use patmatch directly.
pub fn glob_match_static(s: &str, pattern: &str) -> bool {
    // Extendedglob `^pat` negation: when extendedglob is on AND
    // the pattern starts with a literal `^`, strip it and invert
    // the match of the remainder. Already done in
    // `extendedglob_match` for the param-filter path; do it here
    // too so `[[ str = ^pat ]]` works via the cond `=` matcher.
    let extendedglob_on =
        with_executor(|e| crate::ported::options::opt_state_get("extendedglob").unwrap_or(false));
    if extendedglob_on {
        if let Some(rest) = pattern.strip_prefix('^') {
            return !crate::exec::glob_match_static(s, rest);
        }
        // Extendedglob `~` exclusion: `pat1~pat2` matches strings
        // matching `pat1` AND NOT matching `pat2`. Direct port of
        // zsh's pattern.c P_EXCLUDE handling (line 155 onward) for
        // the top-level case — the canonical implementation also
        // handles nested exclusions (`(a~b)c`) but the top-level
        // form is what `*.txt~README*` and similar idioms produce.
        // Walk the pattern looking for a `~` that's NOT inside
        // `[...]` or `(...)` so nested specials stay literal.
        if let Some(idx) = find_top_level_tilde(pattern) {
            let lhs = &pattern[..idx];
            let rhs = &pattern[idx + 1..];
            return crate::exec::glob_match_static(s, lhs)
                && !crate::exec::glob_match_static(s, rhs);
        }
    }

    // ksh-style negation `!(p)` (gated on `setopt kshglob`): when
    // the entire pattern is `!(<body>)`, match anything that does
    // NOT match `<body>`. This handles the standalone case (the
    // overwhelmingly common form); embedded `!()` inside a larger
    // pattern still falls through and is left literal — full
    // zsh-style negation needs lookahead which `regex` lacks.
    let kshglob_on = with_executor(|e| crate::ported::options::opt_state_get("kshglob").unwrap_or(false));
    if kshglob_on {
        if let Some(body) = pattern.strip_prefix("!(").and_then(|r| r.strip_suffix(')')) {
            // Don't recurse if body itself contains an unmatched
            // `(` that would change the meaning.
            let mut depth = 0;
            let mut balanced = true;
            for c in body.chars() {
                match c {
                    '(' => depth += 1,
                    ')' => {
                        if depth == 0 {
                            balanced = false;
                            break;
                        }
                        depth -= 1;
                    }
                    _ => {}
                }
            }
            if balanced && depth == 0 {
                return !crate::exec::glob_match_static(s, body);
            }
        }
    }

    // Inline pattern flags `(#i)` / `(#I)` / `(#l)` / `(#a<n>)` per
    // zshexpn(1) "Globbing Flags". They prefix a pattern and modify
    // matching semantics for the rest.
    //   (#i) — case insensitive
    //   (#I) — case sensitive (turn (#i) back off)
    //   (#l) — lowercase pattern char matches both cases in input;
    //          uppercase pattern char is exact-match
    //   (#a<n>) — approximate match: up to <n> errors (Levenshtein
    //          distance, insert/delete/substitute)
    // Inline (#i)/(#l)/(#aN) flag pre-parse — direct call to
    // patgetglobflags + bit-mask extraction, matching how C's
    // patcompile inlines the same parsing at pattern.c:1066+.
    let (pattern, case_insensitive, l_flag, approx_n) =
        if let Some((bits, _assert, consumed)) =
            crate::ported::pattern::patgetglobflags(pattern)
        {
            let ci = (bits & crate::ported::zsh_h::GF_IGNCASE) != 0;
            let l = (bits & crate::ported::zsh_h::GF_LCMATCHUC) != 0;
            let errs = bits & 0xff;
            let approx = if errs != 0 { Some(errs as u32) } else { None };
            (pattern[consumed..].to_string(), ci, l, approx)
        } else {
            (pattern.to_string(), false, false, None)
        };

    if let Some(n) = approx_n {
        // Inline (#aN) approximate-match — direct port of the
        // Levenshtein-distance check inside patmatch (Src/pattern.c)
        // when PAT_APPROX is set. m/k bound check skips early when
        // the strings differ in length by more than the budget;
        // otherwise standard 2-row DP table.
        let s_chars: Vec<char> = s.chars().collect();
        let p_chars: Vec<char> = pattern.chars().collect();
        let m = s_chars.len();
        let k = p_chars.len();
        if m.abs_diff(k) as u32 > n {
            return false;
        }
        let mut prev: Vec<usize> = (0..=k).collect();
        let mut curr: Vec<usize> = vec![0; k + 1];
        for i in 1..=m {
            curr[0] = i;
            for j in 1..=k {
                let cost = if s_chars[i - 1] == p_chars[j - 1] { 0 } else { 1 };
                curr[j] = (prev[j] + 1).min(curr[j - 1] + 1).min(prev[j - 1] + cost);
            }
            std::mem::swap(&mut prev, &mut curr);
        }
        return prev[k] as u32 <= n;
    }

    // Build the regex. For (#l) we need to inflate lowercase chars
    // to character classes that match either case. Also detect
    // zsh's numeric-range glob `<a-b>` (or `<->` for any number,
    // `<a->` / `<-b>` for one-sided ranges) — translate to a
    // capture group and remember the bounds for a post-match check.
    let mut regex_pattern = String::from("^");
    // Numeric ranges paired with the regex capture-group index they
    // correspond to. Required because user-written `(...)` groups
    // in the pattern (esp. alternation `(a|b)`) shift capture
    // indices, so we can't assume each `<N-M>` is at numeric_ranges
    // index + 1. Direct port of the bookkeeping zsh's pattern.c
    // does via `pat_captures` — each numeric atom remembers its
    // own group offset. Without this, `[[ 5.9 == (5.<1->*|<6->.*) ]]`
    // applied the lo/hi check against the OUTER alternation's
    // capture (the literal "5.9") and parse-as-int failed.
    let mut numeric_ranges: Vec<(usize, Option<i64>, Option<i64>)> = Vec::new();
    // Track the capture-group index. Increments on every `(` that
    // OPENS a new group in the emitted regex. Starts at 0 because
    // the outer `^...$` anchors don't add a group.
    let mut capture_group_count: usize = 0;
    let mut chars = pattern.chars().peekable();
    // Helper: after emitting any atom, check for zsh extendedglob
    // postfix `#` (zero-or-more) / `##` (one-or-more) and append
    // the equivalent regex quantifier. Direct port of zsh's
    // pattern.c (`Pound` / `POUND2` cases in `patcompswitch`).
    // Only fires when extendedglob is enabled.
    let consume_extglob_postfix =
        |chars: &mut std::iter::Peekable<std::str::Chars>| -> Option<&'static str> {
            if !extendedglob_on {
                return None;
            }
            if chars.peek() != Some(&'#') {
                return None;
            }
            chars.next();
            if chars.peek() == Some(&'#') {
                chars.next();
                Some("+")
            } else {
                Some("*")
            }
        };
    while let Some(c) = chars.next() {
        match c {
            // ksh-style extglob: ?(p) *(p) +(p) @(p) — translate to
            // (?:p)? (?:p)* (?:p)+ (?:p) respectively. Gated on
            // the `kshglob` option (zsh's default is off). The
            // !(p) (negative) form needs lookahead which the
            // `regex` crate doesn't support; left literal.
            '?' | '*' | '+' | '@'
                if chars.peek() == Some(&'(')
                    && with_executor(|e| {
                        crate::ported::options::opt_state_get("kshglob").unwrap_or(false)
                    }) =>
            {
                let op = c;
                chars.next(); // consume '('
                              // Capture body until matching ')'. Track depth so
                              // nested parens work.
                let mut depth = 1;
                let mut body = String::new();
                while let Some(&pc) = chars.peek() {
                    chars.next();
                    if pc == '(' {
                        depth += 1;
                        body.push(pc);
                    } else if pc == ')' {
                        depth -= 1;
                        if depth == 0 {
                            break;
                        }
                        body.push(pc);
                    } else {
                        body.push(pc);
                    }
                }
                // Inline ksh-extglob body -> regex translator.
                // Direct port of the tiny per-char dispatch zsh's
                // pattern.c does inside its extglob handler — no
                // anchors, no (#flags), just glob -> regex chars.
                let body_re = {
                    let mut out = String::new();
                    let mut chars = body.chars().peekable();
                    while let Some(c) = chars.next() {
                        match c {
                            '|' => out.push('|'),
                            '*' => out.push_str(".*"),
                            '?' => out.push('.'),
                            '[' => {
                                out.push('[');
                                for cc in chars.by_ref() {
                                    if cc == ']' {
                                        out.push(']');
                                        break;
                                    }
                                    out.push(cc);
                                }
                            }
                            '.' | '+' | '^' | '$' | '\\' | '{' | '}' | '(' | ')' => {
                                out.push('\\');
                                out.push(c);
                            }
                            _ => out.push(c),
                        }
                    }
                    out
                };
                let suffix = match op {
                    '?' => "?",
                    '*' => "*",
                    '+' => "+",
                    '@' => "",
                    _ => "",
                };
                regex_pattern.push_str(&format!("(?:{}){}", body_re, suffix));
            }
            '*' => regex_pattern.push_str(".*"),
            '?' => {
                regex_pattern.push('.');
                if let Some(q) = consume_extglob_postfix(&mut chars) {
                    regex_pattern.push_str(q);
                }
            }
            '<' => {
                // Try to parse `<lo-hi>`. If the form doesn't
                // match, fall back to literal `<`. Direct port of
                // zsh's numeric-range glob handler — speculative
                // scan for the closing `>`, split on `-`, parse
                // optional bounds. Matches `<5-10>`, `<5->`,
                // `<-10>`, `<->`.
                let parsed: Option<(Option<i64>, Option<i64>, usize)> = (|| {
                    let mut buf = String::new();
                    let peek_iter = chars.clone();
                    for c in peek_iter {
                        buf.push(c);
                        if c == '>' { break; }
                        if buf.len() > 64 { return None; }
                    }
                    if !buf.ends_with('>') {
                        return None;
                    }
                    let inner = &buf[..buf.len() - 1];
                    let (lo_str, hi_str) = inner.split_once('-')?;
                    let lo: Option<i64> = if lo_str.is_empty() {
                        None
                    } else {
                        Some(lo_str.parse().ok()?)
                    };
                    let hi: Option<i64> = if hi_str.is_empty() {
                        None
                    } else {
                        Some(hi_str.parse().ok()?)
                    };
                    let n = buf.chars().count();
                    for _ in 0..n { chars.next(); }
                    Some((lo, hi, n))
                })();
                if let Some((lo, hi, consumed)) = parsed {
                    regex_pattern.push_str("(\\d+)");
                    capture_group_count += 1;
                    numeric_ranges.push((capture_group_count, lo, hi));
                    let _ = consumed;
                } else {
                    regex_pattern.push('<');
                }
            }
            '[' => {
                // Direct port of zsh's character-class compile
                // (pattern.c, see `patcompcls` and the `[`
                // handling in `patcompswitch`):
                //   - `[!...]` and `[^...]` both negate (POSIX +
                //     zsh both accept; only `^` is canonical
                //     regex). Translate `!` -> `^` so the regex
                //     crate sees the right form. Was being
                //     copied verbatim, so `[!a]` matched `!` or
                //     `a` instead of "anything but a".
                //   - POSIX character classes `[:alpha:]` /
                //     `[:digit:]` etc. inside `[...]` already
                //     pass through the regex crate, but the
                //     trailing `]` of the class would be misread
                //     as the closing of the outer bracket. Walk
                //     past `[:NAME:]` as a unit so the next `]`
                //     after the class isn't taken as the close.
                //   - Backslash-escaped `]` (`[\\]]`) keeps the
                //     `]` as a literal class member.
                regex_pattern.push('[');
                let mut first = true;
                while let Some(cc) = chars.next() {
                    if first && cc == '!' {
                        regex_pattern.push('^');
                        first = false;
                        continue;
                    }
                    first = false;
                    if cc == ']' {
                        regex_pattern.push(']');
                        break;
                    }
                    if cc == '\\' {
                        // Pass escape + next char through.
                        regex_pattern.push('\\');
                        if let Some(nx) = chars.next() {
                            regex_pattern.push(nx);
                        }
                        continue;
                    }
                    if cc == '[' && chars.peek() == Some(&':') {
                        // POSIX class `[:NAME:]`. Read until
                        // `:]` then push the class verbatim.
                        regex_pattern.push('[');
                        let mut prev_colon = false;
                        for ic in chars.by_ref() {
                            regex_pattern.push(ic);
                            if prev_colon && ic == ']' {
                                break;
                            }
                            prev_colon = ic == ':';
                        }
                        continue;
                    }
                    regex_pattern.push(cc);
                }
                // After a closed `[...]`, the bracket is a single
                // regex atom — apply extendedglob `#`/`##`
                // postfix as `*`/`+` directly.
                if let Some(q) = consume_extglob_postfix(&mut chars) {
                    regex_pattern.push_str(q);
                }
            }
            '(' => {
                // `(#cN)` and `(#cN,M)` post-subpattern repetition
                // qualifiers: the previous element gets a `{N}` or
                // `{N,M}` regex quantifier. Detect by peeking for
                // `#c` after the opening `(`.
                let peek_iter = chars.clone();
                let mut probe: Vec<char> = Vec::new();
                let p = peek_iter;
                for pc in p {
                    probe.push(pc);
                    if pc == ')' || probe.len() > 32 {
                        break;
                    }
                }
                let probe_str: String = probe.iter().collect();
                if probe_str.starts_with("#c") && probe_str.ends_with(')') {
                    let body = &probe_str[2..probe_str.len() - 1];
                    let quant = if let Some((lo, hi)) = body.split_once(',') {
                        format!("{{{},{}}}", lo, hi)
                    } else {
                        format!("{{{}}}", body)
                    };
                    regex_pattern.push_str(&quant);
                    // Advance the real iterator past the consumed chars.
                    for _ in 0..probe.len() {
                        chars.next();
                    }
                } else if probe_str == "#e)" {
                    // `(#e)` — match end-of-string anchor. Direct
                    // port of zsh's pattern.c P_EOL token (zsh's
                    // "globbing flag" `(#e)` per zshexpn(1)).
                    // Emits regex `$` to anchor the match at the
                    // end of the input. Used by zinit's
                    // `(#b)((*)\\(#e)|(*))` to detect a trailing
                    // `\` in each element.
                    regex_pattern.push('$');
                    for _ in 0..probe.len() {
                        chars.next();
                    }
                } else if probe_str == "#s)" {
                    // `(#s)` — match start-of-string anchor.
                    // zshexpn(1): "matches at the start of the
                    // test string". Emits regex `^`.
                    regex_pattern.push('^');
                    for _ in 0..probe.len() {
                        chars.next();
                    }
                } else {
                    regex_pattern.push('(');
                    capture_group_count += 1;
                }
            }
            ')' => {
                regex_pattern.push(')');
                // Closed group is an atom — extendedglob `#`/`##`
                // postfix applies to the whole group.
                if let Some(q) = consume_extglob_postfix(&mut chars) {
                    regex_pattern.push_str(q);
                }
            }
            '|' => regex_pattern.push('|'),
            '\\' => {
                // Special-case: `\(#e)` / `\(#s)` — literal
                // backslash followed by extendedglob end/start
                // anchor. Emit `\\$` / `\\^` so the pattern matches
                // a literal trailing/leading `\`. Without this the
                // `(` of `(#e)` got consumed as the escaped char,
                // dropping the anchor entirely. Direct port of
                // pattern.c P_EOL/P_BOL recognition after a `\`.
                // Only fires under extendedglob — without the
                // option, `(#e)` is not a token at all.
                if extendedglob_on {
                    let mut peek = chars.clone();
                    let p1 = peek.next();
                    let p2 = peek.next();
                    let p3 = peek.next();
                    let p4 = peek.next();
                    if p1 == Some('(')
                        && p2 == Some('#')
                        && (p3 == Some('e') || p3 == Some('s'))
                        && p4 == Some(')')
                    {
                        regex_pattern.push_str("\\\\");
                        regex_pattern.push(if p3 == Some('e') { '$' } else { '^' });
                        chars.next(); chars.next(); chars.next(); chars.next();
                        continue;
                    }
                }
                // Backslash escapes the next char — treat literally.
                if let Some(next) = chars.next() {
                    if matches!(
                        next,
                        '.' | '+'
                            | '^'
                            | '$'
                            | '\\'
                            | '{'
                            | '}'
                            | '*'
                            | '?'
                            | '('
                            | ')'
                            | '|'
                            | '['
                            | ']'
                    ) {
                        regex_pattern.push('\\');
                    }
                    regex_pattern.push(next);
                } else {
                    regex_pattern.push_str("\\\\");
                }
            }
            '.' | '+' | '^' | '$' | '{' | '}' => {
                regex_pattern.push('\\');
                regex_pattern.push(c);
            }
            _ => {
                if l_flag && c.is_ascii_lowercase() {
                    regex_pattern.push('[');
                    regex_pattern.push(c);
                    regex_pattern.push(c.to_ascii_uppercase());
                    regex_pattern.push(']');
                } else {
                    regex_pattern.push(c);
                }
                // After a literal/(#l)-class atom, extendedglob
                // `#`/`##` postfix maps to regex `*`/`+` and
                // binds to that single atom. Same as zsh's
                // pattern.c Pound/POUND2 handling on the atom
                // just compiled.
                if let Some(q) = consume_extglob_postfix(&mut chars) {
                    regex_pattern.push_str(q);
                }
            }
        }
    }
    regex_pattern.push('$');
    let final_pattern = if case_insensitive {
        format!("(?i){}", regex_pattern)
    } else {
        regex_pattern
    };
    if !numeric_ranges.is_empty() {
        // Need captures + per-group numeric range checks.
        let re = match regex::Regex::new(&final_pattern) {
            Ok(re) => re,
            Err(_) => return false,
        };
        let caps = match re.captures(s) {
            Some(c) => c,
            None => return false,
        };
        for (group_idx, lo, hi) in numeric_ranges.iter() {
            // A numeric-range `<N-M>` inside an alternation branch
            // that didn't fire (e.g. branch B of `(A|B)` when A
            // matched) won't have a populated capture. Skip the
            // bounds check for those — the alternation's match
            // already commits to the branch that DID fire.
            let cap_str = match caps.get(*group_idx) {
                Some(m) => m.as_str(),
                None => continue,
            };
            let n: i64 = match cap_str.parse() {
                Ok(n) => n,
                Err(_) => return false,
            };
            if let Some(l) = lo {
                if n < *l {
                    return false;
                }
            }
            if let Some(h) = hi {
                if n > *h {
                    return false;
                }
            }
        }
        return true;
    }
    regex::Regex::new(&final_pattern)
        .map(|re| re.is_match(s))
        .unwrap_or(false)
}


// =============================================================================
// Direct ports from Src/exec.c — fns whose Rust home was misplaced in
// builtin.rs because they're called from `bin_autoload` but actually
// defined in Src/exec.c.
// =============================================================================

/// Direct port of `Shfunc loadautofn(Shfunc shf, int ks, int test_only,
/// int ignore_loaddir)` from `Src/exec.c:5050`. Walks `$fpath` for a
/// file named `shf->node.nam`, reads it, installs the text body on
/// the corresponding `shfunctab` entry, and clears `PM_UNDEFINED`.
///
/// C body (abridged):
///   1. `name = shf->node.nam`
///   2. `getfpfunc(name, &dir_path, NULL, 0)` → resolved file path
///   3. If !test_only && file found: parse → store eprog on
///      `shf->funcdef`; clear PM_UNDEFINED; set `shf->filename`.
///   4. Returns shf on success, NULL on failure.
///
/// Rust port: returns 0 = success, 1 = failure (matches the
/// existing call-site convention in `bin_functions -c`). Stores
/// raw file text on `ShFunc.body` (the Rust-side ShFunc in
/// `hashtable.rs:362`); the parser pass that converts text →
/// Eprog runs lazily at first call site.
/// Port of `loadautofn(Shfunc shf, int fksh, int autol, int current_fpath)` from `Src/exec.c:5682`.
pub fn loadautofn(shf: *mut crate::ported::zsh_h::shfunc,                        // c:5682 (Src/exec.c)
              _ks: i32, test_only: i32, _ignore_loaddir: i32) -> i32 {
    if shf.is_null() {
        return 1;
    }
    // c:5054 — `name = shf->node.nam`.
    let name = unsafe { (*shf).node.nam.clone() };
    // c:5070 — `path = getfpfunc(name, &dir_path, NULL, 0)`.
    let mut dir_path: Option<String> = None;
    let path = match getfpfunc(&name, &mut dir_path, None, 0) {
        Some(p) => p,
        None => return 1,                                                    // c:5074 not found
    };
    if test_only != 0 {                                                      // c:5096
        return 0;                                                            // test passes — file exists
    }
    // c:5100-5140 — read the file. C uses zopen + read + parse_string +
    // execsave; Rust port stores raw text on the ShFunc and defers
    // parse-to-Eprog until the first call.
    let body = match std::fs::read_to_string(&path) {
        Ok(t) => t,
        Err(_) => return 1,
    };
    // c:5142 — `shf->filename = ztrdup(dir_path)`.
    unsafe {
        (*shf).filename = dir_path.clone().or(Some(path.clone()));
    }
    // c:5148 — `shf->node.flags &= ~PM_UNDEFINED`.
    unsafe {
        (*shf).node.flags &= !(PM_UNDEFINED as i32);
    }
    // Sync the body string into the Rust-side ShFunc table so the
    // lazy-parse path can find it later.
    if let Ok(mut tab) = crate::ported::hashtable::shfunctab_lock().write() {
        if let Some(existing) = tab.get_mut(&name) {
            existing.body = Some(body);
            existing.filename = dir_path;
        } else {
            tab.add(crate::ported::hashtable::ShFunc {
                node: crate::ported::zsh_h::hashnode {
                    next: None,
                    nam: name.clone(),
                    flags: 0,
                },
                filename: dir_path,
                lineno: 0,
                funcdef: None,
                redir: None,
                sticky: None,
                body: Some(body),
            });
        }
    }
    0
}

/// Port of `getfpfunc(char *s, int *ksh, char **fdir, char **alt_path, int test_only)` from Src/exec.c:5260. Walks `$fpath` (or the
/// supplied `spec_path` slice) for a file named `name` and writes the
/// resolved directory through `*dir_path_out` (matching the C `char **dir_path`).
/// Returns `Some(file_contents_path)` on success, `None` when not found.
pub fn getfpfunc(name: &str, dir_path_out: &mut Option<String>,                  // c:5260 (Src/exec.c)
             spec_path: Option<&[String]>, _all_loaded: i32) -> Option<String> {
    let dirs: Vec<String> = match spec_path {
        Some(s) => s.to_vec(),
        None => std::env::var("FPATH").or_else(|_| std::env::var("fpath"))
            .ok().map(|v| v.split(':').map(String::from).collect())
            .unwrap_or_default(),
    };
    for dir in &dirs {
        if dir.is_empty() { continue; }
        let path = format!("{}/{}", dir, name);
        if std::path::Path::new(&path).exists() {
            *dir_path_out = Some(dir.clone());
            return Some(path);
        }
    }
    None
}