zsh/

vm_helper.rs

//! Shell executor state for zshrs.
//!
//! ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
//! !!! LAST-RESORT FILE — NOT FOR NEW LOGIC !!!
//!
//! This file holds the `ShellExecutor` runtime state struct + VM-adjacent
//! helpers. It is **not** the place to add zsh logic — every line here that
//! does real shell work is a tax we pay because zshrs uses fusevm bytecode
//! instead of C zsh's wordcode walker.
//!
//! **Before adding code to this file, STOP and ask:**
//!
//!   1. Does the C source have a fn that does this? (Check `src/zsh/Src/*.c`)
//!      → Port it into `src/ported/<file>.rs` with line-by-line citations.
//!        Then call the canonical fn from here.
//!
//!   2. Does `src/ported/` already have a port?
//!      → Call it directly. Don't reimplement.
//!
//!   3. Is this purely a Rust-only state-struct accessor (getter/setter on
//!      ShellExecutor fields, VM init plumbing, executor-context guards)?
//!      → OK to put it here. Mark it `WARNING: RUST-ONLY HELPER` per memory
//!        `feedback_rust_only_helpers_need_warning`.
//!
//! **NEVER:** reinvent paramsubst/expansion/glob/typeset/redirect/scope
//! management here. Every one of those has a canonical port in `src/ported/`.
//! When a bridge-side fn grows past ~30 lines of shell logic, that's a
//! signal the work belongs in `src/ported/` — port it, don't inline.
//!
//! This file should be SHRINKING over time. Every PR that adds lines here
//! should justify it; every PR that moves lines OUT to `src/ported/` is
//! aligned with the project direction.
//!
//! See also: memory `feedback_no_shortcuts_in_porting`, `feedback_true_port_pattern`,
//! `feedback_no_shellexecutor_in_ported` (the inverse direction).
//! ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
//!
//! **Not a port of Src/exec.c.** C zsh runs compiled programs on the native
//! **wordcode walker** 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
//!
//! Path-wise this file lives at the crate root (`src/vm_helper`) 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::compsys::cache::CompsysCache;
use crate::compsys::CompInitResult;
use crate::history::HistoryEngine;
use crate::options::ZSH_OPTIONS_SET;
use crate::ported::builtin::{BREAKS, CONTFLAG};
use crate::ported::math::mathevali;
use crate::ported::modules::parameter::*;
use crate::ported::subst::singsub;

thread_local! {
    /// Eval-recursion depth counter — no C counterpart by design.
    ///
    /// !!! WARNING: RUST-ONLY BACKSTOP — reproduces C behaviour, no C fn !!!
    ///
    /// zsh bounds runaway `eval` recursion via its job table: every eval'd
    /// list runs through `execpline`, which grabs a job slot per pipeline
    /// (`initjob`), and the table caps at `MAX_MAXJOBS` → `zerr("job table
    /// full or recursion limit exceeded")` (Src/jobs.c:1878-1884). The fusevm
    /// runtime that executes eval bodies allocates no job per pipeline, and
    /// nested evals push no funcstack frame (INEVAL suppression, matching zsh's
    /// `if (!ineval)` at Src/builtin.c:6164), so neither the job table nor the
    /// FUNCNEST/FUNCSTACK depth reflects eval nesting — leaving eval recursion
    /// unbounded until the (256 MB but finite) main-thread stack overflows →
    /// uncatchable SIGBUS. This counter is the Rust proxy for zsh's count of
    /// concurrently-held job slots: `builtin.rs::eval` bumps it around each
    /// eval body and refuses to recurse at the same `MAX_MAXJOBS` ceiling.
    /// Lives here (not src/ported/) because it is an architectural Rust-only
    /// backstop with no 1:1 C symbol.
    pub static EVAL_RECURSION_DEPTH: std::cell::Cell<usize> = const { std::cell::Cell::new(0) };
    /// Set by `execute_cmdarg` for the next compile_script_isolated only —
    /// the `-c` string itself, not an `eval` or trap it runs.
    ///
    /// !!! WARNING: RUST-ONLY FLAG — C PASSES `exiting` TO execode !!!
    static CMDARG_EXITING: std::cell::Cell<bool> = const { std::cell::Cell::new(false) };
}

/// O(1) single-key probe against the canonical hashed storage — the
/// fast-path companion to subst.rs `assoc_get` for order-independent
/// single-key reads. Returns `None` when `name` (post-nameref) isn't
/// an assoc; otherwise `Some((key_present, value))` under ONE lock,
/// with no whole-map clone and no zsh-bucket-order rebuild (that
/// reorder is only observable to whole-map enumeration). Hot: shell
/// loops reading `${assoc[$k]}` per iteration were O(n²) through
/// assoc_get — zpwr expandstats over 42k records took 43s vs zsh's ~1s.
/// Lives here (not src/ported/) because it has no C counterpart — C's
/// getarg IS the single-key path.
/// Classify an assoc subscript as an EXACT-key lookup and return the
/// key: plain text (no leading flag group) passes through; a leading
/// `(e…)`/`(E…)` group (c:Src/params.c:1449 — literal-key flag) is
/// stripped. Search groups ((r)/(i)/(k)/…) return `None` — they need
/// the full getarg walk. Companion gate for [`assoc_key_hit`]'s O(1)
/// fast paths.
/// !!! WARNING: RUST-ONLY HELPER — body of c:Src/init.c:180-215, lifted out
/// of loop() so the script-file event loop (`run_events_per_command`) runs
/// the same code; src/ported/ may not gain functions. !!!
///
/// The `toplevel` preexec branch of loop(): when a `preexec` function or
/// `preexec_functions` exists, call the hook with `$1` (the history line, or
/// "" when the history ring does not hold the current line — always the
/// case for a script), `$2` (getjobtext) and `$3` (getpermtext), then clear
/// ERRFLAG_ERROR (c:214). `event_src` is the event's source text captured
/// around parse_event; zshrs's parse_event returns the fusevm AST, which the
/// text renderers cannot walk, so the source is compiled to the wordcode
/// Eprog C would already hold. That compile is silent and leaves errflag as
/// it found it; an event it cannot take gets empty `$2`/`$3`.
pub fn run_preexec_hook(event_src: Option<&str>) {
    use crate::ported::zsh_h::{interact, isset, INTERACTIVECOMMENTS, SHINSTDIN};
    // Native p10k engine command timer (src/extensions/p10k): stamp the
    // command start for command_execution_time, with or without a user hook.
    crate::p10k::note_exec_start();
    let preexec_fn = crate::ported::utils::getshfunc("preexec"); // c:181
    let preexec_hook = crate::ported::params::paramtab()
        .read()
        .ok()
        .and_then(|t| {
            t.get(&format!("preexec{}", crate::ported::zsh_h::HOOK_SUFFIX))
                .map(|_| ())
        }); // c:182 realparamtab->getnode2(realparamtab, "preexec" HOOK_SUFFIX)
    if preexec_fn.is_none() && preexec_hook.is_none() {
        return;
    }
    let mut args: Vec<String> = Vec::new(); // c:191 newlinklist()
    args.push("preexec".to_string()); // c:192
    {
        // c:195 — `if (hist_ring && curline.histnum == curhist)`
        let hr = crate::ported::hist::hist_ring.lock().unwrap();
        let cl = crate::ported::hist::curline.lock().unwrap();
        let same = !hr.is_empty()
            && cl.as_ref().map(|c| c.histnum).unwrap_or(0)
                == crate::ported::hist::curhist.load(Ordering::SeqCst);
        if same {
            args.push(hr.first().map(|h| h.node.nam.clone()).unwrap_or_default()); // c:196
        } else {
            args.push(String::new()); // c:198
        }
    }
    let event_prog: Option<crate::ported::zsh_h::eprog> = event_src.and_then(|src| {
        let noerrs = crate::ported::utils::noerrs_lock();
        let saved_noerrs = std::mem::replace(&mut *noerrs.lock().unwrap(), 1);
        let saved_errflag = errflag.load(Ordering::SeqCst);
        // The event was lexed with `strin == 0`, where a `#` starts a comment
        // only under INTERACTIVECOMMENTS in an interactive stdin shell
        // (c:Src/lex.c:678-681). parse_string lexes under `strin`, which would
        // turn comments on; `nocomments` restores that decision, the way
        // getoutput does around its own parse_string (c:Src/exec.c:4720-4723).
        let onc = crate::ported::lex::LEX_NOCOMMENTS.with(|c| c.get());
        crate::ported::lex::LEX_NOCOMMENTS.with(|c| {
            c.set(interact() && isset(SHINSTDIN) && !isset(INTERACTIVECOMMENTS))
        });
        let p = crate::ported::exec::parse_string(src, 0);
        crate::ported::lex::LEX_NOCOMMENTS.with(|c| c.set(onc));
        errflag.store(saved_errflag, Ordering::SeqCst);
        *noerrs.lock().unwrap() = saved_noerrs;
        p
    });
    // c:210 — addlinknode(args, dupstring(getjobtext(prog, NULL)))
    // c:211 — addlinknode(args, cmdstr = getpermtext(prog, NULL, 0))
    let (job_text, cmdstr) = match event_prog {
        Some(p) => (
            crate::ported::text::getjobtext(Box::new(p.clone()), None), // c:210
            crate::ported::text::getpermtext(Box::new(p), None, 0),     // c:211
        ),
        None => (String::new(), String::new()),
    };
    args.push(crate::ported::mem::dupstring(&job_text));
    args.push(cmdstr.clone());
    crate::ported::utils::callhookfunc("preexec", Some(&args), 1, std::ptr::null_mut()); // c:202
    crate::ported::mem::zsfree(cmdstr); // c:205
    errflag.fetch_and(!ERRFLAG_ERROR, Ordering::SeqCst); // c:214
}

pub fn exact_assoc_sub_key(sub: &str) -> Option<&str> {
    match sub.strip_prefix('(') {
        None => Some(sub),
        Some(rest) => {
            let close = rest.find(')')?;
            let grp = &rest[..close];
            if !grp.is_empty() && grp.chars().all(|c| c == 'e' || c == 'E') {
                Some(&rest[close + 1..])
            } else {
                None
            }
        }
    }
}

pub fn assoc_key_hit(name: &str, key: &str) -> Option<(bool, Option<String>)> {
    let resolved = match crate::ported::params::resolve_nameref_name(name, None) {
        crate::ported::params::nameref_resolution::Target { name: t_, .. } => t_,
        _ => name.to_string(),
    };
    // c:Src/params.c:1090-1115 createparam — a `local NAME` / `typeset
    // NAME` replaces a special's paramtab node with a plain one, so the
    // name is no longer a hash. Answering here would strand the read on
    // the O(1) assoc fast path and never reach paramsubst's scalar
    // subscript arm (`${options[1]}` came back empty for a local).
    //
    // …but "no longer the magic row" is NOT the same as "no longer a
    // hash": a `local -A commands` shadow owns a table of its own and the
    // key read must be served FROM IT (c:Src/params.c:2270 / :1597-1606).
    // See `magic_special_shadowed_by_nonhash`, which every sibling
    // dispatch site shares so the qualification cannot drift.
    if magic_special_shadowed_by_nonhash(resolved.as_str()) {
        return None;
    }
    // c:Src/Zle/complete.c:1272/1411 — `compstate[nmatches]` is a LIVE gsu
    // integer (`get_nmatches` = `permmatches(0) ? 0 : nmatches`), not stored
    // data, so the hashed store never held it and every shell-side read
    // returned the EMPTY string. `_parameters` (`local -i nm=$compstate[
    // nmatches]` … `(( compstate[nmatches] > nm ))`) therefore always
    // reported "added nothing" and returned 1 — `unset <TAB>` offered 197
    // names against zsh's 496 — and the same idiom in `_alternative`,
    // `_describe` and `_arguments` mis-fired the same way.
    // The same applies to the other NINE gsu-backed rows
    // (c:complete.c:1261-1300): list_lines, list_max, unambiguous,
    // unambiguous_cursor, unambiguous_positions, insert_positions, vared,
    // all_quotes, ignored. Only `nmatches` was served live here, so
    // `$compstate[list_lines]` and friends read empty from shell code
    // where zsh reports a value.
    if resolved == "compstate" && crate::ported::zle::compcore::LIVE_COMPSTATE_KEYS.contains(&key) {
        return Some((
            true,
            Some(
                crate::ported::zle::compcore::get_compstate_str(key).unwrap_or_else(|| {
                    if key == "nmatches" {
                        "0".to_string()
                    } else {
                        String::new()
                    }
                }),
            ),
        ));
    }
    crate::ported::params::paramtab_hashed_storage()
        .lock()
        .ok()
        .and_then(|s| {
            s.get(resolved.as_str())
                .map(|m| (m.contains_key(key), m.get(key).cloned()))
        })
}
use crate::ported::utils::{errflag, ERRFLAG_ERROR};
use crate::ported::zsh_h::PM_UNDEFINED;
use crate::ported::zsh_h::WC_SIMPLE;
use crate::ported::zsh_h::{options, MAX_OPS};
use crate::ported::zsh_h::{PM_ARRAY, PM_HASHED, PM_INTEGER, PM_READONLY};
use parking_lot::Mutex;
use std::collections::HashSet;
use std::ffi::CStr;
use std::ffi::CString;
use std::ffi::OsStr;
use std::fs;
use std::io::Read;
use std::os::unix::ffi::OsStrExt;
use std::os::unix::fs::FileTypeExt;
use std::os::unix::fs::PermissionsExt;
use std::os::unix::io::FromRawFd;
use std::sync::atomic::AtomicI32;
use std::sync::atomic::Ordering;
use std::time::{SystemTime, UNIX_EPOCH};
use walkdir::WalkDir;

// Backward-compat re-exports for free ported recently relocated to their
// canonical-C-file Rust modules. Existing call-sites in this file (and
// elsewhere) still reference these unqualified.
#[allow(unused_imports)]
pub(crate) use crate::func_body_fmt::FuncBodyFmt;
#[allow(unused_imports)]
pub(crate) use crate::ported::hist::bufferwords as bufferwords_z_tuple;
#[allow(unused_imports)]
pub(crate) use crate::ported::math::{parse_assign, parse_compound, parse_pre_inc};
#[allow(unused_imports)]
pub use crate::ported::params::convbase as format_int_in_base;
pub use crate::ported::params::convbase_underscore;
// `getarrvalue` is already re-exported by `pub use crate::ported::params::*`
// below; an explicit `pub(crate) use` here only shadowed that public export.
#[allow(unused_imports)]
pub(crate) use crate::ported::utils::base64_decode;
#[allow(unused_imports)]
pub(crate) use crate::ported::utils::{ispwd, printprompt4, quotedzputs};

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<HashMap<String, Regex>>> =
    LazyLock::new(|| Mutex::new(HashMap::with_capacity(64)));

// fusevm VM bridge (extension; not a port of Src/exec.c) lives in
// src/fusevm_bridge.rs. Re-exports below let the rest of the codebase
// reference symbols as `crate::ported::exec::X`.
pub(crate) use crate::fusevm_bridge::ExecutorContext;
pub use crate::fusevm_bridge::*;

/// `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"));
}

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

/// 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
});

use crate::exec_jobs::{JobState, JobTable};
use crate::parse::{Redirect, RedirectOp, ShellCommand, ShellWord, VarModifier, ZshParamFlag};
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};

// Re-exports for call-sites that reference `crate::ported::exec::<Name>`.
pub use crate::bash_complete::CompSpec;
pub use crate::ported::builtin::AutoloadFlags;
pub use crate::ported::modules::zutil::zstyle_entry;

/// One inline-assignment scope (`X=foo Y=bar cmd`).
///
/// `saved` holds `(name, prev_var, prev_env)` for each name the
/// PREFIX assignments touched, so END_INLINE_ENV can put the shell
/// var and the process env back.
///
/// `recording` is what keeps the frame from swallowing assignments
/// the *command itself* performs. zsh's `addvars()` (Src/exec.c:4142)
/// walks only the parsed WC_ASSIGN chain, and `save_params`
/// (Src/exec.c:4410) snapshots only those names; once the command
/// runs, the save list is closed. The bytecode emits the prefix
/// assignments between BEGIN_INLINE_ENV and SEAL_INLINE_ENV, and
/// SEAL clears this flag, so `X=y . file` no longer records (and
/// then reverts) every global the sourced file assigns.
pub struct InlineEnvFrame {
    /// Per-name pre-assignment state, one entry per prefix assignment.
    pub saved: Vec<SavedInlineParam>,
    /// True only while the prefix assignments are being executed.
    pub recording: bool,
    /// C's `ADDVAR_EXPORT` bit for this command (c:Src/exec.c:37), decided
    /// where C decides it: `if (is_shfunc) flags |= ADDVAR_EXPORT`
    /// (c:Src/exec.c:4142-4143), under the comment "Export this if the
    /// command is a shell function, but not if it's a builtin"
    /// (c:4138-4140). `addvars` reads it to run the prefix assignment with
    /// `opts[ALLEXPORT]` forced on (c:2646-2651), which is what makes
    /// `X=y shellfn` leave `X` marked exported for the duration of the
    /// call while `X=y builtin` does not.
    pub export: bool,
}

/// One parameter a prefix assignment displaced — the Rust twin of the
/// `tpm` that C's `save_params` builds with
/// `copyparam(tpm, pm, 0)` (c:Src/exec.c:4491-4493).
pub struct SavedInlineParam {
    /// The assigned name (C's `s`, c:Src/exec.c:4475).
    pub name: String,
    /// The WHOLE pre-assignment `Param` — type flags, base, width, level
    /// and the value union, with the value read back through the type's
    /// GSU getfn exactly as `copyparam` does (c:Src/params.c:1273-1291).
    /// `None` when the name did not exist, which is C's remove-only arm
    /// at c:Src/exec.c:4507-4508.
    pub pm: Option<crate::ported::zsh_h::param>,
    /// !!! RUST-ONLY FIELD — THE SECOND HALF OF c:Src/params.c:1289 !!!
    /// C's `copyparam` copies an association's pairs into `tpm->u.hash`,
    /// so they travel inside the `Param` above. zshrs keeps them in the
    /// name-keyed `paramtab_hashed_storage` instead, OUTSIDE the `Param`
    /// (the structural mismatch `stdunsetfn` documents at
    /// params.rs:11044), so the pairs must be carried — and restored —
    /// alongside the node rather than within it.
    pub hashed: Option<IndexMap<String, String>>,
    /// Pre-assignment `environ` entry for the name.
    pub prev_env: Option<String>,
}

impl InlineEnvFrame {
    /// New frame, open for recording until SEAL_INLINE_ENV runs.
    pub fn new() -> Self {
        Self {
            saved: Vec::new(),
            recording: true,
            // c:4141 `int flags = 0;` — BEGIN_INLINE_ENV sets the
            // ADDVAR_EXPORT bit once it has resolved the command word.
            export: false,
        }
    }

    /// Put every displaced parameter back — the frame's half of
    /// `restore_params` (c:Src/exec.c:4519), run when the prefixed
    /// command returns.
    ///
    /// Saves are pushed as the prefix assignments execute, so a name
    /// assigned twice (`X=1 X=2 cmd`) has its ORIGINAL in the first
    /// entry; walking in reverse makes that the last write, which is
    /// what C's single pre-`addvars` snapshot achieves.
    pub fn restore(self) {
        for saved in self.saved.into_iter().rev() {
            // c:4525-4531 (remove the temporary parameter) followed by
            // c:4533-4570 (put the saved one back). C's `remove_p` carries
            // the name in BOTH arms of `save_params` (c:4504 runs whether or
            // not a `tpm` was made), so the name is always in the remove
            // list and the restore list holds the snapshot only if there was
            // one.
            crate::ported::exec::restore_params(
                saved.pm.into_iter().collect(),
                vec![saved.name.clone()],
            );
            // !!! RUST-ONLY — see `SavedInlineParam::hashed` !!!
            // c:4561's `tpm->gsu.h->setfn(tpm, pm->u.hash)` in zshrs terms.
            // Unconditional: when nothing was saved the row must be gone, or
            // the pairs the command itself wrote would outlive the frame.
            if let Ok(mut store) = crate::ported::params::paramtab_hashed_storage().lock() {
                match saved.hashed {
                    Some(pairs) => {
                        store.insert(saved.name.clone(), pairs);
                    }
                    None => {
                        store.remove(saved.name.as_str());
                    }
                }
            }
            // c:4568-4569 — `if ((pm->node.flags & PM_EXPORTED) && ...)
            // addenv(pm, s);`. zshrs's prefix-assignment path publishes the
            // value with `zputenv` on the way in, so the way out is the
            // matching restore of the pre-assignment `environ` entry.
            match saved.prev_env {
                Some(v) => std::env::set_var(&saved.name, &v),
                None => std::env::remove_var(&saved.name),
            }
        }
    }
}

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

/// 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).
    /// Same node storage as the live table (`Src/params.c:854`
    /// `newparamtable(151, "paramtab")`) so restoring a snapshot restores
    /// C's bucket-walk order too, not just the name→value mapping.
    pub paramtab: crate::ported::hashtable::hashtable_nodes<crate::ported::zsh_h::Param>,
    /// `paramtab_hashed_storage` field.
    pub paramtab_hashed_storage: crate::cow_map::CowHashMap<String, IndexMap<String, String>>,
    /// `positional_params` field.
    pub positional_params: Vec<String>,
    /// Values of the special parameters whose backing store is a process
    /// GLOBAL rather than the parameter table — `Src/params.c`'s `char *ifs`
    /// (IFS), `wordchars`, `home`, `histsiz`, … — each reached through a GSU
    /// getfn/setfn pair (the dispatch list at params.rs:12548).
    ///
    /// The `paramtab` snapshot above restores the param NODE, but the node only
    /// carries the GSU pair; the value itself lives in the global, which a
    /// paramtab restore doesn't touch. C forks for `(...)`, so a child's writes
    /// to those globals die with it. zshrs runs subshells in-process, so
    /// `(IFS=,; :)` left the PARENT's IFS as `,` — and every later word-split
    /// in the parent silently used it. Same fork-copy reasoning as `opts`
    /// and `tables`.
    pub special_globals: Vec<(String, String)>,
    /// Flock fds (`Src/utils.c:2111` `addlockfd`) live at subshell
    /// entry. `zsystem flock FILE` keeps the fd open for the life of
    /// the shell; under C's forked `(...)` the child's fd — and hence
    /// the lock — dies when the subshell exits. zshrs runs subshells
    /// in-process, so the lock outlived the subshell and every later
    /// `zsystem flock` on that file (from a real forked background job)
    /// blocked forever. Recorded here so `subshell_end` can close the
    /// fds the subshell itself opened.
    pub flock_fds: Vec<i32>,
    /// `loops` / `breaks` / `contflag` at subshell entry
    /// (c:Src/loop.c, c:Src/builtin.c bin_break). C forks for `(...)`,
    /// so a `break` executed inside dies with the child and the parent's
    /// loop runs on: `for i in 1 2; do (break); print after; done` prints
    /// `after` twice. zshrs runs subshells in-process, so the three
    /// counters have to be restored by hand at the boundary.
    /// Fourth slot: `ancestor_loops` (c:Src/loop.c:36), which entry moves
    /// `loops` into (c:Src/exec.c:1263-1264, 55061).
    pub loop_flags: (i32, i32, i32, i32),
    /// `cmdoutval` (c:Src/exec.c:225) at subshell entry. A process global
    /// the forked child owns a private copy of: `x=$(exit 3); (y=1); exec
    /// 3>f` still reports 3 in zsh although the subshell's assignment reset
    /// its own copy (c:2796). Restored by hand like `loop_flags`.
    pub cmdoutval: i32,
    /// `stopmsg` (c:Src/builtin.c) at subshell entry. Another process
    /// global the child owns a copy of: a nofork `${ exit N }` in a
    /// subshell sets it (c:Src/subst.c:2100) and the child then exits, so
    /// in C it never reaches the parent. Leaked here it made every later
    /// `exit` in a function or nofork skip its deferral (c:5884).
    pub stopmsg: i32,
    /// 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. Stores a snapshot
    /// of `crate::ported::builtin::traps_table()` (canonical).
    pub traps: HashMap<String, String>,
    /// Parent's shell options at subshell entry. `(set -e)` /
    /// `(setopt extendedglob)` mustn't leak; zsh forks the subshell
    /// so child options die with the child. We run in-process, so we
    /// must restore the option store on subshell_end.
    pub opts: HashMap<String, bool>,
    /// The fork-copied hash tables — `aliastab`, `sufaliastab`, … — at
    /// subshell entry (see `crate::ported::exec::SubshForkCopy`). zsh forks
    /// for `(...)` so `(alias x=y)` inside a subshell dies with the child
    /// and doesn't leak to the parent. Bug #209 in docs/BUGS.md. The
    /// tables are restored whole — node flags (ALIAS_GLOBAL / DISABLED)
    /// and bucket order included — which the `(name, text, flags)` list
    /// this replaced got only partly right, and it never covered
    /// `sufaliastab` at all: `(alias -s x=y)` leaked.
    pub tables: crate::ported::exec::SubshForkCopy,
    /// Parent's shell-function table at subshell entry. C zsh's
    /// `entersubsh` (`Src/exec.c`) forks before running the
    /// subshell body so `(f() { ... })` defining a function dies
    /// with the child and never leaks to the parent. zshrs runs
    /// subshells in-process, so we must clone `shfunctab` on entry
    /// and restore on exit. Bug #208 in docs/BUGS.md. Stored as a
    /// clone of the whole `shfunc_table` — the bucket layout is part
    /// of the state, because `${(k)functions}` / `compadd -k functions`
    /// emit C's bucket-walk order verbatim
    /// (`Src/Modules/parameter.c:480-481`); rebuilding the table from
    /// an unordered map on restore would reshuffle that order after
    /// every `( … )` / `$( … )`.
    pub shfuncs: std::sync::Arc<crate::ported::hashtable::shfunc_table>,
    /// Parent's compiled-function chunks at subshell entry. Companion
    /// to `shfuncs` above — `ShellExecutor.functions_compiled` is the
    /// runtime dispatch table that `Op::CallFunction` reads through;
    /// without restoring it, a subshell `(g() { override; })` leaves
    /// the override bytecode chunk in place so the parent's
    /// `g` call still runs the override after `subshell_end`
    /// restored shfunctab. Bug #208 in docs/BUGS.md.
    ///
    /// Copy-on-write (`crate::cow_map`): taking this snapshot is a
    /// refcount bump, and the deep copy happens only if the subshell
    /// body actually compiles or redefines a function.
    pub functions_compiled: crate::cow_map::CowHashMap<String, fusevm::Chunk>,
    /// Parent's function source map at subshell entry. Companion to
    /// `functions_compiled` so `typeset -f` / `whence` show the
    /// parent's source after subshell exit, not the subshell's
    /// overridden body. Bug #208 in docs/BUGS.md.
    ///
    /// Copy-on-write, for the same reason as `functions_compiled`.
    pub function_source: crate::cow_map::CowHashMap<String, String>,
    /// Parent's THINGYTAB (ZLE widget registry) at subshell entry.
    /// zsh forks for `(...)` so `zle -N w f` / `zle -D w` inside the
    /// subshell flip widget bindings only in the child; when the
    /// child exits the parent's widget table is untouched. zshrs runs
    /// subshells in-process so a subshell's `zle -D w` would
    /// otherwise unbind the parent's widget. Bug #453 in docs/BUGS.md.
    pub thingytab: HashMap<String, crate::ported::zle::zle_thingy::Thingy>,
    /// Parent's KEYMAPNAMTAB (named keymap registry) at subshell
    /// entry. Same fork-copy semantics as THINGYTAB — a subshell's
    /// `bindkey -N km` / `bindkey -D km` mutates only the child's
    /// keymap registry in C zsh. Bug #454 in docs/BUGS.md.
    pub keymapnamtab:
        crate::ported::hashtable::hashtable_nodes<crate::ported::zle::zle_keymap::KeymapName>,
    /// Parent's `$!` (clone::lastpid) at subshell entry. C zsh forks
    /// for `(...)`, so a background job started INSIDE the subshell
    /// sets the child's `lastpid` only — `( : & ); echo $!` prints 0
    /// in zsh. zshrs runs subshells in-process, so restore on end.
    pub lastpid: i32,
    /// Job-control state at subshell entry: (JOBTAB clone, CURJOB,
    /// PREVJOB, MAXJOB, THISJOB). C zsh forks for `(...)` so any
    /// `disown` / `wait` / new `&` job inside the subshell mutates the
    /// CHILD's copy of jobtab and dies with it (Src/exec.c::entersubsh
    /// fork semantics); the parent's table is untouched. zshrs's
    /// in-process subshell must snapshot/restore to match — without
    /// this, `sleep 1 & (disown); jobs` shows an empty table where
    /// zsh still lists the job. Bug #462.
    pub jobtab: Vec<crate::ported::zsh_h::job>,
    /// `curjob` at subshell entry (Src/jobs.c:75 global).
    pub curjob: i32,
    /// `prevjob` at subshell entry (Src/jobs.c:80 global).
    pub prevjob: i32,
    /// `maxjob` at subshell entry (Src/jobs.c:71 global).
    pub maxjob: usize,
    /// `thisjob` at subshell entry (Src/jobs.c:77 global).
    pub thisjob: i32,
    /// `oldjobtab` / `oldmaxjob` at subshell entry (Src/jobs.c:101/104).
    /// The subshell's `clearjobtab` (c:1808-1825) saves the parent's jobs
    /// there; in C that copy lives in the forked child only, so the
    /// parent's own `oldjobtab` must come back unchanged or its `jobs`,
    /// `$jobstates` and `disown` would read the dead subshell's snapshot.
    pub oldjobtab: Vec<crate::ported::zsh_h::job>,
    pub oldmaxjob: usize,
    /// The descriptors 0-9 a bare `exec` redirection in the body moves
    /// are saved here on first touch and put back when this is dropped
    /// (see `crate::ported::exec::SubshFdFrame`). C zsh forks for `(...)`
    /// so the child's `exec >file` / `exec 3<&-` dies with it; without
    /// this, `(exec >t.log; ...); cat t.log` left the PARENT's fd 1
    /// pointing at t.log and `cat` looped forever copying the file into
    /// itself.
    pub fd_frame: crate::ported::exec::SubshFdFrame,
    /// `redirect_scope_stack` depth at entry. A body aborted by an error
    /// skips its `WithRedirectsEnd`; C's forked child takes those fds with
    /// it, so subshell_end unwinds to here.
    pub redir_depth: usize,
    /// Pipeline job slots held at entry (`exec_jobs::execpline_slots_mark`).
    /// Slots the body takes come from the cleared child table, so
    /// subshell_end drops their records along with that table.
    pub slots_mark: usize,
    /// `sigtrapped[]` at subshell entry (Src/signals.c:39). C's
    /// `entersubsh` clears per-signal trap STATE via `unsettrap(sig)`
    /// (c:Src/exec.c:1088-1092), which zeroes both the body and the
    /// sigtrapped flags. zshrs cleared only the body table, so the flags
    /// desynced: a subshell that dropped a trap body still reported the
    /// signal as trapped. Snapshot the whole vector so subshell_end can
    /// restore the parent's exact state (including an inherited
    /// ZSIG_IGNORED on SIGQUIT).
    pub sigtrapped: Vec<i32>,
    /// `subsh` at subshell entry (Src/exec.c:160 global). C's
    /// `entersubsh` sets `subsh = 1` for a real (non-ESUB_FAKE)
    /// subshell at c:Src/exec.c:1192-1193, and the forked child
    /// carries it for the whole body. PRINT_EXIT_VALUE reads it
    /// (c:4309 `&& !subsh`), which is why zsh prints nothing for
    /// `setopt printexitvalue; (false)` while still reporting a
    /// bare `false`. zshrs runs `( … )` in-process, so the flag has
    /// to be set on entry and restored by hand on End.
    pub subsh: i32,
    /// The libc locale on entry, as `setlocale(LC_ALL, NULL)` reports it.
    /// `LC_ALL=C` / `LANG=…` / `LC_CTYPE=…` inside the body reach libc via
    /// `setlang` / `lcsetfn` (c:Src/params.c:4811, c:4877), which in C
    /// changes only the forked child. The paramtab restore puts the
    /// parameters back without re-running their setfns, so the parent kept
    /// the child's locale: `() { (LC_ALL=C; true) }` left `${(q+)…}` quoting
    /// multibyte text as raw bytes for the rest of the script.
    pub locale: Option<std::ffi::CString>,
}

/// !!! WARNING: RUST-ONLY !!! C forks `( … )` and `$( … )`, so a locale the
/// body sets dies with the child. zshrs runs both in-process; this records
/// the parent's libc locale on entry for `subsh_locale_restore`.
pub(crate) fn subsh_locale_save() -> Option<std::ffi::CString> {
    let cur = unsafe { libc::setlocale(libc::LC_ALL, std::ptr::null()) };
    (!cur.is_null()).then(|| unsafe { std::ffi::CStr::from_ptr(cur) }.to_owned())
}

/// !!! WARNING: RUST-ONLY !!! Put back the locale `subsh_locale_save`
/// recorded, if the body changed it, and redo what the locale setfns do after
/// `setlocale` (c:Src/params.c:4841 `clear_mbstate()`, c:4842 `inittyptab()`).
/// Call it after the paramtab restore: inittyptab reads $IFS. The typtab is
/// rebuilt only when the locale differs, so an ordinary subshell does not
/// rewrite the table concurrent lexers read.
pub(crate) fn subsh_locale_restore(saved: Option<&std::ffi::CStr>) {
    let Some(loc) = saved else { return };
    let cur = unsafe { libc::setlocale(libc::LC_ALL, std::ptr::null()) };
    if !cur.is_null() && unsafe { std::ffi::CStr::from_ptr(cur) } == loc {
        return;
    }
    unsafe { libc::setlocale(libc::LC_ALL, loc.as_ptr()) };
    crate::ported::params::clear_mbstate();
    crate::ported::utils::inittyptab();
}

#[allow(unused_imports)]
pub(crate) use crate::ported::pattern::{
    extract_numeric_ranges, numeric_range_contains, numeric_ranges_to_star,
};

/// Top-level shell executor state.
/// Fork-equivalent event counter — incremented on every external
/// spawn and in-process subshell entry. C zsh's `time` keyword
/// reports only for JOBS (forked work, Src/jobs.c printtime via the
/// job table); zshrs runs builtins/braces/functions in-process with
/// no job, so the TIME_SUBLIST handler compares this counter across
/// the timed body to decide whether to emit the report.
pub static FORK_EVENTS: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0);

/// 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>,
    /// 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<InlineEnvFrame>,
    /// 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>,
    /// `jobs` field.
    pub jobs: JobTable,
    /// `fpath` field.
    pub fpath: Vec<PathBuf>,
    /// SQLite history index, opened on FIRST USE rather than at startup.
    ///
    /// Only `--doctor`, the cache report and `dbview history` read it, and
    /// none of them runs on a script or `-c` invocation — but opening it
    /// eagerly cost every `zshrs script.zsh` an sqlite open plus
    /// `init_schema` (0.40 ms of a 1.75 ms startup, measured with
    /// `ZSHRS_STARTUP_TRACE`). A pre-filled `None` is how a pool worker
    /// declares it must never open one.
    pub history: std::cell::OnceCell<Option<HistoryEngine>>,
    pub(crate) process_sub_counter: u32,
    pub completions: HashMap<String, CompSpec>, // command -> completion spec
    pub zstyles: Vec<zstyle_entry>,             // zstyle configurations
    /// 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,
    /// 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,
    /// `profiling_enabled` field.
    pub profiling_enabled: bool,
    // compsys - completion system cache
    /// `compsys_cache` field.
    /// SQLite mirror, opened on FIRST USE via [`ShellExecutor::compsys_cache`].
    ///
    /// It is a dbview/FTS mirror for inspection — the authoritative completion
    /// cache is the rkyv shards — so nothing on a normal command path touches
    /// it. Opening it in the constructor still cost every shell three file
    /// opens (`compsys.db`, `-wal`, `-shm`) plus WAL setup, including
    /// `zshrs -f -c exit`, which cannot consult it at all.
    pub compsys_cache: std::cell::OnceCell<Option<CompsysCache>>,
    // Background compinit — receiver for async fpath scan result
    /// `compinit_pending` field.
    pub compinit_pending: Option<(
        std::sync::mpsc::Receiver<CompInitBgResult>,
        std::time::Instant,
    )>,
    // Plugin source cache — stores side effects of source/. in SQLite
    /// `plugin_cache` field.
    pub plugin_cache: Option<crate::plugin_cache::PluginCache>,
    // cdreplay - deferred compdef calls for zinit turbo mode
    /// `deferred_compdefs` field.
    pub deferred_compdefs: Vec<Vec<String>>,
    // Control flow signals
    pub returning: Option<i32>, // Set by return builtin, cleared after function returns
    /// 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,
    /// 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)>>,
    /// Per-scope MULTIOS tee state. Each entry is `(pipe_write_fd,
    /// JoinHandle)`: the pipe write-end currently dup2'd onto the
    /// command's fd, and the splitter thread that reads from the
    /// pipe read-end and writes to every collected target. Closed
    /// + joined by `host_redirect_scope_end` BEFORE the saved fds
    /// are restored so the splitter drains every byte the body
    /// wrote into the pipe. Bug #36 in docs/BUGS.md.
    pub multios_scope_stack: Vec<Vec<(i32, std::thread::JoinHandle<()>)>>,
    /// True while applying a bare `exec`'s redirect list (`exec 1>&-`,
    /// `exec 2>/dev/null` — no command words). `host_apply_redirect`
    /// then skips pushing the saved fd into the enclosing scope so the
    /// fd change survives group/command teardown.
    /// c:Src/exec.c:3978-3986 — nullexec==1: "we specifically *don't*
    /// restore the original fd's before returning"; C's per-execcmd
    /// `save[]` means exec's redirs never enter the enclosing group's
    /// save list either. Toggled by `BUILTIN_EXEC_PERM_REDIRS`.
    pub exec_redirs_permanent: bool,
    /// Set in a forked pipeline-stage child right after its stdout is
    /// dup2'd onto the pipe write-end. Consumed by the FIRST
    /// `host_redirect_scope_begin` (the stage command's own redirect
    /// list) into `pipe_output_scope`.
    /// c:Src/exec.c:3722-3724 — `addfd(forked, save, mfds, 1, output,
    /// 1, NULL)`: the pipe occupies mfds[1] in the SAME execcmd that
    /// processes the stage command's redirect list.
    pub pipe_output_pending: bool,
    /// Index into `redirect_scope_stack` of the scope whose redirect
    /// list shares an execcmd with the pipeline output on fd 1. A
    /// write-side redirect of fd 1 applied at exactly this scope depth
    /// MULTIOS-splits (tees) instead of replacing — c:Src/exec.c:
    /// 2447-2480 addfd "split the stream". Cleared when that scope ends.
    pub pipe_output_scope: Option<usize>,
    /// 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,
    /// 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.
    ///
    /// COPY-ON-WRITE. `$( … )` and `( … )` snapshot this whole map for
    /// subshell isolation (Bug #208), so a plain `HashMap` made entering
    /// a substitution cost one `Chunk` clone per compiled function. It
    /// is a `CowHashMap`, so the snapshot shares and the first write
    /// inside the body splits. Reads and writes are unchanged —
    /// `Deref`/`DerefMut` keep every call site as it was.
    pub functions_compiled: crate::cow_map::CowHashMap<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])`.
    ///
    /// Copy-on-write for the same reason as `functions_compiled`: a
    /// subshell snapshots it whole, and the body usually never writes.
    pub function_source: crate::cow_map::CowHashMap<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]`.
    /// 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)>,

    // ── ztest framework counters (extensions/ztest.rs) ──────────────────
    //
    // Mirrors strykelang's per-VMHelper test counters
    // (strykelang/builtins.rs:22292-22308 + builtins.rs::test_pass/_fail/_skip,
    //  builtins.rs::test_pass_count etc.). Each `zassert_*` builtin bumps
    // the per-block counter; `ztest_run` rolls per-block into _total and
    // resets the per-block side, so a single test file with multiple
    // `ztest_run` calls can reuse the counters. The worker-pool runner in
    // src/extensions/ztest.rs reads pass_total+pass_count and
    // fail_total+fail_count after `execute_script` returns for the cumulative
    // numbers (strykelang/cli_runners.rs:115-118). `ztest_run_failed` is a
    // sticky bool the runner reads so a test that asserts but then exits
    // 0 still flags as failed. `ztest_suppress_stdout` matches
    // VMHelper::suppress_stdout — the runner sets it inside the forked
    // grandchild so the per-test stderr capture stays clean.
    /// Per-block pass count (reset by `ztest_run`).
    pub ztest_pass_count: std::sync::atomic::AtomicUsize,
    /// Per-block fail count (reset by `ztest_run`).
    pub ztest_fail_count: std::sync::atomic::AtomicUsize,
    /// Per-block skip count (reset by `ztest_run`).
    pub ztest_skip_count: std::sync::atomic::AtomicUsize,
    /// Cumulative pass total across the run.
    pub ztest_pass_total: std::sync::atomic::AtomicUsize,
    /// Cumulative fail total across the run.
    pub ztest_fail_total: std::sync::atomic::AtomicUsize,
    /// Cumulative skip total across the run.
    pub ztest_skip_total: std::sync::atomic::AtomicUsize,
    /// Sticky failure flag — set by any `ztest_run` that observed fails;
    /// the CLI runner reads this so a test that asserts then exits 0
    /// still counts as a failed file.
    pub ztest_run_failed: std::sync::atomic::AtomicBool,
    /// Suppress per-assertion `✓`/`✗` lines on stderr. Set by the worker
    /// runner inside the forked child when it has already redirected
    /// fd 2 to a tmp file (we still want the lines, but only after the
    /// runner re-emits them under print_lock to avoid line-tearing).
    pub ztest_suppress_stdout: bool,
}

/// Context-isolated nested parse — the AST-path bridge for C's
/// `parse_string` (`Src/exec.c:283`). zshrs executes via the ZshProgram
/// AST + `compile_zsh`, not wordcode, so this can't live in `src/ported/`
/// (C's `parse_string` returns `Eprog`, and the build.rs port-gate rejects
/// any non-C-named fn there). It's the bridge that wraps the AST
/// `parse_init`+`parse` in the SAME isolation `parse_string` provides.
///
/// Why this exists: a runtime parse — command-substitution body,
/// process-substitution argv — must not clobber the outer
/// `loop()`/`parse_event` reader's live input when it interleaves parsing
/// with execution (faithful single-event mode).
///
/// The load-bearing piece is `strinbeg(0)`/`strinend()` (c:290/298). It
/// sets the `strin` flag so that when the nested lexer drains `cmd_str`,
/// `ingetc` returns EOF (input.rs:391) instead of falling through to
/// `inputline()`, which would STEAL the outer reader's next SHIN line —
/// e.g. `echo A` / `v=$(echo hi)` / `echo B` had the cmd-subst swallow
/// `echo B` off stdin, and the outer loop then hit EOF after one command.
/// `strinbeg` also runs `hbegin`/`lexinit`, so it must execute on isolated
/// history+lexer state — hence the surrounding `zcontext_save`/`restore`
/// (c:288/300), which saves+restores `tok`/`tokstr`/`lexbuf`/`isnewlin`/
/// `incmdpos`/heredocs/`lexstop`/`toklineno`/history.
///
/// Two zshrs-specific globals `zcontext` doesn't cover are saved here too:
/// the lexer-input window (`LEX_INPUT`/`LEX_POS`/`LEX_UNGET_BUF`) that
/// `lex_init` overwrites with `cmd_str`, and the line counter `LEX_LINENO`
/// (C saves `oldlineno` explicitly at parse_string c:291/295).
///
/// NOTE: using `inpush` (the literal C input stack) instead does NOT work
/// in zshrs's hybrid input model — the outer piped reader pulls from SHIN
/// via `inputline`, and pushing/popping the `inbuf` stack severs that
/// continuation. The `LEX_INPUT` window + `strin` flag is the working
/// equivalent.
pub(crate) fn parse_isolated(input: &str) -> crate::parse::ZshProgram {
    parse_isolated_at(input, None)
}

/// `parse_isolated` with C's `reset_lineno` argument inverted: `Some(n)` is
/// `parse_string(s, 0)` (c:Src/exec.c:291-293), which parses from the line the
/// shell is executing, `n`, instead of from line 1. A parse error in a body
/// parsed at run time (`` `…` `` in getoutput c:4778) then carries that line,
/// or none at all when it is 0 (c:Src/utils.c:301).
pub(crate) fn parse_isolated_at(input: &str, lineno: Option<u64>) -> crate::parse::ZshProgram {
    use crate::ported::lex::{
        tok, LEXERR, LEX_INPUT, LEX_LINENO, LEX_POS, LEX_UNGET_BUF, LEX_FILE_WINDOW_STRIN,
    };

    // Inline Rust FFI: rewrite every `rust { ... }` block into a
    // `__rust_compile '<base64>' <line>` command before it reaches the lexer.
    // This is the shared source-string chokepoint for `-c`, script files, and
    // nested (command/process-substitution) parses. The `.contains("rust")`
    // gate keeps the common case (no FFI block) allocation-free — the vast
    // majority of nested parses never mention `rust`.
    let ffi_desugared = input
        .contains("rust")
        .then(|| crate::rust_ffi::desugar(input));
    let input: &str = ffi_desugared.as_deref().unwrap_or(input);

    crate::ported::context::zcontext_save(); // c:288
                                             // Save the zshrs-specific lexer window + line counter that lex_init
                                             // overwrites but zcontext doesn't cover.
    let saved_input = LEX_INPUT.with_borrow(|s| s.clone());
    let saved_pos = LEX_POS.get();
    let saved_unget = LEX_UNGET_BUF.with_borrow(|b| b.clone());
    let saved_lineno = LEX_LINENO.get(); // c:291 oldlineno
    // The nested parse installs its own window; `lex_init` marks it a
    // string unit. Put the outer window's kind back with the window.
    let saved_file_window = LEX_FILE_WINDOW_STRIN.get();
                                         // input.rs `lexstop` is the input-side half of C's single `lexstop`;
                                         // draining the nested LEX_INPUT sets it true and zcontext only covers
                                         // the lex.rs half (LEX_LEXSTOP). Restore it so the outer reader isn't
                                         // left at EOF.
    let saved_in_lexstop = crate::ported::input::lexstop.with(|c| c.get());

    // c:Src/exec.c:294 `inpush(s, INP_LINENO, NULL)` — the nested parse
    // gets its own input frame, so whatever the OUTER reader still has
    // queued is parked on the input stack until the inpop below. The text
    // itself is lexed from LEX_INPUT (parse_init), so the pushed frame is
    // empty: once that window drains, ingetc hits the end of THIS frame
    // and returns EOF. Without the frame it fell through to the outer
    // buffer — the rest of a multi-line command line, still unread while
    // `preexec` ran an `eval` or `$(…)` — and swallowed it.
    crate::ported::input::inpush("", crate::ported::zsh_h::INP_LINENO, None);
    crate::ported::hist::strinbeg(0); // c:290 — strin++ → drained nested input EOFs (no SHIN steal)
    crate::ported::parse::parse_init(input); // install cmd_str as LEX_INPUT (lex_init), LEX_LINENO=1
    if let Some(n) = lineno {
        LEX_LINENO.set(n); // c:292 `if (reset_lineno)` not taken: keep the running line
    }
    let program = crate::ported::parse::parse(); // c:294 (AST analog of par_list)

    // Capture parse failure BEFORE the restores wipe the signals.
    let parse_err = (errflag.load(Ordering::Relaxed) & ERRFLAG_ERROR) != 0 || tok() == LEXERR;
    if tok() == LEXERR && crate::ported::builtin::LASTVAL.load(Ordering::Relaxed) == 0 {
        crate::ported::builtin::LASTVAL.store(1, Ordering::Relaxed); // c:296-297
    }

    crate::ported::hist::strinend(); // c:298 — strin--
    // c:Src/exec.c:304 `inpop()` — pops the pushed frame AND its continuations. An
    // alias expanded at the end of the body sits on top as an
    // INP_ALIAS|INP_CONT frame (c:Src/input.c:695), so this is also where its
    // `inuse` is cleared (c:Src/input.c:773): left behind, the alias stayed
    // `inuse` and every later `$(m)` / `m` reported "command not found".
    // Popping the frame pushed above restores the outer reader's queue.
    crate::ported::input::inpop();
                                     // Restore the zshrs window, then the token/parse/history state.
    LEX_INPUT.with_borrow_mut(|s| *s = saved_input);
    LEX_POS.set(saved_pos);
    LEX_UNGET_BUF.with_borrow_mut(|b| *b = saved_unget);
    LEX_LINENO.set(saved_lineno); // c:295
    LEX_FILE_WINDOW_STRIN.set(saved_file_window);
    crate::ported::input::lexstop.with(|c| c.set(saved_in_lexstop));
    crate::ported::context::zcontext_restore(); // c:300
                                                // zcontext_restore → parse_context_restore clears ERRFLAG_ERROR
                                                // (parse.c:354); re-raise so callers gating on the bit still see it.
    if parse_err {
        errflag.fetch_or(ERRFLAG_ERROR, Ordering::Relaxed);
    }
    program
}

/// Build the `scriptname[:lineno]` prefix zsh puts on an execution error.
///
/// c:Src/utils.c:301 — `zerrmsg` prints the line number ONLY when it is
/// non-zero: `if ((unset(SHINSTDIN) || locallevel) && lineno) fprintf(file,
/// "%lld: ", lineno);`. The command-not-found / no-such-file / permission-denied
/// sites below emit DIRECTLY rather than through `zerr` (deliberately — see
/// their comments, routing through zerr would set errflag and abort a script
/// that zsh continues), but they hand-rolled `"{}:{}"` and so printed a bare
/// `:0` inside a one-line function where zsh prints no line number at all:
/// `f(){ nosuchcmd }; f` gave `f:0: command not found:` vs zsh's `f: command
/// not found:`. Mirrors the C condition exactly. Bug #1070.
fn zerr_prefix(sn: &str) -> String {
    let lineno = crate::ported::lex::lineno();
    let ll = crate::ported::params::locallevel.load(std::sync::atomic::Ordering::Relaxed);
    if (crate::ported::zsh_h::unset(crate::ported::zsh_h::SHINSTDIN) || ll != 0) && lineno != 0 {
        format!("{}:{}", sn, lineno)
    } else {
        sn.to_string()
    }
}

thread_local! {
    /// `(function name, its source file)` while that function's AUTOLOAD body
    /// is being run. Empty at every other moment.
    pub static AUTOLOAD_DEF_FILE: std::cell::RefCell<Vec<(String, String)>> =
        const { std::cell::RefCell::new(Vec::new()) };
}

/// Scope guard for [`AUTOLOAD_DEF_FILE`].
pub struct AutoloadFileGuard(bool);

impl AutoloadFileGuard {
    fn enter(name: &str) -> Self {
        match crate::ported::hashtable::getshfuncfile(name) {
            Some(f) => {
                AUTOLOAD_DEF_FILE.with(|s| s.borrow_mut().push((name.to_string(), f)));
                Self(true)
            }
            None => Self(false),
        }
    }
}

impl Drop for AutoloadFileGuard {
    fn drop(&mut self) {
        if self.0 {
            AUTOLOAD_DEF_FILE.with(|s| {
                s.borrow_mut().pop();
            });
        }
    }
}

/// The file `name` is being autoloaded from, if that is happening right now.
pub fn autoload_def_file(name: &str) -> Option<String> {
    AUTOLOAD_DEF_FILE.with(|s| {
        s.borrow()
            .iter()
            .rev()
            .find(|(n, _)| n == name)
            .map(|(_, f)| f.clone())
    })
}

/// !!! WARNING: RUST-ONLY HELPER — NO DIRECT C COUNTERPART !!!
///
/// C's `zexecve` (Src/exec.c:504-643) performs the whole `#!` recovery
/// in place: it is only ever reached in the already-forked child that is
/// about to BECOME the command, so at c:566/571/581/585/627 it simply
/// calls `execve()` a second time and never returns. zshrs reaches the
/// same decision from a second call site — the `std::process::Command`
/// spawn in `vm_helper::execute_external_bg` — which hands argv to the
/// kernel from the PARENT process and therefore cannot "re-exec in
/// place". This helper is c:534-634 verbatim with each of those five
/// `execve(prog, argv)` calls replaced by `Ok((prog, argv))`, so both
/// call sites share one implementation of the shebang rules.
///
/// `Err(eno)` is what C's `return eno` (c:643) would hand back — either
/// the original `eno` or the `errno` from a failed open/read (c:632/634).
#[allow(non_snake_case)]
pub fn zexecve_recover(pth: &str, argv: &[String], eno: i32) -> Result<(String, Vec<String>), i32> {
    if eno == libc::ENOEXEC || eno == libc::ENOENT {
        // c:534
        let cpth = match std::ffi::CString::new(pth) {
            Ok(c) => c,
            Err(_) => return Err(libc::ENOENT),
        };
        let fd = unsafe { libc::open(cpth.as_ptr(), libc::O_RDONLY | libc::O_NOCTTY) }; // c:538
        if fd < 0 {
            // c:633-634 — `} else eno = errno;` then fall through to `return eno`.
            return Err(std::io::Error::last_os_error()
                .raw_os_error()
                .unwrap_or(libc::ENOENT));
        }
        let mut buf = vec![0u8; crate::ported::exec::POUNDBANGLIMIT + 1]; // c:541
        let ct = unsafe {
            libc::read(
                fd,
                buf.as_mut_ptr() as *mut libc::c_void,
                crate::ported::exec::POUNDBANGLIMIT as libc::size_t,
            )
        }; // c:542
        unsafe {
            libc::close(fd);
        } // c:543
        if ct >= 0 {
            // c:544
            let ct = ct as usize;
            if ct >= 2 && buf[0] == b'#' && buf[1] == b'!' {
                // c:545
                let mut t0 = 0;
                while t0 < ct && buf[t0] != b'\n' {
                    t0 += 1;
                } // c:546-548
                if t0 == ct {
                    // c:549
                    // c:550 `zerr(...)`. C is inside the forked child that is
                    // about to `_exit`, so the errflag `zerr` raises is
                    // irrelevant there. This runs in the PARENT, where a raised
                    // errflag aborts the enclosing script — `( if
                    // bad-interp-cmd; then exit 0; else exit 1; fi )` returned
                    // 127 instead of running its else branch. `zwarn`
                    // (utils.rs:260) emits the identical text without the flag.
                    crate::ported::utils::zwarn(&format!(
                        // c:550
                        "{}: bad interpreter: {}: {}",
                        pth,
                        String::from_utf8_lossy(&buf[2..t0.min(ct)]),
                        std::io::Error::from_raw_os_error(eno)
                    ));
                } else {
                    // c:552
                    while t0 > 0 && (buf[t0] == b' ' || buf[t0] == b'\t' || buf[t0] == b'\n') {
                        buf[t0] = 0;
                        t0 -= 1;
                    } // c:553-554
                    let mut ptr_lo: usize = 2;
                    while ptr_lo < buf.len() && buf[ptr_lo] == b' ' {
                        ptr_lo += 1;
                    } // c:555
                    let ptr2_lo = ptr_lo;
                    let mut ptr_hi = ptr2_lo;
                    while ptr_hi < buf.len() && buf[ptr_hi] != 0 && buf[ptr_hi] != b' ' {
                        ptr_hi += 1;
                    } // c:556
                    let interp_str = String::from_utf8_lossy(&buf[ptr2_lo..ptr_hi]).into_owned();
                    if eno == libc::ENOENT {
                        // c:557 — pathprog rewrite path.
                        let pprog = if !interp_str.starts_with('/') {
                            // c:561
                            crate::ported::utils::pathprog(&interp_str)
                                .map(|p| p.display().to_string())
                        } else {
                            None
                        };
                        if let Some(pprog) = pprog {
                            // c:562
                            let mut argv_new: Vec<String> = Vec::with_capacity(argv.len() + 2);
                            argv_new.push(interp_str.clone()); // c:564
                            if ptr_hi >= buf.len() || buf[ptr_hi] == 0 {
                                argv_new.push(pth.to_string());
                            } else {
                                // c:567
                                let mut rest_lo = ptr_hi + 1;
                                while rest_lo < buf.len() && buf[rest_lo] == b' ' {
                                    rest_lo += 1;
                                }
                                let mut rest_hi = rest_lo;
                                while rest_hi < buf.len() && buf[rest_hi] != 0 {
                                    rest_hi += 1;
                                }
                                let arg_str =
                                    String::from_utf8_lossy(&buf[rest_lo..rest_hi]).into_owned();
                                argv_new.push(arg_str);
                                argv_new.push(pth.to_string());
                            }
                            for orig in argv.iter().skip(1) {
                                argv_new.push(orig.clone());
                            }
                            // c:565/c:570 — `winch_unblock(); execve(...)`.
                            // Deliberately NOT ported here. In C that unblock is
                            // the last statement before `execve` in the FORKED
                            // CHILD, so all it decides is the mask the new
                            // program starts with; the parent never sees it.
                            // This resolver runs in the PARENT (see the c:550
                            // note above) and RETURNS, so calling it dropped the
                            // shell's standing `winch_block()`
                            // (c:Src/init.c:1458) with nothing here to re-arm
                            // it. The next re-arm is whenever `raw_getbyte`
                            // returns from its read (zle_main.rs:507/654/762),
                            // so the leak spans the REST OF THE CURRENT COMMAND,
                            // not the session — and a completer that execs a
                            // shebang-less script therefore finishes its
                            // completion with the handler live. That is the one
                            // state c:1458 exists to prevent: `adjustwinsize(1)`
                            // inside a widget makes `calclist` count display
                            // strings against a width they were not built at,
                            // and repaints over the prompt row.
                            //
                            // The new image still gets SIGWINCH unblocked: the
                            // child-side `zexecve` unblocks at c:527 (ported at
                            // src/ported/exec.rs:4215), and the spawn-based
                            // callers of this function go through
                            // `std::process::Command`, whose child resets the
                            // signal mask to empty before `execvp`.
                            return Ok((pprog, argv_new)); // c:566/c:571
                        }
                        crate::ported::utils::zwarn(&format!(
                            // c:574 — `zerr`; see the c:550 note above for why
                            // this is `zwarn` in the parent-side port.
                            "{}: bad interpreter: {}: {}",
                            pth,
                            interp_str,
                            std::io::Error::from_raw_os_error(eno)
                        ));
                    } else if ptr_hi < buf.len() && buf[ptr_hi] != 0 {
                        // c:576
                        let mut rest_lo = ptr_hi + 1;
                        while rest_lo < buf.len() && buf[rest_lo] == b' ' {
                            rest_lo += 1;
                        }
                        let mut rest_hi = rest_lo;
                        while rest_hi < buf.len() && buf[rest_hi] != 0 {
                            rest_hi += 1;
                        }
                        let arg_str = String::from_utf8_lossy(&buf[rest_lo..rest_hi]).into_owned();
                        let mut argv_new: Vec<String> =
                            vec![interp_str.clone(), arg_str, pth.to_string()];
                        for orig in argv.iter().skip(1) {
                            argv_new.push(orig.clone());
                        }
                        // c:580 — `winch_unblock()` omitted: child-side in C,
                        // parent-side here. See the c:565/c:570 note above.
                        return Ok((interp_str, argv_new)); // c:581
                    } else {
                        // c:582
                        let mut argv_new: Vec<String> = vec![interp_str.clone(), pth.to_string()];
                        for orig in argv.iter().skip(1) {
                            argv_new.push(orig.clone());
                        }
                        // c:584 — `winch_unblock()` omitted: child-side in C,
                        // parent-side here. See the c:565/c:570 note above.
                        return Ok((interp_str, argv_new)); // c:585
                    }
                }
            } else if eno == libc::ENOEXEC {
                // c:588 — binary-safety + /bin/sh fallback.
                let nul_pos = buf[..ct].iter().position(|&b| b == 0); // c:597
                let isbinary = match nul_pos {
                    None => false, // c:598
                    Some(npos) => {
                        let mut has_letter = false;
                        let mut binary = true;
                        for &b in &buf[..npos] {
                            // c:602-609
                            if (b as char).is_ascii_lowercase() || b == b'$' || b == b'`' {
                                has_letter = true;
                            }
                            if has_letter && b == b'\n' {
                                binary = false; // c:606
                                break;
                            }
                        }
                        binary
                    }
                };
                if !isbinary {
                    // c:611
                    let mut argv_new: Vec<String> = Vec::with_capacity(argv.len() + 2);
                    argv_new.push("sh".to_string()); // c:625
                    // c:544 — `*argv = pth;`: by now argv[0] IS the path
                    // being executed, not the command word, so both the
                    // `-`/`+` guard and the operand handed to sh are `pth`.
                    // Testing the word let `PATH=-dir tstcmd` hand sh
                    // `-dir/tstcmd` with no `-` guard (sh: `-d: invalid
                    // option`), and ran a bare-word script as `sh tstcmd`.
                    if pth.starts_with('-') || pth.starts_with('+') {
                        argv_new.push("-".to_string()); // c:623
                    }
                    argv_new.push(pth.to_string()); // c:544
                    for orig in argv.iter().skip(1) {
                        argv_new.push(orig.clone());
                    }
                    // c:626 — `winch_unblock()` omitted: child-side in C,
                    // parent-side here. See the c:565/c:570 note above.
                    return Ok(("/bin/sh".to_string(), argv_new)); // c:627
                }
            }
        }
    }
    Err(eno) // c:643
}


/// !!! WARNING: RUST-ONLY HELPER — the non-forking form of `execute()`'s
/// search (Src/exec.c:791-895) !!!
///
/// C runs `execute()` in the forked child, where every `zexecve` either
/// replaces the process or returns an errno and the walk moves on to the
/// next candidate. zshrs spawns from the parent, so each `zexecve` here is a
/// `posix_spawn(2)` attempt (`zexecve_spawn`) and the first one that starts a
/// process ends the walk with its pid. The candidates, their order and the
/// `isgooderr` bookkeeping are C's:
///
/// * c:791-801 — an `arg0` holding a `/` is exec'd as spelled; unless it is
///   relative, not `./…`/`../…`, and PATH_DIRS is set, a failure is final.
/// * c:803-819 — `command -p`: the default-path hit alone.
/// * c:822-870 — the `cmdnamtab` candidate, then c:877-895
///   `execute_skip_exec:`, the full `$path` walk (empty and `.` entries
///   mean `arg0` itself).
///
/// `Err(eno)` is C's `eno` at c:871: non-zero means `zerr("%e: %s")`, zero
/// means nothing usable was found (`command not found`).
pub(crate) fn execute_spawn(
    arg0: &str,
    argv: &[String],
    defpath: Option<&str>,
    hashed: Option<&str>,
    drop_argv0: bool,
    in_place: bool,
) -> Result<libc::pid_t, i32> {
    use crate::ported::exec::isgooderr;
    // c:791-801
    if let Some(slash) = arg0.find('/') {
        let lerrno = match zexecve_spawn(arg0, argv, drop_argv0, in_place) {
            Ok(pid) => return Ok(pid),
            Err(e) => e,
        }; // c:793
        let dotted = arg0.starts_with('.')
            && (slash == 1 || (arg0.starts_with("..") && slash == 2));
        if slash == 0 || crate::ported::zsh_h::unset(crate::ported::zsh_h::PATHDIRS) || dotted {
            return Err(lerrno); // c:794-798
        }
    }
    let mut eno = 0;
    let mut attempt = |pth: &str, dir: &str| -> Option<libc::pid_t> {
        match zexecve_spawn(pth, argv, drop_argv0, in_place) {
            Ok(pid) => Some(pid),
            Err(ee) => {
                if isgooderr(ee, dir) {
                    eno = ee;
                }
                None
            }
        }
    };
    let dir_of = |p: &str| -> String {
        // c:817-818 / c:866-867 — `if ((dptr = strrchr(nn, '/'))) *dptr =
        // '\0'; isgooderr(ee, *nn ? nn : "/")`.
        match p.rfind('/') {
            Some(0) | None => "/".to_string(),
            Some(i) => p[..i].to_string(),
        }
    };
    if let Some(pbuf) = defpath {
        // c:815 — `ee = zexecve(pbuf, argv, newenvp);`
        if let Some(pid) = attempt(pbuf, &dir_of(pbuf)) {
            return Ok(pid);
        }
        return Err(eno);
    }
    if let Some(nn) = hashed {
        // c:863 — `ee = zexecve(nn, argv, newenvp);`
        if let Some(pid) = attempt(nn, &dir_of(nn)) {
            return Ok(pid);
        }
    }
    // c:877 `execute_skip_exec:` — `for (pp = path; *pp; pp++)`.
    let path = crate::ported::params::getaparam("path").unwrap_or_default();
    for pp in &path {
        let pth = if pp.is_empty() || pp == "." {
            arg0.to_string() // c:879-880
        } else {
            format!("{}/{}", pp, arg0) // c:884-888
        };
        if pth.len() >= libc::PATH_MAX as usize {
            continue; // c:887-888
        }
        if let Some(pid) = attempt(&pth, pp) {
            return Ok(pid); // c:890 `ee = zexecve(buf, argv, newenvp);`
        }
    }
    Err(eno)
}

/// !!! WARNING: RUST-ONLY HELPER — `zexecve()` (Src/exec.c:504-643) from the
/// parent via `posix_spawn(2)` !!!
///
/// Same steps as the forked-child port (`crate::ported::exec::zexecve`), with
/// each `execve` a `posix_spawn` of the SAME path — never `posix_spawnp`,
/// whose libc-internal `/bin/sh` fallback on ENOEXEC runs a shebang-less
/// script without C's `-`/`+` operand guard (c:611-624) and so hands
/// `-dir/tstcmd` to sh as an option. The kernel's refusal comes back here
/// and `zexecve_recover` makes C's decision.
///
/// The environment is the child's `environ` as C leaves it right before
/// `execve`, built as a copy so the parent's own array is untouched (C does
/// these writes in the child that is about to vanish):
///
/// * c:514-520 — `zputenv("_=<pth>")`: an existing `_` entry is replaced in
///   place, otherwise the entry is appended.
/// * c:765-768 (`execute`) — `unsetenv("ARGV0")` when ARGV0 supplied argv[0].
///
/// The array keeps `environ`'s order: `std::process::Command` rebuilds any
/// environment it modifies from a sorted map, so externals saw the variables
/// alphabetically instead of in the order the shell added them.
fn zexecve_spawn(pth: &str, argv: &[String], drop_argv0: bool, in_place: bool) -> Result<libc::pid_t, i32> {
    use std::ffi::CString;
    use std::os::unix::ffi::OsStrExt as _;
    // c:514-520 — `_=pth`, made absolute against `pwd`.
    let underscore = if pth.starts_with('/') {
        pth.to_string() // c:516-517
    } else {
        format!("{}/{}", crate::ported::params::getsparam("PWD").unwrap_or_default(), pth) // c:519
    };
    let mut underscore_entry = b"_=".to_vec();
    underscore_entry.extend_from_slice(&crate::ported::utils::unmetafy_str(&underscore));
    let mut envp: Vec<CString> = Vec::new();
    let mut have_underscore = false;
    for (k, v) in std::env::vars_os() {
        let k = k.as_bytes();
        if drop_argv0 && k == b"ARGV0" {
            continue; // c:768 `unsetenv("ARGV0")`
        }
        let entry = if k == b"_" {
            have_underscore = true;
            underscore_entry.clone() // c:520 — replaced in place
        } else {
            let mut e = k.to_vec();
            e.push(b'=');
            e.extend_from_slice(v.as_bytes());
            e
        };
        if let Ok(c) = CString::new(entry) {
            envp.push(c);
        }
    }
    if !have_underscore {
        if let Ok(c) = CString::new(underscore_entry) {
            envp.push(c); // c:520 — appended
        }
    }
    // c:528 — `execve(pth, argv, newenvp);`
    let eno = match posix_spawn_argv(pth, argv, &envp, in_place) {
        Ok(pid) => return Ok(pid),
        Err(eno) => eno,
    };
    // c:534-634 — the kernel refused the file: the `#!` line's interpreter,
    // or `/bin/sh` for a shebang-less script.
    match zexecve_recover(pth, argv, eno) {
        // c:566/571/581/585/627 — the second `execve`; when it fails too, C
        // falls through to c:643 `return eno` with the ORIGINAL errno.
        Ok((prog, newargv)) => posix_spawn_argv(&prog, &newargv, &envp, in_place).map_err(|_| eno),
        Err(e) => Err(e), // c:632/634/643
    }
}

/// !!! WARNING: RUST-ONLY HELPER — the dispositions `entersubsh` resets in the
/// child C forks for an external, applied at the spawn instead !!!
///
/// c:Src/exec.c:1185-1193 —
/// ```c
/// if (interact) {
///     signal_default(SIGTERM);
///     if (!(sigtrapped[SIGINT] & ZSIG_IGNORED))
///         signal_default(SIGINT);
///     if (!(sigtrapped[SIGPIPE]))
///         signal_default(SIGPIPE);
/// }
/// if (!(sigtrapped[SIGQUIT] & ZSIG_IGNORED))
///     signal_default(SIGQUIT);
/// ```
/// The shell ignores SIGQUIT always and SIGTERM when interactive
/// (c:Src/init.c:1448/1463), and SIG_IGN survives `execve`, so without this a
/// spawned `sh -c 'kill -QUIT $$'` survived its own signal. SIGPIPE is reset
/// unless a `trap '' PIPE` ignores it: C never ignores it otherwise, but the
/// Rust runtime does. The job-control stops (c:1174-1183) stay as they are: a foreground
/// wait here does not watch for a stopped child, so a ^Z'd child would hang
/// the shell.
fn entersubsh_sigdef() -> Vec<i32> {
    use crate::ported::zsh_h::{isset, INTERACTIVE, ZSIG_IGNORED};
    let trapped = |sig: i32| -> i32 {
        crate::ported::signals::sigtrapped
            .lock()
            .ok()
            .and_then(|t| t.get(sig as usize).copied())
            .unwrap_or(0)
    };
    let mut sigs = Vec::with_capacity(4);
    if trapped(libc::SIGPIPE) & ZSIG_IGNORED == 0 {
        sigs.push(libc::SIGPIPE); // c:1189-1190, and the Rust runtime's ignore
    }
    if isset(INTERACTIVE) {
        sigs.push(libc::SIGTERM); // c:1186
        if trapped(libc::SIGINT) & ZSIG_IGNORED == 0 {
            sigs.push(libc::SIGINT); // c:1187-1188
        }
    }
    if trapped(libc::SIGQUIT) & ZSIG_IGNORED == 0 {
        sigs.push(libc::SIGQUIT); // c:1192-1193
    }
    sigs
}

/// !!! WARNING: RUST-ONLY HELPER — the signal mask the child C forks for an
/// external carries into `execve`, computed in the parent instead !!!
///
/// The child inherits the shell's mask minus what C unblocks on the way to
/// the exec:
///
/// * c:Src/exec.c:1162-1166 (`entersubsh`) — while `intrap`, every trapped,
///   non-ignored signal is unblocked: the trap dispatcher blocks the signal
///   being handled, and a command run from the trap body must not inherit it.
/// * c:Src/exec.c:751 (`execute`) — `child_unblock()` right before the
///   `zexecve` walk, so SIGCHLD is never blocked in an external.
///
/// Without this a command run from a `trap '...' USR2` handler started with
/// SIGUSR2 blocked, and every external started with SIGCHLD blocked.
fn execute_sigmask() -> libc::sigset_t {
    use crate::ported::signals_h::SIGCOUNT;
    use crate::ported::zsh_h::ZSIG_IGNORED;
    unsafe {
        let mut mask: libc::sigset_t = std::mem::zeroed();
        libc::sigemptyset(&mut mask);
        libc::pthread_sigmask(libc::SIG_BLOCK, std::ptr::null(), &mut mask);
        if crate::ported::signals::intrap.load(std::sync::atomic::Ordering::Relaxed) != 0 {
            // c:1163-1166 — `for (sig = 1; sig <= SIGCOUNT; sig++) if
            // (sigtrapped[sig] && sigtrapped[sig] != ZSIG_IGNORED)
            // signal_unblock(signal_mask(sig));`
            let trapped = crate::ported::signals::sigtrapped
                .lock()
                .map(|t| t.clone())
                .unwrap_or_default();
            for sig in 1..=SIGCOUNT {
                let st = trapped.get(sig as usize).copied().unwrap_or(0);
                if st != 0 && st != ZSIG_IGNORED {
                    libc::sigdelset(&mut mask, sig);
                }
            }
        }
        libc::sigdelset(&mut mask, libc::SIGCHLD); // c:751 `child_unblock();`
        mask
    }
}

/// !!! WARNING: RUST-ONLY HELPER — the `posix_spawn(2)` call standing in for
/// `execve(2)` in `zexecve_spawn` !!!
///
/// argv and path are unmetafied first, as C's `zexecve` does at c:510-513
/// (`$'\xff'` reaches the child as the raw byte). The child starts with
/// `execute_sigmask`'s mask and `entersubsh_sigdef`'s dispositions.
///
/// `in_place` is c:Src/exec.c:4369 in a child already forked for the command
/// (`last1 = forked = 1`, c:3063): `execve(2)` replaces this process instead
/// of spawning, and returns only on failure.
fn posix_spawn_argv(
    pth: &str,
    argv: &[String],
    envp: &[std::ffi::CString],
    in_place: bool,
) -> Result<libc::pid_t, i32> {
    use std::ffi::CString;
    let cstr = |s: &str| {
        let mut b = crate::ported::utils::unmetafy_str(s);
        if let Some(n) = b.iter().position(|c| *c == 0) {
            b.truncate(n); // a C string ends at its first NUL
        }
        CString::new(b).unwrap_or_default()
    };
    let cpth = cstr(pth);
    let cargs: Vec<CString> = argv.iter().map(|a| cstr(a)).collect();
    let mut argv_ptrs: Vec<*mut libc::c_char> = cargs.iter().map(|c| c.as_ptr() as *mut _).collect();
    argv_ptrs.push(std::ptr::null_mut());
    let mut envp_ptrs: Vec<*mut libc::c_char> = envp.iter().map(|c| c.as_ptr() as *mut _).collect();
    envp_ptrs.push(std::ptr::null_mut());
    let sigdef = entersubsh_sigdef();
    let sigmask = execute_sigmask();
    unsafe {
        if in_place {
            for &sig in &sigdef {
                libc::signal(sig, libc::SIG_DFL);
            }
            libc::pthread_sigmask(libc::SIG_SETMASK, &sigmask, std::ptr::null_mut());
            libc::execve(cpth.as_ptr(), argv_ptrs.as_ptr() as *const *const _, envp_ptrs.as_ptr() as *const *const _);
            return Err(std::io::Error::last_os_error().raw_os_error().unwrap_or(libc::ENOEXEC));
        }
        let mut attrs: libc::posix_spawnattr_t = std::mem::zeroed();
        let rc = libc::posix_spawnattr_init(&mut attrs);
        if rc != 0 {
            return Err(rc);
        }
        let mut dfl: libc::sigset_t = std::mem::zeroed();
        libc::sigemptyset(&mut dfl);
        for &sig in &sigdef {
            libc::sigaddset(&mut dfl, sig);
        }
        libc::posix_spawnattr_setsigdefault(&mut attrs, &dfl);
        libc::posix_spawnattr_setsigmask(&mut attrs, &sigmask);
        libc::posix_spawnattr_setflags(
            &mut attrs,
            (libc::POSIX_SPAWN_SETSIGDEF | libc::POSIX_SPAWN_SETSIGMASK) as _,
        );
        let mut pid: libc::pid_t = 0;
        let rc = libc::posix_spawn(
            &mut pid,
            cpth.as_ptr(),
            std::ptr::null(),
            &attrs,
            argv_ptrs.as_ptr(),
            envp_ptrs.as_ptr(),
        );
        libc::posix_spawnattr_destroy(&mut attrs);
        if rc != 0 {
            return Err(rc);
        }
        Ok(pid)
    }
}

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) {
        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).
    /// 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 {
        paramtab()
            .read()
            .ok()
            .and_then(|t| t.get(name).map(|p| p.node.flags))
            .unwrap_or(0)
    }

    /// `readonly` / `typeset -r` / read-only-by-design (LINENO, PPID,
    /// $$, $?, $!, ...) — match user-side rejection in C's
    /// assignstrvalue at `Src/params.c:2699-2703` which gates on
    /// `pm->node.flags & PM_READONLY` where the IPDEF4 family declares
    /// `PM_READONLY_SPECIAL = PM_SPECIAL | PM_READONLY | PM_RO_BY_DESIGN`
    /// (all three bits set together), which `init_partab_params` now
    /// stamps in full. The PM_RO_BY_DESIGN arm below is therefore no
    /// longer the IPDEF4 rows' only read-only marker — it remains
    /// because `private` params (c:Src/Modules/param_private.c:174)
    /// carry PM_RO_BY_DESIGN WITHOUT PM_READONLY and need the
    /// scope-gated test. Bug #418-family / test_lineno_intrinsic_readonly.
    pub fn is_readonly_param(&self, name: &str) -> bool {
        // c:Src/params.c:2235 fetchvalue looks the name up through
        // realparamtab->getnode, i.e. getprivatenode (Src/Modules/
        // param_private.c:678): a private of an enclosing scope with nothing
        // beneath it is ABSENT, and createparam reports the write.
        let (flags, pm_level) = crate::ported::params::paramtab()
            .read()
            .ok()
            .and_then(|t| {
                t.get(name).and_then(|p| {
                    let vis = crate::ported::modules::param_private::getprivatenode(&**p as *const _);
                    (!vis.is_null()).then(|| unsafe { ((*vis).node.flags as u32, (*vis).level) })
                })
            })
            .unwrap_or((0, 0));
        // c:Src/params.c:2264-2265 — assignsparam reaches its c:3216 PM_READONLY
        // test only through fetchvalue, which reports a node that is PM_UNSET
        // without PM_DECLARED as ABSENT; createparam then decides (for an
        // outer-scope private, hidden by scopeprivate's PM_UNSET|PM_READONLY,
        // that is "can't modify read-only parameter"). So such a node is not
        // a read-only rejection here; assignsparam reports it.
        if (flags & crate::ported::zsh_h::PM_UNSET) != 0 && (flags & crate::ported::zsh_h::PM_DECLARED) == 0 {
            return false;
        }
        // c:Src/params.c assignsparam — a real PM_READONLY param always
        // rejects writes.
        if (flags & PM_READONLY) != 0 {
            return true;
        }
        if (flags & crate::ported::zsh_h::PM_RO_BY_DESIGN) != 0 {
            // c:Src/Modules/param_private.c pps_setfn (c:300-307) — a
            // PRIVATE param (PM_RO_BY_DESIGN + PM_REMOVABLE) is NOT blanket
            // read-only: a write is permitted iff it is in the SAME scope
            // (`locallevel == pm->level`, e.g. `() { private p=1; p=2 }`
            // → 2) or above the wrap level (`locallevel >
            // private_wraplevel`). A deeper nested-scope write is rejected
            // (setfn_error) — that is how a nested fn writing an OUTER
            // function's private still errors and aborts. zshrs never
            // wires the private GSU, so the level gate is enforced here.
            if (flags & crate::ported::zsh_h::PM_REMOVABLE) != 0 {
                let ll = crate::ported::params::locallevel.load(Ordering::Relaxed);
                let wrap = crate::ported::modules::param_private::private_wraplevel
                    .load(Ordering::Relaxed);
                return !(ll == pm_level || ll > wrap); // c:304 (negated: blocked)
            }
            // Non-removable PM_RO_BY_DESIGN = IPDEF4-family special
            // (LINENO/$?/$$…). These now also carry PM_READONLY and so
            // return true from the branch above; this arm stays as the
            // c:Src/zsh.h:1923 "readonly by design" fallback for any row
            // reached before `init_partab_params` has stamped the flag.
            return true;
        }
        false
    }

    /// 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(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, Ordering::Relaxed);
    }

    /// Set an indexed array parameter via canonical paramtab
    /// (`assignaparam`, `Src/params.c:3357`). The single store.
    ///
    /// Callers mean "make NAME this array" — `typeset -a h=(…)` over an
    /// existing assoc among them, whose type conversion C does in
    /// typeset_single before it assigns. `setaparam` now keeps an existing
    /// assoc hashed (C's c:3341-3342), so go one level down to the
    /// type-resetting store with the same `ASSPM_WARN` flag setaparam used.
    pub fn set_array(&mut self, name: String, value: Vec<String>) {
        assignaparam(&name, value, crate::ported::zsh_h::ASSPM_WARN); // c:params.c:3766
    }

    /// 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<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());
        }
        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> {
        getsparam(name)
    }

    /// Read an array parameter via canonical `getaparam`
    /// (`Src/params.c:3101`).
    pub fn array(&self, name: &str) -> Option<Vec<String>> {
        getaparam(name)
    }

    /// 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<String, String>> {
        // c:Src/params.c:570-575 — nameref deref before the read.
        let resolved = match crate::ported::params::resolve_nameref_name(name, None) {
            // c:2264-2267 + c:2297 — a reference to an ELEMENT leaves its
            // `[sub]` unparsed for a bracks-0 getvalue, so it is no hash.
            crate::ported::params::nameref_resolution::Target { subscript: Some(_), .. } => {
                return Default::default()
            }
            crate::ported::params::nameref_resolution::Target { name: t_, .. } => t_,
            _ => name.to_string(),
        };
        // The live param's TYPE is authoritative — paramtab_hashed_storage is
        // keyed by NAME ONLY (no scope), so a local ARRAY that shadows a special
        // assoc (`local -a options` / `local -a commands` over the hidden
        // `options`/`commands` specials) leaves a stale (emptied) hashed_storage
        // entry behind. Without this guard `exec.assoc("options")` returned
        // Some(empty), so a subsequent bare `options=(-a -b -c)` routed through
        // sethparam → "bad set of key/value pairs for associative array"
        // (odd count), breaking `_sqlite`'s `local -a options; options=(…)`
        // (separate statements — the one-statement `local -a commands=(…)` form
        // that openssl uses is typed correctly by bin_typeset). Consult the
        // current param: if it exists and is NOT PM_HASHED, it's an array/scalar
        // shadow and the stale assoc storage must not be seen.
        if let Some(flags) = crate::ported::params::paramtab()
            .read()
            .ok()
            .and_then(|t| t.get(resolved.as_str()).map(|p| p.node.flags as u32))
        {
            if (flags & PM_HASHED) == 0 {
                return None;
            }
        }
        paramtab_hashed_storage()
            .lock()
            .ok()
            .and_then(|m| m.get(resolved.as_str()).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 {
        getsparam(name).is_some()
    }

    /// Test whether an array parameter exists in paramtab. Mirrors
    /// `getaparam(name).is_some()` (PM_ARRAY + populated `u_arr`, with
    /// digit-first-name rejection and nameref deref) WITHOUT cloning the
    /// backing vector — `getaparam` returns an owned `Vec<String>`, so a
    /// bare existence probe on a large array copied every element. Hot in
    /// the subscript-store dispatch (`a[i]=v` in a loop), so keep it a
    /// flag read.
    pub fn has_array(&self, name: &str) -> bool {
        if name.starts_with(|c: char| c.is_ascii_digit()) {
            return false;
        }
        let resolved = match crate::ported::params::resolve_nameref_name(name, None) {
            crate::ported::params::nameref_resolution::Target { name: t_, .. } => t_,
            _ => name.to_string(),
        };
        crate::ported::params::paramtab()
            .read()
            .ok()
            .and_then(|t| {
                t.get(resolved.as_str()).map(|p| {
                    (p.node.flags as u32 & crate::ported::zsh_h::PM_ARRAY) != 0 && p.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 {
        // c:Src/params.c:570-575 — nameref deref before the read.
        let resolved = match crate::ported::params::resolve_nameref_name(name, None) {
            // c:2264-2267 + c:2297 — a reference to an ELEMENT leaves its
            // `[sub]` unparsed for a bracks-0 getvalue, so it is no hash.
            crate::ported::params::nameref_resolution::Target { subscript: Some(_), .. } => {
                return Default::default()
            }
            crate::ported::params::nameref_resolution::Target { name: t_, .. } => t_,
            _ => name.to_string(),
        };
        // Live-param type is authoritative (see `assoc` above): a non-PM_HASHED
        // shadow (e.g. `local -a options`) hides the stale name-keyed
        // hashed_storage entry.
        if let Some(flags) = crate::ported::params::paramtab()
            .read()
            .ok()
            .and_then(|t| t.get(resolved.as_str()).map(|p| p.node.flags as u32))
        {
            if (flags & PM_HASHED) == 0 {
                return false;
            }
        }
        paramtab_hashed_storage()
            .lock()
            .ok()
            .map(|m| m.contains_key(resolved.as_str()))
            .unwrap_or(false)
    }

    /// Unset an associative array parameter via canonical
    /// `unsetparam` (Src/params.c:3819) — PM_READONLY rejection,
    /// stdunsetfn dispatch, env clear. Also clears the zshrs-side
    /// `paramtab_hashed_storage` parallel IndexMap shadow.
    pub fn unset_assoc(&mut self, name: &str) {
        unsetparam(name);
        let _ = paramtab_hashed_storage()
            .lock()
            .ok()
            .as_deref_mut()
            .map(|m| m.remove(name));
    }

    /// 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 with ALIAS_SUFFIX node flag — mirrors C
    /// Src/builtin.c:4480-4481 (`flags1 |= ALIAS_SUFFIX; ht =
    /// sufaliastab;`) → c:4527 (`createaliasnode(value, flags1)`).
    /// Without ALIAS_SUFFIX in node.flags, `${saliases[k]}` /
    /// `${(k)saliases}` introspection (parameter.c:1953/2018) fails
    /// because both paths strict-equality-match flags == ALIAS_SUFFIX.
    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,
                crate::ported::zsh_h::ALIAS_SUFFIX as u32,
            ));
        }
    }

    /// 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.
    /// Unset an array parameter via canonical `unsetparam`
    /// (Src/params.c:3819). Routes through the C-faithful port
    /// that runs PM_NAMEREF skip + PM_READONLY rejection via
    /// unsetparam_pm + stdunsetfn dispatch + pm.old scope restore.
    /// Inline `tab.remove(name)` skipped all four.
    pub fn unset_array(&mut self, name: &str) {
        unsetparam(name);
    }

    /// Unset a scalar parameter via canonical `unsetparam`. Same
    /// C-faithful path as `unset_array`; the C `unsetparam` itself
    /// is type-agnostic and dispatches through PM_TYPE inside.
    pub fn unset_scalar(&mut self, name: &str) {
        unsetparam(name);
    }
    /// Lightweight executor for a POOL WORKER THREAD. Unlike [`new`] (a full
    /// session bootstrap that re-derives PWD, imports the environment, seeds
    /// `OPTS_LIVE`, and writes ~30 default params into the GLOBAL param table),
    /// this constructs ONLY the per-executor struct fields and touches NO
    /// global state. A worker shares the already-populated, `RwLock`-synchronized
    /// globals (params / functions / options); re-seeding them here would clobber
    /// the live main session's values (IFS, OPTIND, `$_`, user options, …).
    ///
    /// The worker pool is shared (Arc) — a worker never spins up its own pool.
    /// Per-worker SQLite caches (compsys / plugin) and the history engine are
    /// left `None`: a worker runs short compute bodies, not interactive editing.
    ///
    /// Phase 1 of the in-process thread-execution model (replaces the
    /// subprocess-forking parallel builtins). The caller runs the body under
    /// `ExecutorContext::enter(&mut wex)` so the VM's thread_local executor
    /// resolves on the worker thread; param writes flow to the shared globals.
    pub fn new_worker(pool: std::sync::Arc<crate::worker::WorkerPool>) -> Self {
        // fpath from the inherited env, same as new() — pure read, no global write.
        let raw_fpath: Vec<PathBuf> = env::var("FPATH")
            .unwrap_or_default()
            .split(':')
            .filter(|s| !s.is_empty())
            .map(PathBuf::from)
            .collect();
        // c:Src/init.c:1132-1143 seeds `<prefix>/share/zsh/<ver>/functions` at
        // a FIXED position, and every `#compdef` claim is resolved against
        // `$fpath` ORDER. The bundled tree is that tree's replacement — a
        // byte-identical superset of it — so it belongs AT ITS INDEX, not at
        // either end.
        let host_at = raw_fpath.iter().position(|d| is_host_zsh_function_tree(d));
        let mut fpath: Vec<PathBuf> = raw_fpath
            .into_iter()
            .filter(|d| !is_host_zsh_function_tree(d))
            .collect();
        if fpath.is_empty() {
            fpath = default_fpath(); // c:Src/init.c:1143
        }
        // Same directory as the main constructor, and LAST for the same
        // reason, but never written from a pool worker -- materialisation
        // is the session's job.
        if let Some(d) = crate::bundled_functions::functions_dir() {
            if d.is_dir() && !fpath.contains(&d) {
                // Insert AT the host tree's inherited index, not at either
                // end. `host_at` is that index in the raw FPATH; the filter
                // above removed only host-tree entries, all of which are at or
                // after it, so the index still addresses the same slot.
                //
                // Both ends are wrong, and each was tried. LAST (the previous
                // behaviour) let `zsh-more-completions`' appended dirs
                // out-rank the distribution for 343 files / 729 commands —
                // the opposite of real zsh, where the tree sits at index 24
                // and those plugins at 40-49, and the opposite of what
                // `zsh-more-completions.plugin.zsh` itself asks for: it
                // PREPENDS `override_src` and APPENDS `src`/`more_src*`/
                // `man_src`. FIRST shadowed everything the user curated,
                // `override_src` included (that is the `ls -<TAB>` regression
                // recorded in this comment's earlier revision). The host
                // tree's own index is after `override_src` and before the
                // appended plugin dirs, which is exactly where zsh has it.
                //
                // Measured on a 60-cell corpus of contested commands:
                // 1 PASS -> 57 PASS, zero regressions.
                match host_at {
                    Some(i) if i <= fpath.len() => fpath.insert(i, d),
                    _ => fpath.push(d),
                }
            }
        }
        Self {
            scriptname: Some("zsh".to_string()),
            scriptfilename: Some("zsh".to_string()),
            subshell_snapshots: Vec::new(),
            inline_env_stack: Vec::new(),
            current_command_glob_failed: std::cell::Cell::new(false),
            jobs: JobTable::new(),
            fpath,
            // Worker: no interactive history engine, ever — a pre-filled
            // cell so `history()` cannot open one from a pool thread.
            history: std::cell::OnceCell::from(None),
            completions: HashMap::new(),
            process_sub_counter: 0,
            zstyles: Vec::new(),
            local_scope_depth: 0,
            pending_underscore: None,
            in_dq_context: 0,
            in_scalar_assign: 0,
            profiling_enabled: false,
            compsys_cache: std::cell::OnceCell::from(None), // worker: no per-thread SQLite mirror
            compinit_pending: None,
            plugin_cache: None, // worker: no per-thread plugin cache
            deferred_compdefs: Vec::new(),
            returning: None,
            zsh_compat: false,
            bash_compat: false,
            posix_mode: false,
            worker_pool: pool, // SHARED — never spawn a nested pool
            intercepts: Vec::new(),
            async_jobs: HashMap::new(),
            next_async_id: 1,
            redirect_scope_stack: Vec::new(),
            multios_scope_stack: Vec::new(),
            exec_redirs_permanent: false,
            pipe_output_pending: false,
            pipe_output_scope: None,
            redirect_failed: false,
            functions_compiled: crate::cow_map::CowHashMap::new(),
            function_source: crate::cow_map::CowHashMap::new(),
            function_line_base: HashMap::new(),
            function_def_file: HashMap::new(),
            prompt_funcstack: Vec::new(),
            tied_array_to_scalar: HashMap::new(),
            ztest_pass_count: std::sync::atomic::AtomicUsize::new(0),
            ztest_fail_count: std::sync::atomic::AtomicUsize::new(0),
            ztest_skip_count: std::sync::atomic::AtomicUsize::new(0),
            ztest_pass_total: std::sync::atomic::AtomicUsize::new(0),
            ztest_fail_total: std::sync::atomic::AtomicUsize::new(0),
            ztest_skip_total: std::sync::atomic::AtomicUsize::new(0),
            ztest_run_failed: std::sync::atomic::AtomicBool::new(false),
            ztest_suppress_stdout: false,
        }
    }

    /// `new` — see implementation.
    pub fn new() -> Self {
        tracing::debug!("ShellExecutor::new() initializing");

        // zsh's man/info pages ride along with the function tree: same
        // reason (zshrs is not installed under a zsh prefix), same
        // one-stamp-read steady-state cost. This runs FIRST because it
        // edits MANPATH/INFOPATH in the OS environment, and the env is
        // read into paramtab further down -- publishing after that point
        // left an inherited $INFOPATH untouched in the shell while the
        // process environment carried the new value.
        crate::bundled_docs::install_and_publish();

        // c:Src/init.c:1236-1259 — setupvals' pwd/oldpwd init, ported
        // here because the bin entry skips setupvals (see the
        // init_bltinmods note below). The validated value lands in the
        // live OS env: the bin entry's `$PWD` carrier (the analog of
        // C's `pwd` global — see the subshell-snapshot comment at
        // fusevm_bridge.rs `cwd:` field). set_pwd_env() pours it into
        // paramtab after the env-import loop, same order as C
        // (params.c:955).
        //
        // c:1242-1245 — "Try a cheap test to see if we can initialize
        // `PWD' from `HOME'." EMULATE_ZSH reads the `home` global,
        // which setupvals derives from getpwuid(getuid())->pw_dir
        // (c:1222-1225), falling back to "/" (c:1230-1232).
        let home = unsafe {
            let pw = libc::getpwuid(libc::getuid());
            if pw.is_null() {
                None
            } else {
                Some(
                    std::ffi::CStr::from_ptr((*pw).pw_dir)
                        .to_string_lossy()
                        .into_owned(),
                )
            }
        }
        .unwrap_or_else(|| "/".to_string()); // c:1230-1232 EMULATE_ZSH home = "/"
                                             // ispwd (src/zsh/Src/utils.c:809-829): a candidate is honored
                                             // only when it (a) is absolute, (b) stat's to the same
                                             // dev+inode as ".", and (c) has no `.`/`..` components.
                                             // Without this chain, a child that inherits $PWD from a parent
                                             // run in a different directory (cargo test setting
                                             // current_dir(tempdir) while leaking PWD=/project/root) treats
                                             // the stale PWD as the logical-path base, so `cd sub` resolves
                                             // against the wrong directory.
        let pwd_val = if ispwd(&home) {
            home // c:1245-1246 — pwd = ztrdup(ptr) [HOME]
        } else if let Some(p) = env::var("PWD")
            .ok()
            .filter(|p| p.len() < libc::PATH_MAX as usize && ispwd(p))
        {
            p // c:1247-1249 — pwd = ztrdup(getenv("PWD"))
        } else {
            crate::ported::compat::zgetcwd() // c:1250-1252 — pwd = zgetcwd()
        };
        // c:1255-1259 — oldpwd = getenv("OLDPWD") ?: ztrdup(pwd).
        let oldpwd_val = env::var("OLDPWD").unwrap_or_else(|_| pwd_val.clone()); // c:1257
        // Both stay out of the environment until set_pwd_env below: in C they
        // are the `pwd`/`oldpwd` globals, and only set_pwd_env's addenv
        // (c:Src/builtin.c:821-826) exports them, after HOME, LOGNAME and
        // SHLVL (c:Src/params.c:960-977). Publishing them here put a
        // non-inherited PWD/OLDPWD ahead of those in every child's env.

        // Initialize fpath from FPATH env var, or from the compiled-in
        // defaults when it is absent (c:Src/init.c:1132-1143).
        let raw_fpath: Vec<PathBuf> = env::var("FPATH")
            .unwrap_or_default()
            .split(':')
            .filter(|s| !s.is_empty())
            .map(PathBuf::from)
            .collect();
        // c:Src/init.c:1132-1143 seeds `<prefix>/share/zsh/<ver>/functions` at
        // a FIXED position, and every `#compdef` claim is resolved against
        // `$fpath` ORDER. The bundled tree is that tree's replacement — a
        // byte-identical superset of it — so it belongs AT ITS INDEX, not at
        // either end.
        let host_at = raw_fpath.iter().position(|d| is_host_zsh_function_tree(d));
        let mut fpath: Vec<PathBuf> = raw_fpath
            .into_iter()
            .filter(|d| !is_host_zsh_function_tree(d))
            .collect();
        if fpath.is_empty() {
            fpath = default_fpath();
        }
        // zshrs ships zsh's function tree with the binary; its directory
        // goes LAST, so it supplies only what nothing else on fpath does.
        //
        // It was first at one point, mirroring where zsh's own
        // <prefix>/share/zsh/<ver>/functions sits. That is wrong here: zsh
        // puts its tree ahead of nothing the user curated, because the
        // user's own directories are prepended to it, whereas an inherited
        // FPATH arrives ALREADY assembled. Leading it shadowed every
        // curated completion of the same name -- 242 of
        // zsh-more-completions' files on this author's setup, `_ls` among
        // them, which is how `ls -<TAB>` started diverging from zsh.
        //
        // Being last costs nothing: the only tree that could out-rank the
        // bundle is a host zsh's own, and `is_host_zsh_function_tree`
        // already removes that from fpath entirely. Materialised here (not
        // only when FPATH is absent) so an inherited FPATH from a shell
        // that lacks these still resolves is-at-least/colors/add-zsh-hook.
        if let Some(d) = crate::bundled_functions::functions_dir() {
            let _ = crate::bundled_functions::ensure_installed();
            if d.is_dir() && !fpath.contains(&d) {
                // Insert AT the host tree's inherited index, not at either
                // end. `host_at` is that index in the raw FPATH; the filter
                // above removed only host-tree entries, all of which are at or
                // after it, so the index still addresses the same slot.
                //
                // Both ends are wrong, and each was tried. LAST (the previous
                // behaviour) let `zsh-more-completions`' appended dirs
                // out-rank the distribution for 343 files / 729 commands —
                // the opposite of real zsh, where the tree sits at index 24
                // and those plugins at 40-49, and the opposite of what
                // `zsh-more-completions.plugin.zsh` itself asks for: it
                // PREPENDS `override_src` and APPENDS `src`/`more_src*`/
                // `man_src`. FIRST shadowed everything the user curated,
                // `override_src` included (that is the `ls -<TAB>` regression
                // recorded in this comment's earlier revision). The host
                // tree's own index is after `override_src` and before the
                // appended plugin dirs, which is exactly where zsh has it.
                //
                // Measured on a 60-cell corpus of contested commands:
                // 1 PASS -> 57 PASS, zero regressions.
                match host_at {
                    Some(i) if i <= fpath.len() => fpath.insert(i, d),
                    _ => fpath.push(d),
                }
            }
        }

        let history = std::cell::OnceCell::new();

        // Seed canonical OPTS_LIVE with defaults BEFORE any setsparam
        // call. assignstrvalue early-returns when `unset(EXECOPT)`
        // (c:2701 guard); without the option table populated, EXECOPT
        // reads false and every paramtab write below is a silent no-op.
        if opt_state_len() == 0 {
            for (k, v) in Self::default_options() {
                opt_state_set(&k, v);
            }
        }

        // c:Src/params.c:838-847 — `for (ip = special_params; ip->node.nam;
        //     ip++) paramtab->addnode(paramtab, ztrdup(ip->node.nam), ip);`
        // The specials go into paramtab FIRST, ahead of every non-special
        // seed below, because creation ORDER is observable: a new key is
        // front-inserted into its bucket chain (c:Src/hashtable.c:214-215)
        // and `${(k)parameters}` prints that chain walk verbatim
        // (c:Src/hashtable.c:420-434). Seeding NULLCMD / FUNCNEST / PS1 /
        // … before this loop put them AHEAD of the specials they follow in
        // the C table (`#` at c:304 vs NULLCMD at c:378; UID at c:312 vs
        // FUNCNEST at c:366), which is exactly where zshrs's parameter
        // order diverged from zsh's. With the table seeded first, those
        // later `setsparam`/`setiparam` calls hit an existing node and
        // replace it IN PLACE (c:187-203 `replacing:`), keeping C's slot.
        // c:Src/params.c:384-394 — IPDEF8/IPDEF9 macros stamp
        // `PM_SCALAR|PM_SPECIAL` (IPDEF8 for `PATH`/`FPATH`/etc.) and
        // `PM_ARRAY|PM_SPECIAL|PM_DONTIMPORT` (IPDEF9 for `path`/
        // `fpath`/etc.) on every entry in the createparamtable table.
        // setsparam/setaparam above create plain PM_SCALAR/PM_ARRAY
        // entries; this loop applies the PM_SPECIAL + PM_TIED bits
        // (plus the IPDEF9 PM_DONTIMPORT bit on the array side) so
        // `${(t)PATH}` reads `scalar-tied-export-special` and
        // `${(t)path}` reads `array-tied-special`.
        //
        // Walks the `special_params` table (params.rs:464+) which is
        // the Rust port of the C IPDEF list. For each entry: OR the
        // declared pm_flags onto the existing paramtab entry. The
        // tied-pair entries (PM_TIED) also need PM_SPECIAL OR'd in
        // since the IPDEF8/IPDEF9 macros add PM_SPECIAL implicitly;
        // the table declares only the per-entry-distinct flags.
        let stamp_special_params = || {
            use crate::ported::params::{paramtab, special_params};
            use crate::ported::zsh_h::{PM_ARRAY, PM_DONTIMPORT, PM_SCALAR, PM_SPECIAL, PM_TIED};
            if let Ok(mut tab) = paramtab().write() {
                // Stamp PM_SPECIAL onto every entry the special_params
                // table declares. For tied scalars (PATH/FPATH/etc),
                // also walks `tied_name` to apply IPDEF9-flag bits
                // (PM_ARRAY|PM_SPECIAL|PM_DONTIMPORT|PM_TIED) onto the
                // partner array entry (path/fpath/etc) — those array
                // names aren't in the special_params table directly
                // but C zsh's createparamtable emits IPDEF9 rows for
                // them at Src/params.c:425-432.
                use crate::ported::zsh_h::{hashnode, param, PM_DONTIMPORT as PM_DI, PM_UNSET};
                // c:Src/params.c:838-847 — the first section is always
                // loaded; past it, sh/ksh emulation loads the untied scalar
                // `special_params_sh` rows INSTEAD of the zsh-only tail
                // (array-tied pairs, lowercase aliases, pipestatus):
                //     if (EMULATION(EMULATE_SH|EMULATE_KSH))
                //         for (ip = special_params_sh; ...) addnode(...);
                //     else
                //         while ((++ip)->node.nam) addnode(...);
                // `zsh --emulate sh -c 'typeset -p PATH'` therefore prints
                // `export PATH=…`, never `export -T PATH path=( … )`.
                let head = &special_params[..crate::ported::params::SPECIAL_PARAMS_ZSH_START];
                let tail: &[crate::ported::params::special_paramdef] = if crate::ported::zsh_h::EMULATION(
                    crate::ported::zsh_h::EMULATE_SH | crate::ported::zsh_h::EMULATE_KSH,
                ) {
                    crate::ported::params::special_params_sh // c:841-843
                } else {
                    &special_params[crate::ported::params::SPECIAL_PARAMS_ZSH_START..] // c:845-847
                };
                for entry in head.iter().chain(tail.iter()) {
                    // c:384/394 IPDEF8/9 — `D|PM_SCALAR|PM_SPECIAL` or
                    // `D|PM_ARRAY|PM_SPECIAL|PM_DONTIMPORT`.
                    //
                    // Mask `entry.pm_flags` to the attribute bits that
                    // may be OR'd onto an existing Param.
                    //
                    // PM_READONLY IS included. C declares it on 16 rows
                    // via `PM_READONLY_SPECIAL` (c:Src/zsh.h:1925 —
                    // `PM_SPECIAL|PM_READONLY|PM_RO_BY_DESIGN`): the
                    // IPDEF1 pair `#`/`TTYIDLE` (c:304,314), IPDEF2 `-`
                    // (c:318), the IPDEF4 block `!`/`$`/`?`/`HISTCMD`/
                    // `LINENO`/`PPID`/`ZSH_SUBSHELL` (c:351-358) plus
                    // `status` (c:424), IPDEF9 `*`/`@` (c:392-393) and
                    // `zsh_eval_context` (c:438), and IPDEF8
                    // `ZSH_EVAL_CONTEXT` (c:408). `special_params`
                    // (params.rs:477+) declares exactly those 16 and no
                    // others, so the bit lands on precisely C's set.
                    //
                    // An earlier revision stripped PM_READONLY here to
                    // keep internal-runtime writes from tripping
                    // `assignstrvalue`'s guard. Nearly all of those
                    // writers already mutate the paramtab node in place
                    // — exactly as C writes the backing C global behind
                    // a no-op GSU (c:Src/params.c:351, IPDEF4 uses
                    // `varint_readonly_gsu` =
                    // `{intvargetfn, nullintsetfn, stdunsetfn}`). The
                    // in-place sites are `fusevm_bridge.rs:242,261,13045`
                    // (ZSH_SUBSHELL bump on `u_val`) and
                    // `fusevm_bridge.rs:12590,12594,12714,12718` +
                    // `exec.rs:7651,7655` (zsh_eval_context /
                    // ZSH_EVAL_CONTEXT push+pop). None call
                    // `setsparam`/`setiparam`.
                    //
                    // The ONE writer that did route through `setsparam`
                    // was `endparamscope`'s deferred scope-pop restore
                    // (`params.rs`, the `None =>` arm of the `deferred`
                    // loop): with no GSU wired it name-routes the
                    // restore and so re-entered the guard, emitting a
                    // spurious `read-only variable: NAME` while
                    // unwinding a scope that had shadowed one. C cannot
                    // reach the guard there because c:5915-5933 calls
                    // the setfn directly. That arm now drops the bit for
                    // the duration of the restore, matching C.
                    //
                    // With that handled, restoring the flag costs the
                    // runtime nothing while making `typeset X=v`,
                    // `readonly X=v` and `X+=v` reject the way
                    // c:Src/params.c:3216 does, and making
                    // `paramtypestr` (c:Src/Modules/parameter.c:75-76)
                    // emit the `-readonly` component that
                    // `${parameters[X]}` is read for.
                    //
                    // PM_UNSET is included: lookup_special_var arms for
                    // TRY_BLOCK_ERROR / TRY_BLOCK_INTERRUPT (and other
                    // PM_UNSET entries with sentinel defaults) check
                    // this bit to decide between "stored value" vs
                    // "uninitialized → return -1 sentinel". The flag
                    // gets cleared by assignstrvalue at c:3660 on any
                    // write, so it correctly tracks "ever assigned".
                    // Bug #143 in docs/BUGS.md.
                    let safe_pm_flags = entry.pm_flags
                        & (PM_TIED | PM_DI | PM_UNSET | crate::ported::zsh_h::PM_READONLY);
                    // c:Src/params.c — IPDEF macros set PM_TYPE bits
                    // (PM_INTEGER for IPDEF5/6, PM_ARRAY for IPDEF9,
                    // PM_HASHED for IPDEF-hash) along with PM_SPECIAL.
                    // zshrs's previous init only ORed PM_SPECIAL +
                    // tied/di/unset/readonly — never the type bit. If
                    // setsparam ran BEFORE init_partab_params (it does
                    // for OPTIND/SHLVL at vm_helper.rs:874/878), the
                    // param entry stayed PM_SCALAR and `typeset -p
                    // OPTIND` emitted `typeset OPTIND=1` instead of
                    // zsh's `typeset -i10 OPTIND=1`. OR the pm_type
                    // into the bits so the type attribute lands.
                    let mut bits = safe_pm_flags | PM_SPECIAL | entry.pm_type;
                    // c:Src/zsh.h:1925 — `PM_READONLY_SPECIAL` is the
                    // three-bit set `PM_SPECIAL|PM_READONLY|
                    // PM_RO_BY_DESIGN`. `special_params` stores only
                    // PM_READONLY per row (the other two are implied by
                    // the IPDEF macro), so complete the triple here:
                    // PM_SPECIAL is already OR'd into `bits` above, and
                    // this adds the PM_RO_BY_DESIGN companion that
                    // distinguishes a by-design readonly special from a
                    // user `readonly` (c:Src/zsh.h:1923).
                    if (entry.pm_flags & crate::ported::zsh_h::PM_READONLY) != 0 {
                        bits |= crate::ported::zsh_h::PM_RO_BY_DESIGN;
                    }
                    if entry.pm_type == PM_ARRAY {
                        bits |= PM_DI;
                    }
                    let _ = PM_SCALAR;
                    let _ = PM_DONTIMPORT;
                    if let Some(pm) = tab.get_mut(entry.name) {
                        let was_integer =
                            (pm.node.flags as u32 & crate::ported::zsh_h::PM_INTEGER) != 0;
                        pm.node.flags |= bits as i32;
                        // c:Src/params.c:344 IPDEF4 / c:353 IPDEF5 — the
                        // C struct literal initialises the `base` field
                        // to 10 for every PM_INTEGER special. zshrs's
                        // initial paramtab seeding doesn't carry that
                        // through (the special_paramdef table has no
                        // `base` field). Set the default here so
                        // `printparamnode`'s PMTF_USE_BASE arm at
                        // params.rs:9341 emits "10" between
                        // `integer` and the name (`integer 10 readonly
                        // !=0`). Bug #297 in docs/BUGS.md.
                        if entry.pm_type == crate::ported::zsh_h::PM_INTEGER && pm.base == 0 {
                            pm.base = 10;
                        }
                        // When OR-ing PM_INTEGER onto a param that
                        // was previously PM_SCALAR (i.e. setsparam ran
                        // BEFORE init_partab_params, storing the value
                        // in u_str), parse the u_str into u_val so the
                        // integer getter reads the correct value. C
                        // zsh's setsparam-equivalent path detects the
                        // pm's PM_TYPE first and routes through
                        // intsetfn, but zshrs's setsparam at the bin
                        // entry point predates init_partab_params, so
                        // it lands as PM_SCALAR storage that the
                        // type-flip needs to migrate.
                        if !was_integer
                            && entry.pm_type == crate::ported::zsh_h::PM_INTEGER
                            && pm.u_val == 0
                        {
                            if let Some(ref s) = pm.u_str {
                                pm.u_val = s.parse::<i64>().unwrap_or(0);
                                pm.u_str = None;
                            }
                        }
                        // c:Src/zsh.h IPDEF8/IPDEF9 — the third macro
                        // arg is the tied partner name; mapped into
                        // `pm->ename` so `typeset -p` can find the
                        // peer for the PM_TIED swap. Bug #410.
                        if let Some(peer) = entry.tied_name {
                            pm.ename = Some(peer.to_string());
                        }
                    } else {
                        // Param hasn't been created yet (e.g. PATH gets
                        // imported lazily via the env fallback in
                        // getsparam at params.rs:4104; array specials
                        // like `pipestatus` / `funcstack` / `dirstack`
                        // / `zsh_scheduled_events` aren't pre-populated).
                        // Seed an empty placeholder carrying the
                        // canonical flag set so subsequent setsparam /
                        // `(t)X` / `${+X}` observers see the IPDEF
                        // attribute bits AND `${+X}` returns 1.
                        let u_arr = if entry.pm_type == PM_ARRAY {
                            Some(Vec::new())
                        } else {
                            None
                        };
                        let pm: crate::ported::zsh_h::Param = Box::new(param {
                            node: hashnode {
                                next: None,
                                nam: entry.name.to_string(),
                                flags: (entry.pm_type as i32) | bits as i32,
                            },
                            u_data: 0,
                            u_tied: None,
                            u_arr,
                            u_str: None,
                            u_val: 0,
                            u_dval: 0.0,
                            u_hash: None,
                            gsu_s: None,
                            gsu_i: None,
                            gsu_f: None,
                            gsu_a: None,
                            gsu_h: None,
                            // c:Src/params.c:344 IPDEF4 / c:353 IPDEF5 —
                            // PM_INTEGER specials default base=10.
                            base: if entry.pm_type == crate::ported::zsh_h::PM_INTEGER {
                                10
                            } else {
                                0
                            },
                            width: 0,
                            env: None,
                            // c:Src/zsh.h IPDEF8/IPDEF9 — tied partner
                            // name. Bug #410.
                            ename: entry.tied_name.map(|s| s.to_string()),
                            old: None,
                            level: 0,
                        });
                        tab.insert(entry.name.to_string(), pm);
                    }
                    // Tied partner side. The previous loop body ORed
                    // PM_ARRAY|PM_SPECIAL|PM_DONTIMPORT|PM_TIED onto the
                    // partner indiscriminately, but for a SCALAR ↔
                    // ARRAY tied pair (PATH ↔ path, FIGNORE ↔ fignore),
                    // that incorrectly stamped PM_ARRAY onto the scalar
                    // partner (FIGNORE, PATH, FPATH, MAILPATH, MANPATH,
                    // PSVAR, CDPATH, MODULE_PATH). Result: `(t)PATH`
                    // returned `array-tied-export-special` instead of
                    // `scalar-tied-export-special`.
                    //
                    // Both partners are already listed in `special_params`
                    // (the scalar at the IPDEF8 block, the array at the
                    // IPDEF9 block past the sentinel), so each gets its
                    // own pass through this loop and ends up with the
                    // correct flags. No cross-stamping needed.
                    let _ = entry.tied_name;
                }
            }
        };
        // c:Src/init.c:1277 — `inittyptab();  /* initialize the ztypes table */`
        // runs inside setupvals BEFORE `createparamtable()` (c:Src/init.c:1286).
        // This executor is the fusevm runtime's createparamtable entry point,
        // and the seeding below reaches `isident()` (WORDCHARS, …), which is
        // typtab-driven — with a zeroed typtab every name fails IIDENT and the
        // seed aborts with "not an identifier: WORDCHARS".
        crate::ported::utils::inittyptab(); // c:1277
        crate::startup_trace::mark("inittyptab");
        stamp_special_params(); // c:838-847 — create in C's order
                                // Standard zsh scalar param defaults — direct port of
                                // `createparamtable` (Src/params.c:817-988) + the `setupvals`
                                // tail. Writes through canonical `setsparam` (Src/params.c:3350).
                                //
                                // c:params.c:972-973 — ZSH_VERSION / ZSH_PATCHLEVEL.
                                // `zsh_version::ZSH_VERSION` (emitted by build.rs from the
                                // vendored `Config/version.mk`) is the development snapshot
                                // tag `5.9.0.3-test`; shipped zsh binaries report the clean
                                // release form (`5.9`). Bug #73 in docs/BUGS.md — cross-shell
                                // scripts that gate on `[[ $ZSH_VERSION = 5.9 ]]` or split on
                                // `.` expecting MAJOR.MINOR break on the `-test` suffix.
                                //
                                // Use the cleaned `patchlevel::ZSH_VERSION` here ("5.9") and
                                // surface the full snapshot tag as `$ZSHRS_VERSION` for
                                // zshrs-specific identity checks.
                                // ZSH_VERSION / ZSH_PATCHLEVEL / ZSHRS_VERSION / ZSH_NAME /
                                // ZSH_ARGZERO are NOT seeded here: C creates them at the END of
                                // `createparamtable` (c:970-973, after the environ import) and
                                // ZSH_NAME at `Src/init.c:1364` (setupvals, later still). They
                                // are seeded at those C positions further down, because a name
                                // created before the import lands in a different chain slot —
                                // `ZSH_NAME` seeded here came out BEHIND every same-bucket
                                // environment variable in `${(k)parameters}` instead of ahead
                                // of them (c:Src/hashtable.c:214-215 front-insert).
        setsparam("WORDCHARS", "*?_-.[]~=/&;!#$%^(){}<>");
        // SHLVL is NOT seeded here. c:Src/params.c:948-951 increments it
        // AFTER the environ-import loop, so the +1 lives at the end of that
        // loop below — see the `c:948-951` block. Doing it here instead meant
        // parsing the raw env string with `parse::<i32>()`, which mis-read
        // every non-decimal form C accepts via zstrtol_underscore
        // (SHLVL=0x10 must give 17, 010 → 9, 1_0 → 11, 9abc → 10, abc → 1).
        // POSIX/zsh default IFS: space + tab + newline + NUL.
        setsparam("IFS", " \t\n\0");
        // POSIX getopts: OPTIND starts at 1.
        setsparam("OPTIND", "1");
        // Note: OPTERR is NOT pre-initialised. zsh leaves it unset
        // even after `getopts` calls (verified: `getopts ":a" opt -a`
        // does not set it). It's a user-writable variable that
        // starts unset. Bug #150 in docs/BUGS.md.
        // zsh wipes inherited `$_` (unlike bash).
        setsparam("_", "");
        // c:params.c:5064 — histchars derives from bangchar+hatchar+
        // hashchar (defaults `!`, `^`, `#`). At init the special
        // entry may not exist yet — fall back to the literal default.
        let histchars_val = paramtab()
            .read()
            .ok()
            .and_then(|t| {
                t.get("histchars")
                    .or_else(|| t.get("HISTCHARS"))
                    .map(|pm| histcharsgetfn(pm))
            })
            .unwrap_or_else(|| "!^#".to_string());
        setsparam("histchars", &histchars_val);

        // c:Src/params.c:870-871 — `setsparam("TIMEFMT", ...)` etc.
        // Seed TIMEFMT explicitly so `${(k)parameters}` lists it
        // (the createparamtable() ported in ported::params isn't
        // invoked from this bin entry — its setsparam calls don't
        // run, so TIMEFMT only existed via the lookup_special_var
        // fallback, which scanpmparameters can't see).
        setsparam("TIMEFMT", crate::ported::zsh_system_h::DEFAULT_TIMEFMT);
        // c:Src/params.c:892 — `setsparam("TMPPREFIX",
        // ztrdup_metafy(DEFAULT_TMPPREFIX));`, the line immediately
        // before the TIMEFMT seed above. `DEFAULT_TMPPREFIX` is
        // "/tmp/zsh" (c:configure.ac:3030 → config.h). Same reason as
        // TIMEFMT: createparamtable() is not reached from this bin
        // entry, so without this seed `$TMPPREFIX` existed only when
        // the environment happened to export it — every scrubbed-env
        // launch (cron, launchd/systemd unit, container entrypoint,
        // `env -i`) left it unset and every temp-file path derived
        // from it fell back per-call-site.
        //
        // C seeds unconditionally BEFORE the import loop (c:870 vs
        // c:893+) and the import then overwrites via assignsparam, so
        // an exported $TMPPREFIX still wins. zshrs's import only
        // rewrites an entry that is still PM_UNSET, so the env value is
        // resolved HERE instead — same end state, and the node is
        // created at C's position in the bucket chain. Skipping the
        // seed when the environment had TMPPREFIX (the previous shape)
        // deferred creation into the import loop, which put TMPPREFIX
        // behind every environment variable that hashes to its bucket.
        //
        // The lookup reads the process-entry environ snapshot, the same
        // source the import loop below walks (see the `environ` static
        // in ported::params for why the live environment is not it).
        let env_at_entry = |name: &str| -> Option<String> {
            crate::ported::params::environ
                .get()
                .and_then(|v| {
                    v.iter()
                        .find(|(k, _)| k == name)
                        .map(|(_, val)| val.clone())
                })
                .or_else(|| std::env::var(name).ok())
        };
        setsparam(
            "TMPPREFIX",
            env_at_entry("TMPPREFIX")
                .as_deref()
                .unwrap_or(crate::ported::config_h::DEFAULT_TMPPREFIX),
        ); // c:870
           // c:Src/init.c:1214-1215 — `nullcmd = ztrdup("cat");
           // readnullcmd = ztrdup(DEFAULT_READNULLCMD);`. Real paramtab
           // seeds (NOT read-time fallbacks) so `unset NULLCMD` truly
           // unsets — the bare-redirect "redirection with no command"
           // diagnostic depends on getsparam returning None afterwards.
           // c:config.h:48 DEFAULT_READNULLCMD "more" — the parity
           // floor agrees: scrubbed-env Homebrew zsh 5.9.1 -fc reports
           // READNULLCMD=more (probed; the previous macOS arm's "less"
           // guess came from the USER's env exporting READNULLCMD=less
           // — zpwr sets it). This block runs AFTER the env import, so
           // these are DEFAULT seeds only: an env-imported value must
           // win (C seeds before the import loop, c:854-885 vs c:893+).
        if getsparam("NULLCMD").map_or(true, |v| v.is_empty()) {
            setsparam("NULLCMD", "cat");
        }
        if getsparam("READNULLCMD").map_or(true, |v| v.is_empty()) {
            setsparam("READNULLCMD", crate::ported::config_h::DEFAULT_READNULLCMD);
        }
        // c:Src/params.c:873-876 — `gethostname(hostnam, 256);
        //                            setsparam("HOST", ztrdup_metafy(hostnam));`
        // Seeded HERE, before the import loop, exactly like C; it used
        // to run at the very end of this constructor, which put HOST
        // ahead of same-bucket specials (PROMPT) that C creates first.
        // The env value is resolved up front for the same reason as
        // TMPPREFIX above (C's import would overwrite it).
        let mut host_buf = [0u8; 256];
        let host_rc = unsafe { libc::gethostname(host_buf.as_mut_ptr() as *mut libc::c_char, 256) }; // c:874
        let hostname = if host_rc == 0 {
            std::ffi::CStr::from_bytes_until_nul(&host_buf)
                .ok()
                .and_then(|c| c.to_str().ok())
                .unwrap_or("")
                .to_string()
        } else {
            String::new()
        };
        setsparam("HOST", env_at_entry("HOST").as_deref().unwrap_or(&hostname)); // c:875
                                                                                 // c:Src/params.c:878-882 — `setsparam("LOGNAME", (str = getlogin())
                                                                                 //     && *str ? ztrdup_metafy(str) : ztrdup(cached_username));`
                                                                                 // Also pre-import in C (c:878 vs c:893+); creating it during the
                                                                                 // import instead put LOGNAME behind the environment variables
                                                                                 // sharing its bucket.
        let logname_default = {
            let from_getlogin = unsafe {
                let p = libc::getlogin(); // c:880
                if p.is_null() {
                    String::new()
                } else {
                    std::ffi::CStr::from_ptr(p).to_string_lossy().into_owned()
                }
            };
            if from_getlogin.is_empty() {
                crate::ported::utils::get_username() // c:882 cached_username
            } else {
                from_getlogin
            }
        };
        setsparam(
            "LOGNAME",
            env_at_entry("LOGNAME")
                .as_deref()
                .unwrap_or(&logname_default),
        ); // c:878
           // c:Src/init.c:1186-1193 — default prompt strings. zsh sets
           // PS4 to "+%N:%i> " for ZSH emulation ("+ " for KSH/SH).
           // Without seeding, PS4 reads empty and `set -x` output has
           // no prefix at all. Bug #92 in docs/BUGS.md.
           //
           // C zsh runs createparamtable's env-import loop (c:893-924)
           // BEFORE init.c:1186 fires, so an exported $PS4 in the parent
           // env wins over the default seed. zshrs's env import happens
           // further down in ShellExecutor::new() (at the createparamtable
           // call site), so getsparam() reads None here even when env has
           // a value, and the default would clobber the user's PS4.
           //
           // Additional wrinkle: C zsh's PROMPT / PROMPT2 / PROMPT3 /
           // PROMPT4 params are ALIASES for PS1..PS4 (Src/params.c:381,
           // 415-421 — both IPDEF7R entries bind to the same `prompt*`
           // global). So `export PROMPT4=...` in the parent env sets the
           // shared global, and `$PS4` reads the same string. The user's
           // interactive shell exports PROMPT4 (the form zsh's prompt
           // theme system uses), so when zshrs -x runs, PROMPT4 is in
           // env but PS4 is not. Without aliasing in the env-probe step,
           // zshrs seeds default PS4 and ignores the user's customised
           // prefix.
           //
           // Probe env::var directly for the name AND its alias; first
           // non-empty wins. Only fall through to the default seed when
           // every candidate is empty. Mirrors C zsh's behavior without
           // reshuffling the rest of new(). Bug: `zshrs -x` ignored the
           // user's custom PS4/PROMPT4 unless re-forwarded with
           // `PS4=$PROMPT4 zshrs -x`.
        let seed_prompt = |name: &str, alias: Option<&str>, default: &str| {
            let cur = crate::ported::params::getsparam(name);
            let have_param = cur.as_deref().map_or(false, |s| !s.is_empty());
            if have_param {
                return;
            }
            // Probe primary name first, then the C-side alias.
            // An EMPTY exported value counts: C's env import (c:893-924)
            // assigns whatever `environ` holds, empty string included, and
            // it runs before the c:1196 defaults, so `export PS1=` yields
            // an empty prompt rather than `%m%# `. Testing only for a
            // NON-empty value skipped that case and re-seeded the default.
            for candidate in std::iter::once(name).chain(alias.into_iter()) {
                if let Ok(env_val) = std::env::var(candidate) {
                    setsparam(name, &env_val);
                    return;
                }
            }
            setsparam(name, default);
        };
        seed_prompt("PS4", Some("PROMPT4"), "+%N:%i> ");
        // c:Src/init.c:1181-1190 —
        //     if(unset(INTERACTIVE)) {
        //         prompt = ztrdup("");
        //         prompt2 = ztrdup("");
        //     } else ... {
        //         prompt  = ztrdup("%m%# ");
        //         prompt2 = ztrdup("%_> ");
        //     }
        // Non-interactive shells get EMPTY primary/secondary prompts
        // — `zsh -fc 'typeset'` lists PS1='' — while interactive ones
        // get the %m%# defaults. PS3/PS4/SPROMPT are seeded
        // unconditionally in C (c:1191-1194). PS1 may be reset by the
        // prompt-theme layer; only seed when the slot is empty so any
        // prior theme write wins.
        let interactive = crate::ported::zsh_h::isset(crate::ported::zsh_h::INTERACTIVE);
        seed_prompt(
            "PS1",
            Some("PROMPT"),
            if interactive { "%m%# " } else { "" },
        );
        seed_prompt(
            "PS2",
            Some("PROMPT2"),
            if interactive { "%_> " } else { "" },
        );
        // c:Src/init.c:1191 — `prompt3 = ztrdup("?# ");`
        seed_prompt("PS3", Some("PROMPT3"), "?# ");
        // c:Src/init.c:1194 — `sprompt = ztrdup("zsh: correct '%R'
        // to '%r' [nyae]? ");` — spelling-correction prompt.
        seed_prompt("SPROMPT", None, "zsh: correct '%R' to '%r' [nyae]? ");
        // c:Src/params.c:417-422 — `PROMPT*` aliases for `PS*`.
        // C zsh's IPDEF7("PROMPT", &prompt), IPDEF7("PROMPT2",
        // &prompt2), IPDEF7("PROMPT3", &prompt3), IPDEF7("PROMPT4",
        // &prompt4) all point to the same C globals as the matching
        // IPDEF7("PS{1..4}", ...) entries — they're aliases in C,
        // sharing storage. zshrs's paramtab keeps them as separate
        // entries; mirror the alias by mirroring the value here.
        // Bug #274 in docs/BUGS.md (PROMPT3 was the visible report;
        // PROMPT/PROMPT2/PROMPT4 had the same gap silently).
        for (alias, source) in &[
            ("PROMPT", "PS1"),
            ("PROMPT2", "PS2"),
            ("PROMPT3", "PS3"),
            ("PROMPT4", "PS4"),
        ] {
            if crate::ported::params::getsparam(alias).map_or(true, |s| s.is_empty()) {
                if let Some(v) = crate::ported::params::getsparam(source) {
                    setsparam(alias, &v);
                }
            }
        }
        // c:params.c:858-860 — standard non-special param defaults.
        // C uses `setiparam(...)` (PM_INTEGER) for these so
        // `(t)MAILCHECK` etc. report `integer`. zshrs previously
        // routed through `setsparam` (PM_SCALAR) — the value worked
        // but the type bit was wrong, breaking
        // `case "${(t)LISTMAX}" in *integer*)` and any path that
        // gates on arithmetic-typed semantics. Bug #268 in
        // docs/BUGS.md.
        crate::ported::params::setiparam("MAILCHECK", 60); // c:858
        crate::ported::params::setiparam("KEYTIMEOUT", 40); // c:859
        crate::ported::params::setiparam("LISTMAX", 100); // c:860
                                                          // c:config.h:1004 — MAX_FUNCTION_DEPTH=500. Advisory cap;
                                                          // dispatch_function_call enforces against this.
        crate::ported::params::setiparam("FUNCNEST", 500);

        // 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();
        crate::startup_trace::mark("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();
        // c:Src/init.c:1125-1130 — `path` starts as the compiled-in default;
        // an inherited $PATH replaces it in the environ import. With no PATH
        // in the environment the default stands and is not exported.
        let path_dirs: Vec<String> = match env::var("PATH") {
            Ok(p) => p.split(':').map(|s| s.to_string()).collect(),
            Err(_) => ["/bin", "/usr/bin", "/usr/ucb", "/usr/local/bin"] // c:1126-1129
                .iter()
                .map(|s| s.to_string())
                .collect(),
        };
        arrays.insert("path".to_string(), path_dirs);
        let mut exec = Self {
            // c:Src/init.c:479 — `-c` mode: scriptname = scriptfilename
            // = ztrdup("zsh"). Both start at the literal "zsh".
            // dispatch_function_call overrides scriptname per c:5903;
            // scriptfilename stays at the outer file.
            scriptname: Some("zsh".to_string()),
            scriptfilename: Some("zsh".to_string()),
            subshell_snapshots: Vec::new(),
            inline_env_stack: Vec::new(),
            current_command_glob_failed: std::cell::Cell::new(false),
            jobs: JobTable::new(),
            fpath,
            history,
            completions: HashMap::new(),
            process_sub_counter: 0,
            zstyles: Vec::new(),
            local_scope_depth: 0,
            pending_underscore: None,
            in_dq_context: 0,
            in_scalar_assign: 0,
            profiling_enabled: false,
            compsys_cache: std::cell::OnceCell::new(),
            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 _ = 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) => {
                        // A corrupt cache file is not a permanent condition:
                        // `plugins.db` is derived data, rebuilt by the next
                        // plugin scan. SQLite answers a clobbered header with
                        // SQLITE_NOTADB ("file is not a database"), and the
                        // old behaviour logged that and moved on — so the
                        // cache stayed dead for every future shell too, with
                        // nothing but a log line to say why plugin lookups
                        // were slow. Discard the file and open once more;
                        // this is the same "drop it and rebuild silently"
                        // rule the shard cache already applies to a version
                        // mismatch. A second failure keeps the old
                        // behaviour, so a permissions problem still degrades
                        // instead of looping.
                        let corrupt = matches!(
                            e.sqlite_error_code(),
                            Some(rusqlite::ErrorCode::NotADatabase)
                                | Some(rusqlite::ErrorCode::DatabaseCorrupt)
                        );
                        if corrupt {
                            tracing::warn!(
                                error = %e,
                                path = %pc_path.display(),
                                "plugin_cache: corrupt — discarding and rebuilding"
                            );
                            let _ = fs::remove_file(&pc_path);
                            // The -wal/-shm side files belong to the database
                            // that just went away; leaving them makes the
                            // fresh open inherit a journal for a file that no
                            // longer exists.
                            for side in ["-wal", "-shm"] {
                                let mut p = pc_path.clone().into_os_string();
                                p.push(side);
                                let _ = fs::remove_file(PathBuf::from(p));
                            }
                            match crate::plugin_cache::PluginCache::open(&pc_path) {
                                Ok(pc) => {
                                    tracing::info!(
                                        path = %pc_path.display(),
                                        "plugin_cache: rebuilt after corruption"
                                    );
                                    Some(pc)
                                }
                                Err(e2) => {
                                    tracing::warn!(error = %e2, "plugin_cache: reopen after discard failed");
                                    None
                                }
                            }
                        } else {
                            tracing::warn!(error = %e, "plugin_cache: failed to open");
                            None
                        }
                    }
                }
            },
            deferred_compdefs: Vec::new(),
            returning: None,
            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,
            redirect_scope_stack: Vec::new(),
            multios_scope_stack: Vec::new(),
            exec_redirs_permanent: false,
            pipe_output_pending: false,
            pipe_output_scope: None,
            redirect_failed: false,
            functions_compiled: crate::cow_map::CowHashMap::new(),
            function_source: crate::cow_map::CowHashMap::new(),
            function_line_base: HashMap::new(),
            function_def_file: HashMap::new(),
            prompt_funcstack: Vec::new(),
            tied_array_to_scalar: HashMap::new(),
            ztest_pass_count: std::sync::atomic::AtomicUsize::new(0),
            ztest_fail_count: std::sync::atomic::AtomicUsize::new(0),
            ztest_skip_count: std::sync::atomic::AtomicUsize::new(0),
            ztest_pass_total: std::sync::atomic::AtomicUsize::new(0),
            ztest_fail_total: std::sync::atomic::AtomicUsize::new(0),
            ztest_skip_total: std::sync::atomic::AtomicUsize::new(0),
            ztest_run_failed: std::sync::atomic::AtomicBool::new(false),
            ztest_suppress_stdout: false,
        };
        // Publish the session worker pool so preprompt-time async hooks
        // (async_precmd) can reach it without an entered executor context.
        crate::async_precmd::set_session_pool(std::sync::Arc::clone(&exec.worker_pool));
        crate::startup_trace::mark("worker pool ready");
        // 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).
        crate::startup_trace::mark("exec struct built");
        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.
        // c:Src/params.c:395-422 IPDEF8 — full PM_TIED colonarr list:
        // CDPATH, FIGNORE, FPATH, MAILPATH, PATH, PSVAR, MODULE_PATH,
        // MANPATH (ZSH_EVAL_CONTEXT is readonly-special, excluded).
        for (scalar, arr) in [
            ("PATH", "path"),
            ("FPATH", "fpath"),
            ("MANPATH", "manpath"),
            ("CDPATH", "cdpath"),
            ("MODULE_PATH", "module_path"),
            ("PSVAR", "psvar"),
            ("FIGNORE", "fignore"),
            ("MAILPATH", "mailpath"),
        ] {
            exec.tied_array_to_scalar
                .insert(arr.to_string(), (scalar.to_string(), ":".to_string()));
        }

        // Pour `path` (from env PATH split) into paramtab. The IPDEF9
        // flag set was stamped by the c:838-847 pass above and survives
        // the assignment (`assignaparam` keeps PM_DONTIMPORT on a
        // PM_SPECIAL node — c:3374 + params.rs), so no re-stamp is
        // needed here.
        for (k, v) in &arrays {
            setaparam(k, v.clone()); // c:params.c:3595
        }

        // c:Src/params.c:893-924 — the environment import runs AFTER the
        // specials table (moved above, c:838-847) and after the c:854-885
        // non-special seeds, exactly as `createparamtable` sequences them.
        //
        // Carries c:951's `addenv(pm, buf)` argument out of the paramtab
        // write-lock below: `addenv` takes that same lock itself, so the call
        // cannot be made while the guard is alive.
        let mut shlvl_env: Option<String> = None;
        // !!! LOCK DISCIPLINE — NO GSU CALLBACK MAY RUN UNDER THE PARAMTAB GUARD !!!
        //
        // C's import loop calls `assignsparam(..., ASSPM_ENV_IMPORT)` (c:907-908)
        // and holds no lock at all, so a setfn reached from there is free to read
        // any parameter — and several do. `intsetfn` name-dispatches `$COLUMNS` /
        // `$LINES` to `zlevarsetfn` (c:4226), which re-enters `adjustwinsize`,
        // which falls back to `getsparam("COLUMNS")` when its ioctl comes back
        // empty. `paramtab()` is a non-reentrant `std::sync::RwLock`, so running
        // that under the write guard below parked the shell on itself:
        //
        //     COLUMNS=200 zshrs -f -c 'print $COLUMNS'
        //
        // never printed anything and never exited, with `sample` showing
        // 2665/2665 samples in `semaphore_wait_trap` down
        // `ShellExecutor::new → intsetfn → zlevarsetfn → adjustwinsize →
        // adjustlines → getsparam → RwLock::lock_contended`. That is the same
        // chain 5929e82b81 diagnosed on the startup path; that fix removed a
        // Rust-only return value from `adjustwinsize` so the ONE caller it knew
        // about stopped re-entering, and left the pattern in place for this one.
        //
        // So the dispatches are queued here and replayed after the guard is
        // released, the way `shlvl_env` and `tied_env_arrays` already are. One
        // queue, not one per signature, because C's order is per-variable and
        // must survive: `termsetfn` populates the termcap geometry that a later
        // `$LINES` import reads back through `adjustwinsize`.
        enum DeferredEnvSetfn {
            /// c:2774 — `v->pm->gsu.i->setfn(v->pm, ival)`.
            Int(String, i64),
            /// c:907-908 — the cached-storage scalar specials' setfn.
            Scalar(String, String),
        }
        let mut deferred_env_setfns: Vec<DeferredEnvSetfn> = Vec::new();
        {
            use crate::ported::params::paramtab;
            if let Ok(mut tab) = paramtab().write() {
                use crate::ported::zsh_h::{param, PM_UNSET};
                // c:Src/params.c:893-924 environment-import loop —
                // every env var gets either a fresh exported paramtab
                // entry OR (when the entry pre-exists from
                // special_params) PM_EXPORTED OR'd onto its flags.
                // Without this, `declare -p PATH` printed `typeset -T
                // PATH=''` and `declare -p USER` printed nothing at
                // all because USER was never in paramtab.
                use crate::ported::zsh_h::hashnode as _hn;
                use crate::ported::zsh_h::{PM_EXPORTED, PM_SCALAR};
                // c:Src/params.c:4329-4342 colonarrsetfn — assigning a
                // tied IPDEF8 scalar (MANPATH, CDPATH, MODULE_PATH, …)
                // colonsplit()s the value into the partner array,
                // preserving empty components. The env import below
                // bypasses the GSU setfn, so collect the tied pairs
                // here and pour them through setaparam after the
                // paramtab lock drops. PATH→path / FPATH→fpath are
                // seeded earlier (vm_helper ~1160-1199) and skipped.
                let mut tied_env_arrays: Vec<(String, Vec<String>)> = Vec::new();
                // c:Src/params.c:893 — walk the process-entry environ
                // snapshot, not the live env (frameworks can mutate it
                // before init — see params.rs `environ` static).
                let environ_vars: Vec<(String, String)> = crate::ported::params::environ
                    .get()
                    .cloned()
                    .unwrap_or_else(|| std::env::vars().collect());
                for (env_name, env_value) in environ_vars {
                    if env_name.is_empty() || env_name.contains('[') {
                        continue;
                    }
                    if env_name.as_bytes()[0].is_ascii_digit() {
                        continue;
                    }
                    if !crate::ported::params::isident(&env_name) {
                        continue;
                    }
                    if let Some(pm) = tab.get_mut(&env_name) {
                        // c:Src/params.c:902-906 — the import loop runs
                        // `dontimport(pm->node.flags)` BEFORE doing
                        // anything to the entry; PM_DONTIMPORT names
                        // (`_`, IFS, GID/EGID, KEYBOARD_HACK — the
                        // IPDEF7/IPDEF2 rows, c:796-800) are skipped
                        // ENTIRELY: no PM_EXPORTED stamp, no value
                        // seed. zshrs previously OR'd PM_EXPORTED
                        // first, so an inherited env `_` made the
                        // special `_` exported and it leaked into
                        // `typeset +x -r` / `export -p` listings where
                        // zsh shows nothing.
                        if (pm.node.flags as u32 & crate::ported::zsh_h::PM_DONTIMPORT) != 0 {
                            continue; // c:905 `continue;`
                        }
                        pm.node.flags |= PM_EXPORTED as i32;
                        // c:Src/params.c:2769-2776 — assignstrvalue's
                        // PM_INTEGER arm, which C's env import reaches via
                        // `assignsparam(..., ASSPM_ENV_IMPORT)` (c:907-908;
                        // assignsparam forwards its `flags` verbatim at
                        // c:params.c assignstrvalue(v, val, flags)):
                        //     if (flags & ASSPM_ENV_IMPORT) {
                        //         char *ptr;
                        //         ival = zstrtol_underscore(val, &ptr, 0, 1);
                        //     } else
                        //         ival = mathevali(val);
                        //     v->pm->gsu.i->setfn(v->pm, ival);
                        // An integer param keeps its value in `u.val`, NOT in
                        // the scalar slot, so the `pm.u_str = env_value` seed
                        // below stored the digits somewhere no integer reader
                        // ever looks and EVERY pre-existing PM_INTEGER param
                        // silently ignored the environment: COLUMNS/LINES
                        // (IPDEF5, c:355-356) read back 0, while HISTSIZE,
                        // SAVEHIST, LISTMAX, MAILCHECK, KEYTIMEOUT and
                        // FUNCNEST kept their built-in defaults — i.e.
                        // `HISTSIZE=5000 zshrs -c ...` was a no-op.
                        //
                        // Base 0 + underscore=1 is not incidental: it is what
                        // makes `COLUMNS=0x10` 16, `COLUMNS=0b101` 5,
                        // `COLUMNS=010` 8 (octal — c:utils.c:2452-2461 takes
                        // the leading `0` then falls to `base = 8`),
                        // `COLUMNS=1_0` 10, and a trailing-garbage value like
                        // `9abc` a silent 9. mathevali would instead ERROR on
                        // `9abc`, which is precisely why C splits the two
                        // paths — importing a hostile environment must not
                        // abort the shell (upstream 546203a770, "33276: safer
                        // import of numerical variables from environment").
                        if (pm.node.flags as u32 & crate::ported::zsh_h::PM_INTEGER) != 0 {
                            let (ival, _) =
                                crate::ported::utils::zstrtol_underscore(&env_value, 0, true); // c:2773
                                                                                               // c:3660 — any assignstrvalue write clears PM_UNSET.
                            pm.node.flags &= !(PM_UNSET as i32);
                            // c:2774 — `v->pm->gsu.i->setfn(v->pm, ival)`.
                            // intsetfn is this port's stand-in for the gsu_i
                            // vtable: it name-dispatches the specials whose
                            // setter has side effects (SECONDS, RANDOM,
                            // HISTSIZE, …) and writes u.val otherwise. Queued,
                            // not called: see the lock-discipline note above.
                            //
                            // The plain storage half of the setfn still lands
                            // HERE, synchronously, because C's write is
                            // synchronous and code further down this same guard
                            // reads it back: the c:948-951 SHLVL block computes
                            // `++shlvl` from the value this loop just imported,
                            // and the C comment on it ("the increment must
                            // observe the imported value") is load-bearing.
                            // Deferring the storage too made `SHLVL=5 zshrs -f
                            // -c 'print $SHLVL'` answer 1 instead of 6. The
                            // queued dispatch then re-applies it along with the
                            // side effects only it can produce.
                            pm.u_val = ival; // c:2774 (the `pm->u.val = x` half)
                            deferred_env_setfns
                                .push(DeferredEnvSetfn::Int(env_name.clone(), ival)); // c:2774
                            pm.env = Some(format!("{env_name}={env_value}"));
                            continue;
                        }
                        // c:Src/params.c:893-924 — C's env-import calls
                        // `assignsparam(..., ASSPM_ENV_IMPORT)` which
                        // routes through the param's GSU setfn. For
                        // SPECIAL scalars with cached storage (HOME,
                        // USERNAME, TERM, WORDCHARS, TERMINFO,
                        // TERMINFO_DIRS, KEYBOARD_HACK, histchars) the
                        // setfn writes to a separate `*_lock` global
                        // (e.g. home_lock). Just OR'ing PM_EXPORTED
                        // leaves those globals empty, so `$HOME` reads
                        // back "" even though HOME is in env. Mirror
                        // C by copying the env value into pm.u_str and
                        // (for cached specials) the matching global.
                        // Only seed cached state when the param was
                        // still marked PM_UNSET — i.e. nothing has set
                        // it yet. ShellExecutor::new's earlier init
                        // block (vm_helper line 837+) already ran
                        // setsparam for a few names (ZSH_ARGZERO,
                        // WORDCHARS, SHLVL with the +1 increment, IFS,
                        // OPTIND, …); those calls clear PM_UNSET so we
                        // must not overwrite them with the raw env
                        // value here. The PM_UNSET-still-set case is
                        // the "C zsh would have called
                        // assignsparam(...,ASSPM_ENV_IMPORT) and ours
                        // didn't yet" gap that bug #599 (HOME=` `) and
                        // %~ prompt expansion need.
                        let still_unset =
                            (pm.node.flags as u32 & crate::ported::zsh_h::PM_UNSET) != 0;
                        if still_unset {
                            pm.u_str = Some(env_value.clone());
                            pm.env = Some(format!("{}={}", env_name, env_value));
                            // c:Src/params.c:3660 — `assignstrvalue`
                            // clears PM_UNSET on any write. HOME / TERM
                            // / TERMINFO / TERMINFO_DIRS / WORDCHARS
                            // start life with PM_UNSET in
                            // `special_params` (params.rs SPECIAL_PARAMS
                            // table) so `lookup_special_var` skips the
                            // getfn for uninitialized specials; env
                            // import is the canonical "now it's set"
                            // event, so clear the bit.
                            pm.node.flags &= !(PM_UNSET as i32);
                            // Cached-state specials: route through
                            // the matching setfn so the global cache
                            // (home_lock / wordchars_lock / etc.)
                            // reflects the env value. Queued, not
                            // called: see the lock-discipline note
                            // above. `termsetfn` in particular reaches
                            // the terminal setup, which is exactly the
                            // kind of callee that reads parameters.
                            if matches!(
                                env_name.as_str(),
                                "HOME"
                                    | "USERNAME"
                                    | "TERM"
                                    | "WORDCHARS"
                                    | "TERMINFO"
                                    | "TERMINFO_DIRS"
                            ) {
                                deferred_env_setfns.push(DeferredEnvSetfn::Scalar(
                                    env_name.clone(),
                                    env_value.clone(),
                                )); // c:907-908
                            }
                        }
                        // c:Src/params.c:907-908 — env import always
                        // assigns through the GSU setfn; for tied
                        // IPDEF8 scalars that is colonarrsetfn
                        // (c:4329-4342), which colonsplit()s the value
                        // into the partner array, empties preserved.
                        // Not gated on still_unset: C re-assigns on
                        // import regardless.
                        if (pm.node.flags as u32 & crate::ported::zsh_h::PM_TIED) != 0 {
                            if let Some(ref peer) = pm.ename {
                                if peer != "path" && peer != "fpath" {
                                    tied_env_arrays.push((
                                        peer.clone(),
                                        env_value.split(':').map(String::from).collect(), // c:4339 colonsplit
                                    ));
                                }
                            }
                        }
                    } else {
                        // Fresh entry — PM_SCALAR + PM_EXPORTED, value
                        // taken from env. Mirrors C zsh's c:907-908
                        // `assignsparam(..., ASSPM_ENV_IMPORT)` for
                        // names not already in the special table.
                        let pm: crate::ported::zsh_h::Param = Box::new(param {
                            node: _hn {
                                next: None,
                                nam: env_name.clone(),
                                flags: (PM_SCALAR | PM_EXPORTED) as i32,
                            },
                            u_data: 0,
                            u_tied: None,
                            u_arr: None,
                            u_str: Some(env_value.clone()),
                            u_val: 0,
                            u_dval: 0.0,
                            u_hash: None,
                            gsu_s: None,
                            gsu_i: None,
                            gsu_f: None,
                            gsu_a: None,
                            gsu_h: None,
                            base: 0,
                            width: 0,
                            env: Some(format!("{}={}", env_name, env_value)),
                            ename: None,
                            old: None,
                            level: 0,
                        });
                        tab.insert(env_name, pm);
                    }
                }
                // Apply the collected tied-pair splits after the env
                // walk. setaparam (the canonical store) needs the
                // same paramtab write lock held here, so write u_arr
                // directly on the peer entry — array reads route
                // through paramtab so this is the single store.
                for (peer, parts) in tied_env_arrays {
                    if let Some(apm) = tab.get_mut(peer.as_str()) {
                        apm.u_arr = Some(parts); // c:4339 — `*dptr = colonsplit(x, …)`
                        apm.node.flags &= !(crate::ported::zsh_h::PM_UNSET as i32);
                    }
                }
                // c:Src/params.c:948-951 — runs AFTER the import loop:
                //     pm = (Param) paramtab->getnode(paramtab, "SHLVL");
                //     sprintf(buf, "%d", (int)++shlvl);
                //     /* shlvl value in environment needs updating unconditionally */
                //     addenv(pm, buf);
                // SHLVL is `IPDEF5("SHLVL", &shlvl, varinteger_gsu)` (c:358), so
                // the loop above has already parsed any inherited value into it
                // with zstrtol_underscore; C then increments THAT, in place.
                // Ordering is the whole point: the increment must observe the
                // imported value, and the import must not clobber the
                // increment. When SHLVL is absent from the environment the
                // param is still 0 here, so ++ yields 1 — matching C, whose
                // `shlvl` global starts at 0.
                //
                // addenv also exports the INCREMENTED value, which is why a
                // forked child sees 6 for `SHLVL=5 zsh -fc 'printenv SHLVL; true'`.
                // (A bare `printenv SHLVL` shows 5 because zsh exec's the last
                // command in place and backs the increment out — the shell is
                // being replaced, not nested. That is a separate mechanism,
                // ported for the explicit `exec` form at
                // fusevm_bridge.rs's BUILTIN_EXEC.)
                if let Some(pm) = tab.get_mut("SHLVL") {
                    let next = pm.u_val + 1; // c:949 `++shlvl`
                    // Queued like the import loop's dispatches above — SHLVL's
                    // setfn is a leaf today, but the rule is the pattern, not
                    // the current callee list. Storage half applied here for
                    // the same reason it is up there: c:951's `addenv` and
                    // everything after this guard must see the incremented
                    // value.
                    pm.u_val = next; // c:949 (the `*pm->u.valptr = x` half)
                    deferred_env_setfns.push(DeferredEnvSetfn::Int("SHLVL".to_string(), next)); // c:949
                    pm.node.flags &= !(PM_UNSET as i32);
                    // c:951 — the argument of the unconditional `addenv`.
                    // C renders it with `sprintf(buf, "%d", (int)shlvl)`
                    // AFTER the increment, so it is the incremented value.
                    shlvl_env = Some(next.to_string()); // c:950
                }
            }
        }
        // ---- paramtab guard released; replay the queued dispatches ----
        //
        // This is the c:907-908 / c:2774 / c:949 setfn call, moved to where no
        // lock is held, in the order C makes it. Each one runs against a
        // detached node — which is what C's pointer-to-the-live-node amounts to
        // once the lock is out of the way — and the integer arm publishes the
        // union slot the setfn wrote back onto the table afterwards. The scalar
        // specials need no publish: their setfns write a cached global
        // (`home_lock`, `wordchars_lock`, …) and ignore `pm`, matching C's
        // `UNUSED(Param pm)`. A node the setfn removed outright is simply
        // skipped.
        for deferred in deferred_env_setfns {
            match deferred {
                DeferredEnvSetfn::Int(name, ival) => {
                    let staged = crate::ported::params::paramtab()
                        .read()
                        .ok()
                        .and_then(|tab| tab.get(name.as_str()).map(|pm| (**pm).clone()));
                    let Some(mut staged) = staged else { continue };
                    crate::ported::params::intsetfn(&mut staged, ival); // c:2774
                    if let Ok(mut tab) = crate::ported::params::paramtab().write() {
                        if let Some(pm) = tab.get_mut(name.as_str()) {
                            pm.u_val = staged.u_val;
                        }
                    }
                }
                DeferredEnvSetfn::Scalar(name, value) => {
                    let staged = crate::ported::params::paramtab()
                        .read()
                        .ok()
                        .and_then(|tab| tab.get(name.as_str()).map(|pm| (**pm).clone()));
                    let Some(mut staged) = staged else { continue };
                    match name.as_str() {
                        "HOME" => crate::ported::params::homesetfn(&mut staged, value),
                        "USERNAME" => crate::ported::params::usernamesetfn(&mut staged, value),
                        "TERM" => crate::ported::params::termsetfn(&mut staged, value),
                        "WORDCHARS" => crate::ported::params::wordcharssetfn(&mut staged, value),
                        "TERMINFO" => crate::ported::params::terminfosetfn(&mut staged, value),
                        "TERMINFO_DIRS" => {
                            crate::ported::params::terminfodirssetfn(&mut staged, value)
                        }
                        _ => {}
                    }
                }
            }
        }
        // c:Src/params.c:960-965 — HOME wiring, which C runs right
        // after the environment-import loop:
        //     pm = (Param) realparamtab->getnode2(realparamtab, "HOME");
        //     if (EMULATION(EMULATE_ZSH))
        //     {
        //         pm->node.flags &= ~PM_UNSET;
        //         if (!(pm->node.flags & PM_EXPORTED))
        //             addenv(pm, home);
        //     } else if (!home)
        //         pm->node.flags |= PM_UNSET;
        // `home` itself was synthesised from the password database
        // back in setupvals (c:Src/init.c:1237-1250) BEFORE the import
        // loop, so an inherited $HOME wins: the import calls
        // `homesetfn` and overwrites the synthesised value.
        //
        // zshrs reaches neither of those C sites from this bin entry,
        // so `$HOME` was whatever the environment supplied and nothing
        // else — a scrubbed launch (cron, launchd/systemd unit,
        // container entrypoint, `env -i`) got no $HOME at all, and
        // every `~`, rc-file path and cache path derived from it
        // silently resolved to "" (`~/x` expanded to `/x`).
        //
        // Ordering is preserved by only synthesising when the import
        // produced nothing: `var_os` is the exact "was it in the
        // environment" test C's loop keys off, so an explicitly empty
        // `HOME=` still stays empty (reference binary: `env -i … HOME=
        // zsh -f -c 'print -r -- "[${HOME-UNSET}]"'` prints `[]`).
        //
        // `home` itself comes from c:Src/init.c:1237-1250, inlined here
        // because C has no function to port — it is straight-line code
        // inside `setupvals()`:
        //     #ifdef USE_GETPWUID
        //         if ((pswd = getpwuid(cached_uid))) {
        //             if (EMULATION(EMULATE_ZSH))
        //                 home = ztrdup_metafy(pswd->pw_dir);
        //             cached_username = ztrdup_metafy(pswd->pw_name);
        //         }
        //         else
        //     #endif /* USE_GETPWUID */
        //         {
        //             if (EMULATION(EMULATE_ZSH))
        //                 home = ztrdup("/");
        //             cached_username = ztrdup("");
        //         }
        // Both arms are guarded on EMULATE_ZSH: under sh/ksh emulation
        // the C global stays NULL and `$HOME` can only come from the
        // environment. Reference binary agrees — `env -i TERM=dumb
        // PATH=/usr/bin:/bin zsh --emulate sh -f -c 'echo
        // "HOME=${HOME-UNSET}"'` prints `HOME=UNSET`, while the same
        // command without `--emulate sh` prints the password-database
        // home. `cached_username` is seeded separately (see the
        // getlogin() block below), so only the `home` half is here.
        if std::env::var_os("HOME").is_none()
            && crate::ported::zsh_h::EMULATION(crate::ported::zsh_h::EMULATE_ZSH)
        {
            // c:Src/init.c:1239 — `getpwuid(cached_uid)`, cached_uid
            // being `getuid()` from c:1235.
            let pswd = unsafe { libc::getpwuid(libc::getuid()) };
            let pw_dir = if pswd.is_null() {
                std::ptr::null()
            } else {
                unsafe { (*pswd).pw_dir }
            };
            let h = if pw_dir.is_null() {
                // c:1248 — password lookup failed: `home = ztrdup("/")`.
                // A NULL `pw_dir` on a present entry is the same
                // "no usable home" case.
                "/".to_string()
            } else {
                // c:1241 — `home = ztrdup_metafy(pswd->pw_dir)`.
                crate::ported::utils::metafy(
                    &unsafe { std::ffi::CStr::from_ptr(pw_dir) }.to_string_lossy(),
                )
            };
            // Routes through `homesetfn`, so the `home` global and the
            // paramtab entry agree (c:Src/params.c:5118).
            crate::ported::params::setsparam("HOME", &h);
            // c:964-965 — the param is not PM_EXPORTED (it was not
            // imported), so C addenv's it. The reference binary
            // confirms the synthesised value reaches children:
            // `env -i TERM=dumb PATH=/usr/bin:/bin zsh -f -c
            // '/usr/bin/env'` lists `HOME=/Users/…`.
            crate::ported::params::addenv("HOME", &h);
        }

        // c:Src/params.c:968-970 — `pm = realparamtab->getnode2(realparamtab,
        // "LOGNAME"); if (!(pm->node.flags & PM_EXPORTED)) addenv(pm, pm->u.str);`
        //
        // Unconditional in C, right after the HOME block above, and the same
        // shape: the param was SEEDED (c:878-882, from `getlogin()`) rather
        // than imported, so it carries no PM_EXPORTED and C exports it here.
        // The faithful port of this lives in `createparamtable`
        // (ported/params.rs, c:968-970) but that function is not on this
        // entry path — `ShellExecutor::new` is — so the seeded value never
        // reached the environment. Measured under a scrubbed env:
        //
        //   env -i HOME=$HOME TERM=xterm PATH=... <shell> -f -c '${(t)LOGNAME}'
        //     zsh  : scalar-export      zshrs: scalar
        //
        // and a child of zshrs saw no LOGNAME at all where a child of zsh did.
        // Like the SHLVL case above, C exports a value the import loop did not
        // supply; unlike it, there is no paired exec-time adjustment.
        if let Some(v) = crate::ported::params::getsparam("LOGNAME") {
            crate::ported::params::addenv("LOGNAME", &v); // c:970
        }

        // c:Src/params.c:951 — `addenv(pm, buf)`. Unconditional: the C comment
        // on the line above it is "shlvl value in environment needs updating
        // unconditionally". `addenv` both zputenv's the string and stamps
        // `pm->node.flags |= PM_EXPORTED` (c:Src/params.c:5482-5484), so this
        // one call is what makes `${(t)SHLVL}` read `integer-export-special`
        // AND what puts the incremented number in a forked child's
        // environment.
        //
        // Omitting it left $SHLVL unable to count nesting at all — measured
        // with each shell nesting itself twice, the inner shells FORKED so
        // that no exec-in-place decrement applies:
        //     zsh    L1=1 L2=2 L3=3
        //     zshrs  L1=1 L2=1 L3=1
        // because every nested zshrs re-read the grandparent's stale
        // environment entry instead of the parent's incremented one. It also
        // left the parameter unexported under a scrubbed environment
        // (`env -i … -f -c '${(t)SHLVL}'`: zsh `integer-export-special`,
        // zshrs `integer-special`), which a completion listing sees directly:
        // `env <TAB>` runs `_parameters -g "*export*"` and zsh offered SHLVL
        // there where zshrs did not.
        // It follows the HOME and LOGNAME exports, as in C (c:960-974), so a
        // child sees them in zsh's environment order.
        if let Some(v) = shlvl_env {
            crate::ported::params::addenv("SHLVL", &v); // c:951
        }

        // SHLVL's paired exec-time half — c:Src/exec.c:
        // 4332-4336, "for either implicit or explicit exec, decrease $SHLVL as
        // we're now done as a shell", guarded by `!subsh && !forked` — is
        // ported for the EXPLICIT `exec cmd` form at fusevm_bridge.rs's
        // BUILTIN_EXEC, the one place fusevm replaces its own process.
        //
        // Still open: C also execs IN PLACE for the LAST command of a `-c`
        // script, and fusevm always forks there (`zsh -fc 'echo $$; /bin/sh -c
        // "echo \$\$"'` reports one pid on zsh, two on zshrs). So
        // `SHLVL=5 <shell> -fc '/usr/bin/env'` shows SHLVL=5 on zsh (exec'd,
        // decremented) and SHLVL=6 on zshrs (forked, so C's own rule says do
        // not decrement). That divergence belongs to the unported implicit
        // exec-in-place, not to the SHLVL wiring: fixing it means teaching
        // fusevm C's `do_exec` for the final command, and until then the
        // forked answer is the one C would give for a forked command.
        // c:Src/init.c:1907-1909 — `SHTTY = -1; init_io(cmd); setupvals(...)`.
        // zsh_main runs those three in that order, and this constructor stands
        // in for setupvals's param setup on the drivers that never reach
        // zsh_main: `zshrs -c CODE` dispatches at bins/zshrs.rs:1716 (after
        // --zsh/-f are stripped) straight into ShellExecutor::new + exit. So
        // init_io has to happen here, or SHTTY is still -1 and the winsize
        // probe below silently no-ops (adjustwinsize early-returns at
        // c:1900-1901). setupvals's own adjustwinsize(0) covers the zsh_main
        // path; init_io is idempotent (c:615-618 closes and reopens SHTTY), so
        // that path just re-establishes it a moment later.
        crate::ported::init::init_io(None); // c:1908
        crate::startup_trace::mark("exec: init_io");

        // c:Src/init.c:1274-1276 — `adjustwinsize(0)`, the first thing after
        // createparamtable (c:1270). Probes the tty via TIOCGWINSZ and
        // publishes the geometry to $COLUMNS/$LINES.
        //
        // Ordering is C's, and load-bearing in both directions: it must FOLLOW
        // init_io (which sets SHTTY) and it must FOLLOW the environ import
        // above, because the tty geometry OVERRIDES an inherited COLUMNS — a
        // 97-column terminal reports 97 even when COLUMNS=10 was exported in.
        // (C gets that via the c:1906-1907 "Signal missed while a job owned the
        // tty?" promotion of from=0 to from=1, which makes adjustcolumns take
        // the signalled path and overwrite zterm_columns with ws_col.)
        //
        // With no terminal at all, SHTTY stays -1 and the imported value (or 0)
        // survives untouched — which is what C's zterm_columns does there, and
        // why a piped `COLUMNS=20 zshrs -c` still reports 20. Note SHTTY does
        // NOT require stdin/stdout to be a tty: init_io's last resort is
        // `open("/dev/tty")` (c:667-670), so a piped-but-still-attached shell
        // gets the real width, matching `zsh -fc 'print $COLUMNS | cat'`.
        let _ = crate::ported::utils::adjustwinsize(0); // c:1276
        crate::startup_trace::mark("exec: adjustwinsize");

        // c:Src/params.c:955 — `set_pwd_env();` runs AFTER the environ
        // import loop, overwriting the imported $PWD/$OLDPWD paramtab
        // entries with the ispwd()-validated values computed above
        // (c:Src/init.c:1242-1259). Without this, a stale inherited
        // $PWD (env-import snapshot taken at process entry) survives
        // in paramtab even though the live env was corrected.
        // The live environment is the carrier set_pwd_env reads for C's
        // `pwd`/`oldpwd` globals (see the c:Src/init.c:1242-1259 block above).
        env::set_var("PWD", &pwd_val);
        env::set_var("OLDPWD", &oldpwd_val);
        crate::ported::builtin::set_pwd_env();
        crate::startup_trace::mark("exec: set_pwd_env");

        // c:Src/params.c:975-992 — host/arch identification params:
        // CPUTYPE / MACHTYPE / OSTYPE / VENDOR. C zsh reads from
        // compile-time `#define`s (set by ./configure) for MACHTYPE /
        // OSTYPE / VENDOR, and from uname().machine at runtime for
        // CPUTYPE.
        //
        // Rust port: probe uname() at startup for CPUTYPE, and use
        // const strings parameterized by build-target for the
        // others. Match homebrew zsh's values where possible.
        let mut uname_buf: libc::utsname = unsafe { std::mem::zeroed() };
        let _ = unsafe { libc::uname(&mut uname_buf) };
        let to_str = |b: &[libc::c_char]| -> String {
            // c-string → owned String, truncated at first NUL.
            let bytes: Vec<u8> = b
                .iter()
                .take_while(|&&c| c != 0)
                .map(|&c| c as u8)
                .collect();
            String::from_utf8_lossy(&bytes).into_owned()
        };
        let cputype = to_str(&uname_buf.machine);
        crate::ported::params::setsparam("CPUTYPE", &cputype); // c:961
                                                               // OSTYPE: configure's `$host_os`, resolved on the build host and
                                                               // frozen into config.h — C never re-derives it from uname() at
                                                               // startup. Deriving it here made the two writers disagree, so the
                                                               // same binary answered `darwin25.5.0` under -c and `darwin23.6.0`
                                                               // under -i. Single source of truth: config_h::OSTYPE, exactly as
                                                               // MACHTYPE below.
        crate::ported::params::setsparam("OSTYPE", crate::ported::config_h::OSTYPE); // c:990
                                                                                     // MACHTYPE: configure's `$host_cpu`, i.e. the config.guess
                                                                                     // canonical arch name — NOT uname's `machine`. The two differ
                                                                                     // on Apple Silicon (uname says `arm64`, config.guess says
                                                                                     // `aarch64`), and zsh reports the latter. Single source of
                                                                                     // truth: config_h::MACHTYPE (= build target arch).
        crate::ported::params::setsparam("MACHTYPE", crate::ported::config_h::MACHTYPE); // c:967
                                                                                         // VENDOR: configure's `$host_vendor`. Deriving it from uname's
                                                                                         // `sysname` here was a second, non-C writer that disagreed with
                                                                                         // `config_h::VENDOR` off Darwin: config.guess emits `pc` for x86_64
                                                                                         // Linux (config.guess:1222) and `unknown` for aarch64 Linux
                                                                                         // (config.guess:1009), a distinction `sysname` cannot make. Single
                                                                                         // source of truth, exactly as OSTYPE/MACHTYPE above.
        crate::ported::params::setsparam("VENDOR", crate::ported::config_h::VENDOR); // c:992

        // c:Src/init.c:963 — `setsparam("TTY", ttyname(0) ?: "")`, which
        // C reaches at c:969 in the createparamtable tail. Even a
        // non-interactive -fc shell creates the param.
        let tty_str = unsafe {
            let p = libc::ttyname(0);
            if p.is_null() {
                String::new()
            } else {
                std::ffi::CStr::from_ptr(p)
                    .to_str()
                    .unwrap_or("")
                    .to_string()
            }
        };
        crate::ported::params::setsparam("TTY", &tty_str); // c:969
                                                           // c:Src/params.c:971 — `setsparam("ZSH_ARGZERO", ztrdup(posixzero))`:
                                                           // the kernel-supplied argv[0] of THIS binary, in --zsh parity mode
                                                           // too. The bin entrypoint overrides this with the script path for
                                                           // -c / runscript invocations. (A previous revision probed the
                                                           // system zsh install path and reported THAT as ZSH_ARGZERO for
                                                           // byte-parity — faking the shell's identity. Parity tests that
                                                           // compare the value must normalize the machine-specific binary
                                                           // path in the test row instead.)
        let argzero_default = env::args().next().unwrap_or_else(|| "zsh".to_string());
        crate::ported::params::setsparam("ZSH_ARGZERO", &argzero_default); // c:971
                                                                           // c:Src/params.c:972 — ZSH_VERSION. `zsh_version::ZSH_VERSION`
                                                                           // (emitted by build.rs from the vendored `Config/version.mk`) is
                                                                           // the development snapshot tag `5.9.0.3-test`; shipped zsh
                                                                           // binaries report the clean release form (`5.9`). Bug #73 in
                                                                           // docs/BUGS.md — cross-shell scripts that gate on
                                                                           // `[[ $ZSH_VERSION = 5.9 ]]` or split on `.` expecting
                                                                           // MAJOR.MINOR break on the `-test` suffix. Use the cleaned
                                                                           // `patchlevel::ZSH_VERSION` here ("5.9") and surface the full
                                                                           // snapshot tag as `$ZSHRS_VERSION` for zshrs identity checks.
        crate::ported::params::setsparam("ZSH_VERSION", crate::ported::patchlevel::ZSH_VERSION); // c:972
                                                                                                 // c:Src/params.c:973 + Src/patchlevel.h — `ZSH_PATCHLEVEL` is a
                                                                                                 // git-describe-style identifier (`zsh-MAJOR.MINOR-N-gHASH`) of
                                                                                                 // the upstream commit zshrs targets. `build.rs` emits "unknown"
                                                                                                 // because the vendored zsh tarball ships no CUSTOM_PATCHLEVEL
                                                                                                 // define; use the canonical const in `patchlevel.rs` instead.
                                                                                                 // Bug #90 in docs/BUGS.md — scripts that fingerprint by
                                                                                                 // $ZSH_PATCHLEVEL fell to the wildcard arm under "unknown".
        crate::ported::params::setsparam(
            "ZSH_PATCHLEVEL",
            crate::ported::patchlevel::ZSH_PATCHLEVEL,
        ); // c:973
           // Skip ZSHRS_VERSION whenever the zsh-compatible namespace must
           // stay free of zshrs-original names, so `${(k)parameters}`
           // doesn't carry a name zsh doesn't ship — same predicate and
           // reasoning as the guard in `ported::params::createparamtable`.
           // `hide_ext_builtins()` is `--zsh` OR `ZSHRS_HIDE_EXT_BUILTINS`
           // (the parity harnesses' knob). Scripts can still detect zshrs
           // via `$ZSH_VERSION`, which carries a `-test` suffix.
        if !crate::ext_builtins::hide_ext_builtins() {
            crate::ported::params::setsparam(
                "ZSHRS_VERSION",
                crate::ported::patchlevel::ZSHRS_VERSION,
            );
        }
        // `$HELPDIR` points at the bundled help tree that
        // `bundled_docs::install_and_publish` (top of this constructor)
        // materialised, so `run-help` works on a host with no zsh install.
        // It is seeded HERE, after the environment-import loop above, for
        // two reasons: the table has to exist to hold it, and an exported
        // `HELPDIR` the user supplied is already imported by now, so the
        // seed's own guard leaves that value (and its PM_EXPORTED) alone.
        //
        // The parameter is NOT exported. `run-help` is a shell function
        // that reads `${HELPDIR:-…}` out of the shell's own table, so the
        // environment entry this used to create bought nothing and leaked
        // the name into every child process — `env <TAB>`, which lists
        // exported names, offered a name zsh does not have.
        crate::bundled_docs::seed_helpdir_param();
        // c:Src/params.c:974-979 — `setaparam("signals", …)`.
        {
            use crate::ported::signals_h::SIGS;
            // c:signames.c sigs[] (generated) — index 0 is "EXIT",
            // entries 1..=SIGCOUNT are in PLATFORM SIGNAL-NUMBER
            // order, tail is "ZERR", "DEBUG" (zsh.h SIGZERR/SIGDEBUG).
            // SIGS is declared in Linux textual order, so sort by the
            // libc number to reproduce the generated table's order on
            // every platform. Same construction as params.rs — keep
            // in sync.
            let mut by_num: Vec<(&str, i32)> = SIGS.to_vec();
            by_num.sort_by_key(|&(_, n)| n);
            let mut signals_arr: Vec<String> = Vec::with_capacity(by_num.len() + 3);
            signals_arr.push("EXIT".to_string()); // c:sigs[0]
            signals_arr.extend(by_num.iter().map(|(n, _)| n.to_string()));
            // c:Src/params.c:1018-1021 — the real-time names follow.
            #[cfg(target_os = "linux")]
            signals_arr.extend(
                (libc::SIGRTMIN()..=libc::SIGRTMAX()).map(crate::ported::signals::rtsigname),
            );
            signals_arr.push("ZERR".to_string()); // c:sigs tail
            signals_arr.push("DEBUG".to_string()); // c:sigs tail
            crate::ported::params::setaparam("signals", signals_arr); // c:974
        }
        // c:Src/init.c:1364 — `setsparam("ZSH_NAME", ztrdup(zsh_name))`,
        // which setupvals runs AFTER createparamtable, so the node lands
        // ahead of the imported environment in its bucket chain.
        crate::ported::params::setsparam("ZSH_NAME", "zsh"); // c:Src/init.c:1364
        crate::startup_trace::mark("exec: base params set");
                                                             // LOGNAME is seeded pre-import now (c:878) — see the block by the
                                                             // TMPPREFIX/HOST seeds above.
                                                             //
                                                             // DO NOT setsparam("USERNAME", ...) anywhere in init. `$USERNAME`
                                                             // is a special parameter whose SETTER (`usernamesetfn` in
                                                             // params.rs) performs setgid(2) + setuid(2) to actually change
                                                             // the effective user — a deliberate upstream zsh feature for
                                                             // `USERNAME=other-user cmd`. Calling it at init seeds the value
                                                             // AND tries to change uid/gid; when the resolved pwd's pw_uid
                                                             // differs from `getuid()` (sudo launches, macOS Keychain-helper
                                                             // inherited env, container entry points, etc.) the setgid call
                                                             // fails with EPERM and emits `zsh:1: failed to change group ID:
                                                             // Operation not permitted`. Upstream seeds `$USERNAME` via the
                                                             // GETTER path (`usernamegetfn` reads through `cached_username`
                                                             // populated by `inittyptab` → `get_username`), no setter call.

        // c:Src/init.c:1176 — `module_path = mkarray(MODULE_DIR)`.
        // The canonical init lives in `init::setupvals` (port of
        // `Src/init.c:setupvals`); the bin entry skips setupvals (per
        // the init_bltinmods comment above), so call the lightweight
        // module_path bootstrap exposed by init.rs from here. This
        // mirrors the HOST gethostname seeding pattern above:
        // duplicated init that should collapse into a full setupvals

        // c:Src/init.c:1945 init_bltinmods — runs right after setupvals
        // (c:1942), i.e. after createparamtable's import, so the module
        // autoload stubs (`WATCH`, `watch`, …) are created HERE. The bin
        // entry skips zsh_main → init_bltinmods, so run it from
        // ShellExecutor::new for the same effect. Bug #270.
        // c:Src/init.c:1085 — `(void)addhookdefs(NULL, zshhooks, ...)`, a
        // setupvals step. The bin entry skips setupvals, so without this
        // hooktab stayed empty: `zmodload zsh/nearcolor`'s boot_
        // (nearcolor.c:199) found no "get_color_attr" hookdef to attach
        // getnearestcolor to, and `%F{#hex}` never mapped to the palette.
        // Shared once-guard with setupvals (see init::ZSHHOOKS_ADDED).
        crate::ported::init::ZSHHOOKS_ADDED.call_once(|| {
            let base = crate::ported::init::zshhooks.load(std::sync::atomic::Ordering::SeqCst);
            let _ = crate::ported::module::addhookdefs(std::ptr::null(), base, 4);
        });
        crate::ported::init::init_bltinmods(); // c:Src/init.c:1945
        crate::startup_trace::mark("exec: init_bltinmods");

        // Populate paramtab with PM_SPECIAL Params for every PARTAB /
        // PARTAB_ARRAY magic-assoc name. Mirrors what C's zsh/parameter
        // module boot_ → handlefeatures chain does — which happens when
        // the module LOADS, after init_bltinmods planted its autoload
        // stubs, and `addparamdef` unsets the stub before creating the
        // real param (c:Src/module.c addparamdef → unsetparam_pm +
        // createparam), so these names take a FRESH chain slot ahead of
        // the stubs. Running this before init_bltinmods put `usergroups`
        // and friends behind `WATCH` in `${(k)parameters}`.
        init_partab_params(); // c:Src/Modules/parameter.c:2341 boot_/enables_ chain
        crate::startup_trace::mark("exec: init_partab_params");

        // HOST is seeded pre-import now (c:875) — see the block next to
        // the TMPPREFIX/LOGNAME seeds above.
        // bash startup delta: bash defines TERM itself when the
        // environment does not carry one, and exports it. zsh leaves
        // TERM unset in that case, so `zshrs --bash` inherited zsh's
        // behavior and diverged from the reference shell:
        //
        //   $ env -u TERM /bin/bash -c 'printf "%s\n" "${TERM+set}"'
        //   set
        //   $ env -u TERM /bin/bash -c 'echo "$TERM"'
        //   dumb
        //   $ env -u TERM /bin/zsh -f -c 'printf "%s\n" "${TERM+set}"'
        //                                  (empty — zsh leaves it unset)
        //
        // Same on bash 3.2.57 (macOS /bin/bash) and 5.3.15, so it is
        // not a version artifact. Only the bare `--bash` drop-in takes
        // it: `--bash --zsh` asks for zsh-STYLE emulation, where zsh's
        // leave-it-unset behavior is the correct answer. Guarded on the
        // environment so an inherited TERM always wins.
        if crate::extensions::dash_mode::bash_mode() && std::env::var_os("TERM").is_none() {
            crate::ported::params::setsparam("TERM", "dumb");
            // bash exports it (`declare -x TERM` shows up in `export -p`);
            // addenv stamps PM_EXPORTED and pushes it into the child env.
            crate::ported::params::addenv("TERM", "dumb");
        }

        // c:Src/init.c:479 — `-c` mode: scriptname = scriptfilename
        // = ztrdup("zsh"). Both globals start as the literal "zsh"
        // (not the binary path) so PS4's %x / %N print "zsh" not
        // "/path/to/zshrs" at the top level. Function dispatch
        // overrides scriptname per c:5903; scriptfilename stays.
        crate::startup_trace::mark("exec: pre-scriptname");
        crate::ported::utils::set_scriptname(Some("zsh".to_string()));
        // c:Src/init.c:470-479 — `scriptname = scriptfilename =
        // ztrdup("zsh")` sits INSIDE the `-c` branch of the option parse.
        // An interactive shell (or one running a script file) leaves
        // `scriptfilename` NULL, and exec.c:5383 copies it onto every
        // Shfunc it defines — which is why zsh reports an EMPTY
        // `$functions_source[f]` for a function typed at the prompt.
        // Stamping "zsh" unconditionally made zshrs answer "zsh" there.
        let dash_c = std::env::args_os()
            .skip(1)
            .map(|a| a.to_string_lossy().into_owned())
            .any(|a| a.starts_with('-') && !a.starts_with("--") && a.contains('c'));
        if dash_c {
            crate::ported::utils::set_scriptfilename(Some("zsh".to_string())); // c:479
        }

        // call once that port is complete.
        crate::startup_trace::mark("exec: pre-module_path_init");
        crate::ported::init::module_path_init();

        // Publish `fpath` LAST, once every special has been seeded.
        //
        // The earlier `set_array("fpath", …)` above lands before the tied
        // FPATH/fpath special is created, and creating it resets the node
        // to empty -- so an INTERACTIVE shell reached its first prompt with
        //     typeset -aT FPATH fpath=(  )
        // while `$FPATH` still read the full four-entry string. `path`
        // hid the bug: `PATH` is always in the environ, so the env import
        // refills it, whereas zsh never exports `FPATH` and nothing
        // refilled that one.
        //
        // The damage was not a missing default: a `.zshrc` that does
        // `fpath=( mydir $fpath )` -- the standard idiom -- appended to
        // NOTHING, so the shell ended up with only what the rc file added
        // and lost the bundled tree entirely.
        //
        // `-c` was unaffected, which is why every non-interactive probe of
        // this passed.
        let fpath_final: Vec<String> = exec
            .fpath
            .iter()
            .map(|p| p.to_string_lossy().to_string())
            .collect();
        if !fpath_final.is_empty() {
            // The ENVIRONMENT has to carry the final value too, not just
            // paramtab. `setupvals` re-seeds the tied specials and the
            // split that refills `fpath` reads the FPATH string; with an
            // inherited FPATH that string was still the one this process
            // started with, so the bundled tree -- appended to the param
            // only -- vanished the moment a shell was interactive AND had
            // FPATH set. `-c` never re-seeds, which is why it kept showing
            // the correct list.
            unsafe { std::env::set_var("FPATH", fpath_final.join(":")) };
            exec.set_array("fpath".to_string(), fpath_final);
        }
        crate::startup_trace::mark("new() end");

        exec
    }

    /// The SQLite history index, opened on first call.
    ///
    /// Startup no longer pays for it: only the three diagnostic readers
    /// (`--doctor`, the cache report, `dbview history`) reach this, and a
    /// pool worker's cell is pre-filled with `None` so it stays closed
    /// there.
    pub fn history(&self) -> Option<&HistoryEngine> {
        self.history
            .get_or_init(|| HistoryEngine::new().ok())
            .as_ref()
    }

    /// 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. Cached path uses
        // `run_chunk` (the shared VM-execution helper); script-eval
        // path delegates to `execute_script_zsh_pipeline` so the
        // full parse/compile/cache-save/run flow stays in one place.
        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"
                    );
                    return self.run_chunk(chunk, &format!("execute_script_file:cache:{abs_path}"));
                }
            }
        }

        // Cache miss.
        // c:Src/init.c:1394-1395 — `SHIN = movefd(open(funmeta, …))`, then
        // zsh_main's `loop(1,0)` (c:1963) reads the script ONE EVENT AT A
        // TIME: `lexinit(); parse_event(ENDINPUT); … execode(prog, …)`
        // (c:155-220). Every complete command runs before the next is
        // lexed, so an `alias` a line installs is in force for the next
        // line, and a syntax error on line N leaves lines 1..N-1 already
        // executed. A whole-file compile lexed every line with the state
        // the file started with and ran nothing when any line failed to
        // parse. The event loop is the one `source` uses (c:1626-1627
        // `loop(0, 0)`): with `interact` unset, c:234's
        // `(!interact || sourcelevel) && errflag` break is the same test.
        // c:Src/init.c:1566 / Src/input.c — the file is read as RAW BYTES and
        // metafied (Src/utils.c:4856), never rejected for non-UTF-8.
        let content = crate::script_bytes::read_script_file(file_path)
            .map_err(|e| format!("{}: {}", file_path, e))?;
        let mut events: Vec<crate::parse::ZshList> = Vec::new();
        // c:Src/init.c:1963 — zsh_main runs the script through `loop(1, 0)`:
        // toplevel.
        let mut status = self.run_events_per_command(&content, Some(&mut events), true)?;
        // c:Src/init.c:1969-1974 — `if (tok == LEXERR || errexit) { if
        // (!lastval) lastval = 1; stopmsg = 1; zexit(lastval, …); }`: a
        // parse error, or an error abort in a non-interactive shell, exits
        // non-zero even when the last command that ran succeeded.
        if (errflag.load(Ordering::Relaxed) & ERRFLAG_ERROR) != 0 {
            if status == 0 {
                status = 1; // c:1971-1972
                self.set_last_status(status);
            }
            // c:Src/builtin.c:6006 zexit — `errflag = 0;` before the EXIT trap
            // runs, so the trap body is not itself aborted by the error.
            errflag.fetch_and(!ERRFLAG_ERROR, Ordering::Relaxed);
        }
        let status = self.fire_script_exit_hooks(status)?;

        // Best-effort cache save — failures don't block execution. The
        // cached program is the events exactly as the loop lexed them, so
        // a hit replays what this run parsed; `events` is empty unless the
        // loop drained the whole file without an error.
        if !events.is_empty() {
            let program = crate::parse::ZshProgram { lists: events };
            let compiler = crate::compile_zsh::ZshCompiler::new();
            let chunk = compiler.compile(&program);
            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"
                );
            }
        }

        Ok(status)
    }

    /// Run a compiled `fusevm::Chunk` to completion inside this
    /// executor's context. Shared by `execute_script_zsh_pipeline`,
    /// `execute_script_file`'s bytecode-cache hit path, and the
    /// function-dispatch body_runner. Centralises the VM setup so
    /// `register_builtins` and `ExecutorContext::enter` invariants
    /// stay in lockstep.
    fn run_chunk(&mut self, chunk: fusevm::Chunk, label: &str) -> Result<i32, String> {
        if chunk.ops.is_empty() {
            return Ok(self.last_status());
        }
        crate::fusevm_disasm::maybe_print_stdout(label, &chunk);
        let mut vm = crate::vm_pool::acquire(chunk);
        // Seed vm.last_status with the executor's current LASTVAL so
        // sub-VMs (EXIT trap bodies, eval, source) see the inherited
        // `$?` from the caller's last command — matching C zsh where
        // lastval is a process global. Without this, the new VM
        // started at 0 and BUILTIN_GET_VAR's sync_status would write
        // 0 back into LASTVAL on the first `$?` read.
        vm.last_status = self.last_status();
        let _ctx = ExecutorContext::enter(self);
        // c:Src/loop.c — `loops` is bracketed by the C interpreter's own
        // recursion, so a `return` or an errflag abort out of a loop
        // unwinds it for free. A compiled chunk instead jumps straight to
        // its end, skipping the loop's `loops--`. Restoring the count the
        // chunk started with makes that structurally impossible to leak:
        // whatever loops this chunk opened are closed when it finishes.
        let loops_entry = crate::ported::builtin::LOOPS.load(Ordering::Relaxed);
        // c:Src/exec.c:4364 `done:` → `fixfds(save)` — every execcmd puts
        // back the fds its redirections replaced, whether it ran or was
        // abandoned on errflag. A chunk abandoned mid-command (`eval 'echo >
        // nx(N)'`: the target's expansion raises errflag after the scope
        // opened) jumped past its WithRedirectsEnd, so the caller kept
        // writing into the failed redirection's sink. Same unwind the
        // function-call path does (`unwind_redirect_scopes_to`).
        let redir_depth = self.redirect_scope_stack.len();
        // Same for the job slots of pipelines the chunk was running when it
        // was abandoned (see exec_jobs::execpline_slot_open).
        let slots_entry = crate::exec_jobs::execpline_slots_mark();
        let result = vm.run();
        crate::ported::builtin::LOOPS.store(loops_entry, Ordering::Relaxed);
        crate::exec_jobs::execpline_slots_release_to(slots_entry);
        self.unwind_redirect_scopes_to(redir_depth);
        match result {
            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())
    }

    /// Execute via the lex+parse free ported + ZshCompiler pipeline.
    /// This is the only execution path; `execute_script` delegates here.
    /// Parse + compile `script` in an isolated lexer context, without
    /// running it.
    ///
    /// Split out of [`ShellExecutor::execute_script_zsh_pipeline`] so the
    /// autoload loader can get its hands on the compiled chunk: that chunk
    /// is what lands in `~/.zshrs/autoloads.rkyv`, so the next process can
    /// install the same function without re-parsing the definition file.
    fn compile_script_isolated(&mut self, script: &str) -> Result<fusevm::Chunk, String> {
        self.compile_script_isolated_at(script, None)
    }

    /// `compile_script_isolated` with C's `parse_string(s, reset_lineno)`
    /// argument: `Some(n)` is `parse_string(s, 0)` (c:Src/exec.c:291-300),
    /// the body parsed from the running line `n` (see `parse_isolated_at`).
    fn compile_script_isolated_at(
        &mut self,
        script: &str,
        lineno: Option<u64>,
    ) -> Result<fusevm::Chunk, 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);
        // Context-isolated parse (c:Src/exec.c:283 parse_string). eval /
        // source / autoload-register / trap bodies all reach here and run
        // DURING execution; on the faithful single-event loop()/parse_event
        // reader, a bare parse_init/lex_init would steal the outer's next
        // SHIN line into this nested program (e.g. `eval "x=5"` swallowed the
        // following `echo $x` off stdin). parse_isolated sets `strin` so the
        // string drains to EOF; execution below stays in the current shell.
        let program = parse_isolated_at(script, lineno);
        let parse_failed = (errflag.load(Ordering::Relaxed) & ERRFLAG_ERROR) != 0;
        errflag.store(saved_errflag, Ordering::Relaxed);
        if parse_failed {
            // c:Src/init.c — when the parser fires `zerr(...)`, the C
            // shell's `loop()` body skips the eval pass and continues;
            // there's no second "parse error" diagnostic. The Rust
            // binary's call sites print `zshrs: <e>` on Err, doubling
            // up on the message the parser already emitted via zerr.
            // Use a `__SILENCED__` sentinel that the binary's
            // execute_script wrapper recognizes as "already reported,
            // exit silently". Bug #142 in docs/BUGS.md (double-print
            // half).
            return Err("__SILENCED__".to_string());
        }

        let mut compiler = crate::compile_zsh::ZshCompiler::new();
        compiler.nested_lineno_base = lineno; // c:Src/exec.c:297 reset_lineno == 0
        if CMDARG_EXITING.with(|c| c.replace(false)) {
            // c:Src/init.c:1568 — `execstring(cmd, 0, 1, "cmdarg")`: the `-c`
            // string runs as an EXITING list, so its last command is the
            // fake exec's candidate (BUILTIN_EXEC_FORKED_SIMPLE mode 2).
            compiler.forked_tail_list = crate::compile_zsh::program_exiting_tail(&program);
            compiler.exiting_tail_mode = 2;
        }
        Ok(compiler.compile(&program))
    }

    /// `execstring(cmd, 0, 1, "cmdarg")` (c:Src/init.c:1568) — run the `-c`
    /// string as the shell's last act: [`Self::execute_script`] with the
    /// string compiled as an exiting list (see CMDARG_EXITING).
    pub fn execute_cmdarg(&mut self, script: &str) -> Result<i32, String> {
        CMDARG_EXITING.with(|c| c.set(true));
        let chunk = self.compile_script_isolated(script);
        CMDARG_EXITING.with(|c| c.set(false));
        let status = self.run_chunk(chunk?, "cmdarg")?;
        // c:Src/init.c:1572 — `zexit(lastval, ZEXIT_NORMAL)` follows the
        // `-c` string, and c:Src/builtin.c:6012-6015 clears the error state
        // before the EXIT trap (`errflag = intrap = 0; if
        // (sigtrapped[SIGEXIT]) dotrap(SIGEXIT);`): dotrapargs refuses to
        // run anything while errflag is set (c:Src/signals.c:1101), so a
        // script that ended on an error abort (`ro=2` on a readonly, `${x?}`,
        // `$((1/0))`) would otherwise skip its EXIT trap. The flag is put
        // back afterwards because the caller still reads it to pick the
        // exit status of the dash-family drop-ins.
        let saved_errflag = errflag.load(Ordering::Relaxed);
        errflag.store(0, Ordering::Relaxed); // c:6012
        let result = self.fire_script_exit_hooks(status);
        errflag.fetch_or(saved_errflag, Ordering::Relaxed);
        result
    }

    /// Run an already-compiled top-level chunk, then fire the end-of-script
    /// hooks (`EXIT` trap, `TRAPEXIT`, `zshexit` + `zshexit_functions`) the
    /// script pipeline owes them.
    fn run_chunk_with_exit_hooks(
        &mut self,
        chunk: fusevm::Chunk,
        label: &str,
    ) -> Result<i32, String> {
        let status = self.run_chunk(chunk, label)?;
        self.fire_script_exit_hooks(status)
    }

    /// The end-of-script hooks alone (`EXIT` trap, `TRAPEXIT`, `zshexit` +
    /// `zshexit_functions`), for a script that already ran; `status` is the
    /// script's `$?` and is what the call returns.
    fn fire_script_exit_hooks(&mut self, status: i32) -> Result<i32, String> {
        // Fire EXIT trap if set. Two storage paths:
        //   (a) `trap 'cmd' EXIT` writes the body text into
        //       `traps_table` via bin_trap (Src/builtin.c) — fire
        //       directly via execute_script.
        //   (b) `TRAPEXIT() { ... }` function-named form goes
        //       through settrap(SIGEXIT, None, ZSIG_FUNC) at
        //       funcdef time (fusevm_bridge.rs BUILTIN_REGISTER_COMPILED_FN
        //       arm) and lives in shfunctab + sigtrapped — fire
        //       via dotrap(SIGEXIT) which dispatches the named
        //       shfunc. Bug #157 in docs/BUGS.md.
        // Remove the trap from `traps_table` first to prevent
        // infinite recursion of `(a)`; `(b)`'s sigtrapped flag
        // is cleared by dotrap's own intrap guard.
        let exit_body = crate::ported::builtin::traps_table()
            .lock()
            .ok()
            .and_then(|mut t| t.remove("EXIT"));
        if let Some(action) = exit_body {
            tracing::debug!("firing EXIT trap (new pipeline)");
            // c:Src/signals.c — the EXIT trap body sees $? at the
            // value the script left off (so `trap 'echo $?' EXIT;
            // (exit 7)` prints 7), but the SHELL's final exit code
            // is still the pre-trap value (running `echo` inside
            // the trap doesn't reset the script's exit status).
            // Preserve `status` and re-apply it after the trap
            // body returns.
            //
            // c:Src/signals.c:1123/1236 — `intrap++` … `intrap--` bracket a
            // trap body, and while intrap the EXIT, DEBUG and ZERR traps are
            // suppressed (c:1112-1119, the guard in dotrap). This path runs
            // the EXIT body through the script pipeline rather than dotrap,
            // so nothing raised intrap and the body's own failure re-entered
            // the ERR trap: `trap 'print err' ERR; trap 'true; false' EXIT`
            // printed err where zsh prints nothing.
            //
            // A counter, not a flag, and paired with dotrap's SELECTIVE
            // guard: signals zsh does deliver from inside a trap body (e.g.
            // `trap 'kill -USR1 $$' EXIT`) must still dispatch.
            crate::ported::signals::intrap.fetch_add(1, Ordering::SeqCst); // c:1123
            // c:Src/signals.c:1170 — `execode((Eprog)sigfn, 1, 0, "trap")`:
            // the EXIT body sees "trap" in zsh_eval_context (c:Src/exec.c:1251).
            let trap_ctx = crate::ported::exec::EvalContextFrame::push("trap");
            let _ = self.execute_script_zsh_pipeline(&action);
            drop(trap_ctx);
            crate::ported::signals::intrap.fetch_sub(1, Ordering::SeqCst); // c:1236
            self.set_last_status(status);
        }
        // c:Src/signals.c::dotrap(SIGEXIT) — fire TRAPEXIT() shfunc
        // if installed via the function-name path. The TRAPEXIT()
        // form goes through settrap(SIGEXIT, None, ZSIG_FUNC) at
        // funcdef time (sets sigtrapped[SIGEXIT] |= ZSIG_FUNC).
        // Dispatching from here AFTER run_chunk returns means we're
        // outside the VM context — dotrap can't safely re-enter
        // via dispatch_function_call (which uses with_executor).
        // Route through execute_script_zsh_pipeline which sets up
        // a fresh VM context — invoke the function by name.
        let trapped = crate::ported::signals::sigtrapped
            .lock()
            .ok()
            .and_then(|g| g.get(crate::signals_h::SIGEXIT as usize).copied())
            .unwrap_or(0);
        // c:Src/signals.c:1112-1119 — `if (intrap) { switch (sig) { case
        // SIGEXIT: … return; } }`, and c:Src/signals.c:892 `if (!intrap &&
        // …)` in endtrapscope. An EXIT trap never fires from inside another
        // trap body. This site is a Rust-only end-of-pipeline hook (every
        // `eval` / `source` / trap body runs its own pipeline and reaches
        // here), and it dispatches TRAPEXIT by NAME without going through
        // dotrap — so nothing consulted `intrap` and nothing cleared
        // sigtrapped. Once `endtrapscope` started restoring a saved
        // ZSIG_FUNC EXIT trap (the c:929-931 arm), the TRAPEXIT body's own
        // nested pipeline re-entered this hook with the flag still set and
        // recursed without bound:
        //   f() { eval 'TRAPEXIT() { echo T; }' }; f
        // The `intrap++ … intrap--` bracket is the same one the string-form
        // branch above already carries (c:1123 / c:1236).
        // c:Src/signals.c:744-752 — `sigtrapped[sig] |= (locallevel <<
        // ZSIG_SHIFT)`: a trap installed inside a function carries its
        // scope's locallevel, and `endtrapscope` (c:892-903/945-956) is what
        // fires THAT one, at the scope exit. Only an untagged (locallevel 0)
        // EXIT trap belongs to the shell-exit path this hook stands in for.
        // Without the test, `f() { TRAPEXIT() { echo T } }; f` fired twice —
        // once from f's endtrapscope and once more from the pipeline hook.
        let exit_trap_locallevel = trapped >> crate::ported::zsh_h::ZSIG_SHIFT;
        if (trapped & crate::ported::zsh_h::ZSIG_FUNC as i32) != 0
            && exit_trap_locallevel == 0
            && crate::ported::signals::intrap.load(Ordering::SeqCst) == 0
        {
            // The TRAP<SIG> function is stored in shfunctab as
            // "TRAPEXIT"; calling it by name re-enters
            // execute_script_zsh_pipeline with a fresh VM context.
            crate::ported::signals::intrap.fetch_add(1, Ordering::SeqCst); // c:1123
            let _ = self.execute_script_zsh_pipeline("TRAPEXIT");
            crate::ported::signals::intrap.fetch_sub(1, Ordering::SeqCst); // c:1236
        }
        // c:Src/init.c::zexit — `callhookfunc("zshexit", NULL, 1, NULL)`.
        // Fire the `zshexit` shfunc + walk `zshexit_functions` array.
        // Routed through execute_script_zsh_pipeline calls because
        // we're outside the VM context here (post-run_chunk). Iterate
        // the array directly + call zshexit by name. Bug #215 in
        // docs/BUGS.md.
        //
        // Re-entry guard: each call to execute_script_zsh_pipeline
        // (whether top-level script or the named-fn dispatch below)
        // hits this code at its tail. Without a guard, the zshexit
        // hook recurses infinitely (calls itself at end via this
        // path). Use a thread-local depth counter and skip the
        // dispatch when depth > 0.
        thread_local! {
            static ZSHEXIT_HOOK_DEPTH: std::cell::Cell<u32> = const {
                std::cell::Cell::new(0)
            };
        }
        let hook_depth = ZSHEXIT_HOOK_DEPTH.with(|c| c.get());
        if hook_depth == 0 {
            ZSHEXIT_HOOK_DEPTH.with(|c| c.set(hook_depth + 1));
            if crate::ported::hashtable::shfunctab_lock()
                .read()
                .ok()
                .map(|t| t.contains_key("zshexit"))
                .unwrap_or(false)
            {
                let _ = self.execute_script_zsh_pipeline("zshexit");
            }
            let exit_arr = crate::ported::params::paramtab()
                .read()
                .ok()
                .and_then(|t| t.get("zshexit_functions").and_then(|p| p.u_arr.clone()))
                .unwrap_or_default();
            for fn_name in exit_arr {
                let exists = crate::ported::hashtable::shfunctab_lock()
                    .read()
                    .ok()
                    .map(|t| t.contains_key(&fn_name))
                    .unwrap_or(false);
                if exists {
                    let _ = self.execute_script_zsh_pipeline(&fn_name);
                }
            }
            ZSHEXIT_HOOK_DEPTH.with(|c| c.set(hook_depth));
        }
        // Preserve script status; trap body shouldn't override it.
        self.set_last_status(status);

        let _ = status;
        Ok(self.last_status())
    }
    /// zshrs's script entry: lex + parse + compile + run, then the
    /// end-of-script hooks. `eval`, `source`, trap bodies and autoload
    /// registration all funnel through here.
    pub fn execute_script_zsh_pipeline(&mut self, script: &str) -> Result<i32, String> {
        let chunk = self.compile_script_isolated(script)?;
        self.run_chunk_with_exit_hooks(chunk, "execute_script_zsh_pipeline")
    }

    /// Run a source string the way C's `execstring` does (c:Src/exec.c:1228
    /// → `execode`, c:1245): parse, execute, return the status. No `EXIT`
    /// trap, `TRAPEXIT` or `zshexit` hook runs here. In C those belong to
    /// `zexit` (c:Src/builtin.c:6037-6043) and to the end of a function's
    /// trap scope (`endtrapscope`, c:Src/signals.c:880), never to the end of
    /// an `eval`, a trap body or a `sched` command. Firing them there ran a
    /// script's EXIT trap in the middle of the script:
    /// `trap 'print T' EXIT; eval :; print after` printed T before `after`.
    pub fn execute_string_without_exit_hooks(&mut self, script: &str) -> Result<i32, String> {
        let chunk = self.compile_script_isolated(script)?;
        self.run_chunk(chunk, "execstring")
    }

    /// `execode(parse_string(cmdarg, 0), 1, 0, "cmdsubst")` — a nofork
    /// substitution body (c:Src/subst.c:2044-2046) parsed from the running
    /// line, so its statements carry the outer line numbers and leave
    /// `lineno` on them, as C's do.
    pub fn execute_string_at_lineno(&mut self, script: &str, lineno: u64) -> Result<i32, String> {
        let chunk = self.compile_script_isolated_at(script, Some(lineno))?;
        self.run_chunk(chunk, "execstring")
    }

    /// Run the TEXT that `getpermtext` reconstructed from an already-compiled
    /// `.zwc` program.
    ///
    /// c:Src/init.c:1618-1622 — the compiled arm of `source()` is
    /// `execode(prog, 1, 0, "filecode")`. The wordcode runs as it stands and
    /// NOTHING is lexed; a `.zwc` is quote-resolved once, at `zcompile` time.
    ///
    /// !!! WARNING: RUST-ONLY HELPER !!!
    /// zshrs has no execute-the-wordcode path — it deparses the program back
    /// to source (`getpermtext`) and lexes it again — so the round trip is
    /// lossless only while the lexer reads quotes the way the deparse writes
    /// them. `untokenize` (c:Src/exec.c:2134) renders EVERY quote null through
    /// `ztokens[Snull - Pound]`, and that entry is a bare single quote
    /// (c:Src/lex.c:38), so a closing null followed by an opening one comes
    /// back out as two adjacent quotes. Under RCQUOTES the lexer reads that
    /// pair inside a quoted word as one LITERAL quote (c:Src/lex.c:1328)
    /// instead of as two delimiters, so the openshift-aliases plugin's
    /// `alias opodr='oc …=''{…}'''` — which `zcompile` resolved with no
    /// literal quotes at all — re-lexed with two of them. The deparse
    /// spelling is by construction the DEFAULT-option spelling, so the option
    /// is cleared for the compile to restore C's "not lexed at all" property.
    ///
    /// It is cleared for the COMPILE ONLY. A `.zwc` that does `setopt
    /// rcquotes` (zsh-expand's plugin entry does, at its line 39) must still
    /// set the option for real, and that setting must outlive the source — so
    /// the previous value is restored before the chunk RUNS, not after. The
    /// same split applies to alias expansion: a function or `eval` body the
    /// program runs is lexed at RUNTIME and must see the live alias table.
    pub fn execute_zwc_program(&mut self, script: &str) -> Result<i32, String> {
        let chunk = {
            let _relex = ZwcRelexGuard::enter();
            self.compile_script_isolated(script)
        };
        self.run_chunk_with_exit_hooks(chunk?, "execute_zwc_program")
    }

    /// Run `script` the way C runs a PLAIN sourced file: parse ONE event,
    /// execute it, parse the next — so lexer-time state that one line
    /// establishes is in force when the next line is lexed.
    ///
    /// c:Src/init.c:1618-1641 — `source()` has two arms. A file that was
    /// already compiled (`try_source_file` found a `.zwc`) runs whole, as one
    /// program: `execode(prog, 1, 0, "filecode")` (c:1621). A plain file runs
    /// through the per-command loop: `/* loop through the file to be sourced
    /// */ switch (loop(0, 0))` (c:1626-1627), whose body is `lexinit();
    /// parse_event(ENDINPUT); … execode(prog, 0, 0, "file")` (c:155-220).
    /// This is the second arm.
    ///
    /// The difference is observable whenever a line changes something the
    /// LEXER consults, because a whole-file compile lexes every line with the
    /// state the file STARTED with:
    ///
    /// ```text
    /// alias greet='print -r -- hello'   # takes effect at execution time
    /// greet                             # …but this line is lexed after it
    /// ```
    ///
    /// Same for `setopt rcquotes` (c:Src/lex.c:1326), `unsetopt aliases`, and
    /// a syntax error late in the file (C has already run the good lines).
    ///
    /// **Re-entrancy.** Every nested context — `$(source f)`, `` `source f` ``,
    /// `eval "source f"`, a pipe stage, a `( … )` subshell, a `source` inside
    /// a sourced file — reaches here through the normal builtin path, so this
    /// must be safe to enter while an outer instance of itself is parked
    /// mid-file. Two properties make it so, and both are deliberate:
    ///
    ///   * It never touches the shell's INPUT STACK. C's `source` points
    ///     `SHIN` at the file (c:1584) and lets `loop`'s `ingetc` pull from
    ///     it; doing that here would fight the outer reader for the one
    ///     global. Instead the file body is installed as the lexer's own
    ///     `LEX_INPUT` window under `strinbeg` — the exact parking
    ///     [`parse_isolated`] uses for a command-substitution body — and the
    ///     outer window is saved on the Rust stack and restored on the way
    ///     out. Nesting is then just stack discipline.
    ///   * It never dispatches through `execode`. `execode`
    ///     (`src/ported/exec.rs`) runs its program on the installed SESSION
    ///     executor, which is the right one only for the top-level REPL; from
    ///     inside a command substitution the live executor is the sub-VM that
    ///     owns the capture. Each event is compiled and run here on `self` —
    ///     the same executor `execute_script` would have used — via
    ///     [`Self::run_chunk`]. `$(source f)` therefore captures exactly what
    ///     `$(…)` captures from any other builtin.
    ///
    /// Returns the file's `$?`. `Err` only for a VM error, as
    /// [`Self::run_chunk`] reports it.
    pub fn execute_script_per_command(&mut self, script: &str) -> Result<i32, String> {
        // c:Src/init.c:1626-1627 — source() runs `loop(0, 0)`: not toplevel.
        self.run_events_per_command(script, None, false)
    }

    /// The `loop()` body shared by a sourced file and a script file.
    ///
    /// `events`, when given, receives every executed event's lists, and is
    /// CLEARED unless the loop drained the input to a clean `ENDINPUT` — so a
    /// caller holding a non-empty collection after the call has the exact
    /// program the lexer produced, one event at a time, for the whole file.
    ///
    /// `toplevel` is loop()'s parameter of the same name: true only for the
    /// script file zsh_main runs (c:Src/init.c:1963 `loop(1, 0)`), false for
    /// `source` / `.` (c:1626-1627 `loop(0, 0)`). It gates the preexec hook
    /// (c:180).
    fn run_events_per_command(
        &mut self,
        script: &str,
        mut events: Option<&mut Vec<crate::parse::ZshList>>,
        toplevel: bool,
    ) -> Result<i32, String> {
        use crate::ported::lex::{
            tok, ENDINPUT, LEXERR, LEX_FILE_WINDOW_STRIN, LEX_INPUT, LEX_LINENO, LEX_POS,
            LEX_UNGET_BUF,
        };

        // Inline Rust FFI blocks are rewritten before the lexer sees them,
        // as on every other source-string entry (see `parse_isolated`).
        let ffi_desugared = script
            .contains("rust")
            .then(|| crate::rust_ffi::desugar(script));
        let script: &str = ffi_desugared.as_deref().unwrap_or(script);

        // c:Src/init.c:121 — `if (!toplevel) zcontext_save();`, plus the
        // zshrs-only lexer window that `zcontext` doesn't cover (identical
        // list to `parse_isolated`, which parks it for the same reason).
        crate::ported::context::zcontext_save(); // c:121
        let saved_input = LEX_INPUT.with_borrow(|s| s.clone());
        let saved_pos = LEX_POS.get();
        let saved_unget = LEX_UNGET_BUF.with_borrow(|b| b.clone());
        let saved_lineno = LEX_LINENO.get();
        let saved_in_lexstop = crate::ported::input::lexstop.with(|c| c.get());
        let saved_file_window = LEX_FILE_WINDOW_STRIN.get();

        // `strin` makes a drained window report EOF instead of falling
        // through to `inputline()` and STEALING the outer reader's next line
        // (input.rs:391). Without it a sourced file's last event swallows the
        // caller's next stdin line.
        crate::ported::hist::strinbeg(0);
        // c:1588 — `lineno = 1;`. `lex_init` (called by `parse_init`)
        // installs the body as the window and resets the line counter.
        crate::ported::parse::parse_init(script);
        // C reads this file through `inputline` (c:Src/input.c:366) with
        // `strin == 0`: ONE LINE per buffer, which is what makes each line
        // its own event (c:Src/lex.c:310 / c:Src/parse.c:657), and every
        // newline counted (c:Src/input.c:330). zshrs installs the body as
        // one window under one `strinbeg`, so the file kind is declared
        // here, tagged with THIS strinbeg's depth — a nested string push
        // inside the file is deeper and stays a string.
        LEX_FILE_WINDOW_STRIN.set(crate::ported::input::strin.with(|s| s.get()));

        // c:116 — `int err, non_empty = 0;`
        let mut non_empty = false;
        let mut vm_error: Option<String> = None;
        let mut drained = false;

        loop {
            // c:155 — `lexinit();` Resets `tok` and BOTH `lexstop` copies;
            // it does NOT move the window, so the next event resumes where
            // the last one stopped.
            crate::ported::lex::lexinit(); // c:155
            // Event source for preexec's `$2`/`$3` — see run_preexec_hook.
            let event_mark = toplevel.then(crate::funcdef_capture::body_mark_begin);
            let prog = crate::ported::parse::parse_event(ENDINPUT); // c:156
            let event_src = event_mark.and_then(crate::funcdef_capture::event_text);
            let Some(prog) = prog else {
                // c:159-174 — no event this pass. Break on clean EOF or on a
                // parse error (`!toplevel` makes C's LEXERR arm
                // unconditional here); a bare separator just goes round
                // again, which is C's `continue` at c:174.
                let tok_v = tok(); // c:159
                let errflag_v = errflag.load(Ordering::Relaxed);
                if (tok_v == ENDINPUT && errflag_v == 0) || tok_v == LEXERR {
                    // c:159-162
                    drained = tok_v == ENDINPUT;
                    if tok_v == LEXERR
                        && crate::ported::builtin::LASTVAL.load(Ordering::Relaxed) == 0
                    {
                        crate::ported::builtin::LASTVAL.store(1, Ordering::Relaxed); // c:173
                    }
                    break;
                }
                if tok_v == ENDINPUT || errflag_v != 0 {
                    // Drained (or aborted) with a flag set — nothing left to
                    // read, so looping again would spin.
                    break;
                }
                continue; // c:174
            };
            non_empty = true; // c:179
            if toplevel {
                // callhookfunc dispatches through the live executor, which
                // is only installed while a chunk runs (see run_chunk).
                let _ctx = ExecutorContext::enter(self);
                run_preexec_hook(event_src.as_deref()); // c:180-215
            }

            // c:220 — `execode(prog, 0, 0, "file")`. The eval-context entry
            // C's `execode` pushes for this arm is already on the stack:
            // `bin_dot` pushes it once around the whole file (builtin.rs), so
            // pushing it per event would report `file:file:file:…`.
            //
            // `LEX_LINENO` is saved across execution for the same reason
            // `loop()` does it (init.rs, c:Src/exec.c:1376/1640): each
            // statement's `SET_LINENO` overwrites the counter while it runs,
            // and the NEXT event must be lexed from the line the file is
            // really on.
            let chunk = crate::compile_zsh::ZshCompiler::new().compile(&prog);
            let saved_lex_lineno = LEX_LINENO.get();
            let run = self.run_chunk(chunk, "source");
            LEX_LINENO.set(saved_lex_lineno);
            if let Some(ev) = events.as_deref_mut() {
                ev.extend(prog.lists);
            }
            if let Err(e) = run {
                vm_error = Some(e);
                break;
            }

            // c:234 — `if (((!interact || sourcelevel) && errflag) || retflag)
            // break;`. A sourced file always runs with `sourcelevel` bumped
            // (bin_dot, c:1606), so the errflag half is unconditional here.
            if (errflag.load(Ordering::Relaxed) & ERRFLAG_ERROR) != 0
                || crate::ported::builtin::RETFLAG.load(Ordering::Relaxed) != 0
            {
                // c:Src/init.c:1960-1968 — after loop(1,0) breaks on a
                // runtime error, zsh_main re-enters it unless
                // `errflag && !interact && !isset(CONTINUEONERROR)`; the
                // re-entered loop's hbegin clears ERRFLAG_ERROR
                // (c:Src/hist.c:1115) before the next event. Only the script
                // file (toplevel) has that outer loop: `source` breaks
                // (c:234 `sourcelevel`), and a parse error never gets here
                // (the LEXERR arm above breaks first).
                if toplevel
                    && crate::ported::builtin::RETFLAG.load(Ordering::Relaxed) == 0
                    && crate::ported::builtin::EXIT_PENDING.load(Ordering::Relaxed) == 0
                    && !crate::ported::zsh_h::isset(crate::ported::zsh_h::INTERACTIVE)
                    && crate::ported::zsh_h::isset(crate::ported::zsh_h::CONTINUEONERROR)
                {
                    errflag.fetch_and(!ERRFLAG_ERROR, Ordering::Relaxed); // c:Src/hist.c:1115
                    continue;
                }
                break; // c:235
            }
            // C's `exit` inside a sourced file calls `zexit` → `realexit()`
            // and the process is gone, so C never reaches the next event.
            // zshrs defers the exit (EXIT_PENDING plus a jump to chunk end)
            // and lets the caller unwind, so the loop has to stop on its own.
            if crate::ported::builtin::EXIT_PENDING.load(Ordering::Relaxed) != 0 {
                break;
            }
        }

        // c:245 — `err = errflag;` is read BEFORE the context is restored,
        // because `zcontext_restore` → `parse_context_restore` ends with
        // `errflag &= ~ERRFLAG_ERROR` (c:Src/parse.c:354). C carries the
        // answer out as the `LOOP_ERROR` return value; zshrs's `bin_dot`
        // reads the flag itself (its c:1623-1624 + c:1663 block), so the bit
        // is put back after the restore instead.
        let err = (errflag.load(Ordering::Relaxed) & ERRFLAG_ERROR) != 0; // c:245
        if let Some(ev) = events {
            if !drained || err || vm_error.is_some() {
                ev.clear();
            }
        }

        // c:246-249 — leave the loop's context exactly as it was found.
        crate::ported::hist::strinend();
        LEX_INPUT.with_borrow_mut(|s| *s = saved_input);
        LEX_POS.set(saved_pos);
        LEX_UNGET_BUF.with_borrow_mut(|b| *b = saved_unget);
        LEX_LINENO.set(saved_lineno);
        crate::ported::input::lexstop.with(|c| c.set(saved_in_lexstop));
        LEX_FILE_WINDOW_STRIN.set(saved_file_window);
        crate::ported::context::zcontext_restore(); // c:247
        if err {
            errflag.fetch_or(ERRFLAG_ERROR, Ordering::Relaxed); // see the c:245 note
        }

        if let Some(e) = vm_error {
            return Err(e);
        }
        // c:1633-1636 — `case LOOP_EMPTY: /* Empty code resets status */
        // lastval = 0;`. `source /dev/null` (or a comments-only file) clears
        // `$?` rather than leaving the caller's.
        if !non_empty {
            self.set_last_status(0); // c:1635
        }
        Ok(self.last_status())
    }

    /// Install an autoloaded function by running its definition program,
    /// reusing the rkyv-cached chunk when the cache can PROVE the chunk
    /// was compiled from this same definition text by this same binary.
    ///
    /// `registered` is what `autoload_register_source` produced: either
    /// `name() { <file body> }` or, for a file that already contains the
    /// definition, the body verbatim. Running it installs the function;
    /// the compiled chunk for it is exactly what the cache stores, so a hit
    /// skips lex+parse+compile of the whole file. For `_git` that is 424 KB
    /// of shell — the dominant cost of the first `git <tab>`.
    ///
    /// Two conditions gate caching, because outside them the chunk is not a
    /// function of the definition text alone:
    ///   * ksh-style autoload (`KSHAUTOLOAD` / `PM_KSHSTORED`) runs the file
    ///     at top level instead of wrapping it, so the same bytes produce a
    ///     different program depending on a runtime option;
    ///   * without `PM_UNALIASED` (`autoload` without `-U`) the body is
    ///     parsed WITH alias expansion, so the chunk depends on the alias
    ///     table too. Every compsys / plugin autoload uses `-Uz`.
    ///
    /// A hit that runs without defining `name` is treated as a corrupt
    /// entry, not as a failed load: the entry is dropped and the real
    /// source compiled. Installing a function is the one thing this
    /// function exists to do, so "it ran and the function is not there"
    /// is a fact the loader can check for itself rather than leaving the
    /// caller to report `function not defined by file` for what is
    /// actually a bad cache line.
    ///
    /// `from_wordcode` says the text is a `.zwc` deparse rather than file
    /// bytes. C never re-lexes such a body at all — `shf->funcdef =
    /// stripkshdef(prog, …)` (c:Src/exec.c:5753-5755) installs the dump's own
    /// wordcode and the ksh arm runs it with `execode(prog, 1, 0,
    /// "evalautofunc")` (c:5795) — so the compile here, which is zshrs's
    /// stand-in for that install, runs under [`ZwcRelexGuard`]. The guard
    /// covers the COMPILE only: a ksh-style body executes real user code, and
    /// an `eval` or function body IT reaches is lexed at runtime against the
    /// live alias table and the live RCQUOTES, exactly as in C.
    fn run_autoload_definition(
        &mut self,
        name: &str,
        registered: &str,
        ksh_style: bool,
        from_wordcode: bool,
        parse_failed: bool,
    ) -> Result<i32, String> {
        let unaliased = crate::ported::utils::getshfunc(name)
            .map(|f| (f.node.flags as u32 & crate::ported::zsh_h::PM_UNALIASED) != 0)
            .unwrap_or(false);
        let key = if ksh_style || !unaliased {
            None
        } else {
            autoload_source_key(name, registered, from_wordcode)
        };
        if let Some((dir, sha)) = key.as_ref() {
            if let Some(blob) = crate::autoload_cache::try_load_for_source(name, dir, sha) {
                match bincode::deserialize::<fusevm::Chunk>(&blob) {
                    Ok(chunk) if !chunk.ops.is_empty() => {
                        tracing::debug!(
                            name,
                            ops = chunk.ops.len(),
                            "autoload: rkyv chunk hit, skipping parse+compile"
                        );
                        let status = self.run_chunk(chunk, "autoload:cached");
                        if self.functions_compiled.contains_key(name) {
                            return status;
                        }
                        // The chunk ran and `name` is still undefined, so
                        // it is not this function's definition program
                        // whatever the key said. Drop it and fall through
                        // to a real compile — a wrong answer here costs
                        // every completion on the shell.
                        tracing::warn!(
                            name,
                            "autoload: cached chunk did not define the function; \
                             dropping the entry and recompiling"
                        );
                        crate::autoload_cache::try_remove(name);
                    }
                    _ => {}
                }
            }
        }
        let chunk = {
            // c:Src/exec.c:5753-5755 / c:5795 — the dump's wordcode is
            // installed/executed as it stands, so nothing about the live
            // option or alias state can reach it. zshrs lexes the deparse
            // instead; pin the lexer to the spelling the deparse was written
            // in for the duration of that compile, and only that compile.
            let _relex = from_wordcode.then(ZwcRelexGuard::enter);
            // c:Src/exec.c:6264-6266 / c:5726 — C parses the file ONCE and a
            // failure ends the load (`return NULL`), so exactly one diagnostic
            // reaches the terminal. zshrs parsed the raw body in
            // `autoload_definition_source` and parses the WRAPPED text again
            // here, so a body zsh rejects printed the error twice — the second
            // time shifted one line by the wrap's leading `name() {`. The
            // first pass already reported it against the loadee's name; mute
            // this one. `noerrs` still sets ERRFLAG_ERROR (c:Src/utils.c:175),
            // which is what `compile_script_isolated` reads, so the load still
            // fails.
            let _muted = parse_failed.then(ZerrMute::enter);
            self.compile_script_isolated(registered)?
        };
        if let Some((dir, sha)) = key.as_ref() {
            match bincode::serialize(&chunk) {
                Ok(blob) => {
                    if let Err(e) = crate::autoload_cache::try_save_one(name, &blob, dir, *sha) {
                        tracing::warn!(name, error = %e, "autoload: rkyv chunk save failed");
                    }
                }
                Err(e) => tracing::warn!(name, error = %e, "autoload: chunk serialize failed"),
            }
        }
        // c:Src/exec.c:5807-5816 — installing the definition is a funcdef
        // store (`execode(…, "evalautofunc")` for ksh style); nothing on that
        // path reaches the shell-exit hooks. Running the definition through
        // `run_chunk_with_exit_hooks` fired the EXIT trap, `TRAPEXIT` and
        // `zshexit` on the first call of EVERY autoloaded function (and
        // consumed a string EXIT trap so it never ran at exit): `trap 'echo T'
        // EXIT; autoload -Uz is-at-least; is-at-least 1.0` printed T first.
        self.run_chunk(chunk, "autoload:compiled")
    }

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

    /// Run `script` with stdout AND stderr captured, returning `(exit status,
    /// output)` — the entry point for an embedder that owns the terminal (a
    /// TUI), where a stray `echo` corrupts the display.
    ///
    /// A shell cannot capture its output into an in-process buffer the way a
    /// single-runtime language can: a forked child writes fd 1 directly and
    /// knows nothing about the parent's buffers. The capture is therefore at fd
    /// level, and it differs from `$(…)` in the one way that matters to an
    /// embedder: [`Self::run_command_substitution`] runs on a sub-VM, as a
    /// subshell must, so a variable it sets is gone afterwards. This runs the
    /// script on THIS VM, so state persists across captured runs exactly as it
    /// does across ordinary [`Self::execute_script`] calls.
    ///
    /// The saved fds go through `movefd` to land at fd >= 10 and marked
    /// `FDT_INTERNAL`, per zsh's invariant that shell-internal fds never live
    /// below 10 — otherwise a script doing `exec 9>&-` closes the capture's own
    /// bookkeeping. A temp file, not a pipe, receives the output: with no
    /// concurrent reader, a pipe deadlocks the moment a script writes past the
    /// 64 KiB buffer.
    ///
    /// # Concurrency contract
    ///
    /// **While a capture is in flight, no other thread in the process may write
    /// fd 1 or fd 2.** POSIX has no per-thread fd table, so pointing fd 1 at the
    /// capture points it there for every thread at once; any byte another thread
    /// writes during the window lands in the returned `String` instead of on the
    /// terminal. The `CAPTURE_LOCK` below excludes a second *capture*, which is
    /// all a lock can do — a thread that never calls this function (a logger, a
    /// progress meter, a test harness's own reporter) is not excluded by
    /// anything, and its output is silently absorbed.
    ///
    /// This is not a gap that a different capture mechanism closes. C zsh dodges
    /// it for `$(…)` by forking: `getoutput` (`Src/exec.c:4816`) calls `zfork`
    /// and only the child does `redup(pipes[1], 1)` (`Src/exec.c:4837`), so the
    /// parent's fd 1 is never touched — but the child then runs `entersubsh`
    /// (`Src/exec.c:4838`) and a variable it sets is gone. Forking here would
    /// throw away the one property this call exists to provide (state persists
    /// on THIS VM across captured runs), so the cost is paid as a contract
    /// instead: **capture from one thread, and quiesce the rest.**
    pub fn execute_script_captured(&mut self, script: &str) -> (i32, String) {
        use std::io::{Read, Seek, SeekFrom};
        use std::os::unix::io::AsRawFd;

        /// Serializes the redirect/restore window. fd 1 belongs to the process,
        /// not to a `ShellExecutor`, so two threads capturing at once would
        /// restore each other's fds mid-run and each would read back an empty
        /// file. An embedder that evaluates on one thread never contends here.
        /// It excludes another *capture* and nothing else: see the concurrency
        /// contract on this function for what remains the caller's problem.
        static CAPTURE_LOCK: std::sync::Mutex<()> = std::sync::Mutex::new(());
        let _guard = CAPTURE_LOCK.lock().unwrap_or_else(|e| e.into_inner());

        let Ok(mut tmp) = tempfile::tempfile() else {
            // No temp file, no capture: run it anyway rather than silently
            // dropping the script, and report nothing captured.
            let status = self.execute_script(script).unwrap_or(1);
            return (status, String::new());
        };

        // Flush Rust's buffered stdout against the REAL fd 1 before the swap,
        // or bytes written before this call drain into the capture instead
        // (the same ordering bug `run_command_substitution` documents).
        let _ = io::stdout().flush();

        /// Puts fds 1 and 2 back on the way out, including when the run
        /// unwinds. A panic anywhere under `execute_script` would otherwise
        /// leave the whole PROCESS writing into a temp file that is already
        /// unlinked — every later write vanishes, starting with the one
        /// reporting the panic, which turns a localized bug into a silent one.
        struct RestoreFds {
            saved_out: i32,
            saved_err: i32,
        }
        impl Drop for RestoreFds {
            fn drop(&mut self) {
                let _ = io::stdout().flush();
                unsafe {
                    libc::dup2(self.saved_out, libc::STDOUT_FILENO);
                    libc::dup2(self.saved_err, libc::STDERR_FILENO);
                }
                crate::ported::utils::zclose(self.saved_out);
                crate::ported::utils::zclose(self.saved_err);
            }
        }

        let saved_out = crate::ported::utils::movefd(unsafe { libc::dup(libc::STDOUT_FILENO) });
        let saved_err = crate::ported::utils::movefd(unsafe { libc::dup(libc::STDERR_FILENO) });
        unsafe {
            libc::dup2(tmp.as_raw_fd(), libc::STDOUT_FILENO);
            libc::dup2(tmp.as_raw_fd(), libc::STDERR_FILENO);
        }
        let restore = RestoreFds {
            saved_out,
            saved_err,
        };

        let status = self.execute_script(script);

        // Explicit, not end-of-scope: the temp file must be read back only
        // after the real fds are restored, or a diagnostic emitted while
        // reading would land in the very buffer being read.
        drop(restore);

        let mut output = String::new();
        let _ = tmp.seek(SeekFrom::Start(0));
        let mut bytes = Vec::new();
        if tmp.read_to_end(&mut bytes).is_ok() {
            // Lossless for the same reason as the `$( cmd )` capture above:
            // a captured byte that is not valid UTF-8 is a byte the script
            // really wrote, not an encoding error to paper over.
            output = crate::script_bytes::decode_script_bytes(&bytes);
        }
        // Match `$(…)`: one trailing newline is an artifact of the last `echo`,
        // not part of the output.
        while output.ends_with('\n') {
            output.pop();
        }

        (status.unwrap_or_else(|_| self.last_status()), output)
    }

    /// Run an ALREADY-PARSED program (the back half of
    /// `execute_script_zsh_pipeline`): compile the `ZshProgram` to a
    /// fusevm Chunk and run it. Used by the ported `loop()` REPL
    /// (Src/init.c:220 `execode`), which parses via `parse_event` and
    /// hands the program here through the `execute_program` exec hook.
    /// Returns the resulting `$?` (1 on a compile/run error).
    pub fn execute_program(&mut self, program: &crate::parse::ZshProgram) -> i32 {
        let chunk = crate::compile_zsh::ZshCompiler::new().compile(program);
        match self.run_chunk(chunk, "loop") {
            Ok(status) => status,
            Err(_) => 1,
        }
    }

    /// 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)
    }

    /// 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. Thin passthru — autoload-materialize
    /// the body if needed, build a synthetic `shfunc`, and hand off to
    /// the canonical `doshfunc` port (`Src/exec.c:5823` →
    /// `src/ported/exec.rs::doshfunc`). doshfunc owns ALL scope
    /// management (starttrapscope/endtrapscope, startparamscope/
    /// endparamscope, funcdepth bump, pipestats save/restore, scriptname
    /// snapshot, BREAKS/CONTFLAG/LOOPS/RETFLAG snapshot+restore, `$0`
    /// override via FUNCTIONARGZERO, etc.). The body run itself is the
    /// Rust-only adaptation passed via the `body_runner` closure because
    /// zshrs runs function bodies through fusevm bytecode (not C zsh's
    /// wordcode walker via `runshfunc`).
    ///
    /// Returns `None` when the name isn't a known function so the caller
    /// can fall through to external dispatch.
    /// Body-only counterpart to [`dispatch_function_call`] — runs
    /// the function body WITHOUT wrapping in `doshfunc`. Used as the
    /// `body_runner` closure target by `src/ported/` callers that
    /// already wrap their own `crate::ported::exec::doshfunc(...)`
    /// call (so going back through `dispatch_function_call` would
    /// double-wrap the scope). Mirrors C's `runshfunc(prog, wrappers,
    /// name)` at `exec.c:6042` from doshfunc's perspective.
    pub fn run_function_body_only(&mut self, name: &str, args: &[String]) -> Option<i32> {
        // Held for the WHOLE call, not just the load: an autoloaded function is
        // registered TWICE — once when its file's text defines it, and again
        // (unchanged) when its chunk is compiled at call time — and the second
        // stamp would otherwise relabel it with the caller's scriptfilename.
        // See the AUTOLOAD_DEF_FILE consumer in fusevm_bridge.
        let mut _autoload_file_guard: Option<AutoloadFileGuard> = None;
        // Same Rust-port short-circuit as dispatch_function_call,
        // sans the doshfunc wrap.
        //
        // c:Src/exec.c:3760-3763 — `if (errflag) { lastval = 1; goto err; }`,
        // the gate execcmd_exec applies AFTER argument expansion and BEFORE it
        // invokes anything. A shell function whose argument list raised errflag
        // (`_describe -t t "${(j:,:)${(s: :)x y z}}" d` — a bad substitution)
        // is therefore never entered. zshrs's ordinary function path honours
        // that, but the compsys router short-circuits above it, so a NATIVE
        // PORT ran where the stock shell function did not and the completion
        // listed matches zsh never offered. Gate the short-circuit on the same
        // condition; the ordinary path below is left alone, since it already
        // aborts upstream.
        if (errflag.load(Ordering::Relaxed) & ERRFLAG_ERROR) != 0 {
            crate::ported::builtin::LASTVAL.store(1, Ordering::Relaxed); // c:3761
            return Some(1); // c:3762 goto err
        }
        if let Some(rc) = crate::compsys::router::dispatch_compsys(name, args) {
            // Plugin override (ABI v4) wins over the built-in Rust port.
            return Some(rc);
        }
        // Bug #657 gap #2 — `_regex_arguments`-generated completion functions
        // live in a runtime registry, not the static router table (a plain
        // `fn` ptr can't carry the dynamic name). Consult that registry here
        // so `compdef mycmd` → `_comps[cmd]=mycmd` → this call routes to the
        // compiled regex state machine.
        if let Some(rc) = crate::compsys::ported::_regex_arguments::dispatch_if_registered(name) {
            return Some(rc);
        }
        // c:Src/exec.c:5626 — see the twin site in
        // `dispatch_function_call`: a body loaded on THIS call runs one
        // `zsh_eval_context` frame deeper ("loadautofunc") than the
        // caller's "shfunc".
        let mut did_autoload = false;
        // Autoload prelude (same as dispatch_function_call's).
        if !self.functions_compiled.contains_key(name) {
            // On-demand $fpath autoload for `_`-prefixed compsys helpers that
            // compinit didn't register as autoload stubs — see the fuller
            // note in dispatch_function_call.
            if name.starts_with('_') && crate::ported::utils::getshfunc(name).is_none() {
                // c:6219 getfpfunc — gate the stub on the definition file
                // actually existing in $fpath, mirroring zsh's `compdef -na`
                // (only autoloads `_`-names present in fpath). Without this a
                // `_`-name with no file (e.g. a fasd completer trigger absent
                // from this fpath) got a phantom PM_UNDEFINED stub, and
                // loadautofn then leaked "function definition file not found"
                // to the terminal during completion. test_only=1 is a pure
                // probe; dump_out is preserved so .zwc-dump autoloads resolve.
                let mut _dir: Option<String> = None;
                let mut _dump = None;
                if crate::ported::exec::getfpfunc(name, &mut _dir, None, 1, &mut _dump).is_some() {
                    let _ = self.execute_script_zsh_pipeline(&format!("autoload -rUz -- {name}"));
                }
            }
            if let Some(stub) = crate::ported::utils::getshfunc(name) {
                // c:Src/exec.c:5684-5704 (loadautofn) —
                //     int noalias = noaliases;
                //     noaliases = (shf->node.flags & PM_UNALIASED);
                //     prog = getfpfunc(...);        /* parses the file */
                //     noaliases = noalias;
                // `autoload -U` records PM_UNALIASED (c:3354-3357), and its ONLY
                // effect is that the autoloaded body is PARSED with alias
                // expansion disabled. zshrs recorded the bit but never consulted
                // it, so a body calling `helper` picked up a caller-defined
                // `alias helper=...` — exactly what -U exists to prevent.
                let unaliased = (stub.node.flags as u32 & crate::ported::zsh_h::PM_UNALIASED) != 0;
                let noalias_save = crate::ported::lex::noaliases(); // c:5684
                crate::ported::lex::set_noaliases(unaliased); // c:5697
                let _restore_noaliases = NoAliasesRestore(noalias_save); // c:5704
                if (stub.node.flags as u32 & PM_UNDEFINED) != 0 {
                    did_autoload = true; // c:5626 — body runs as "loadautofunc"
                    let _sticky_load = AutoloadStickyGuard::enter(&stub);
                    let boxed = Box::new(stub.clone());
                    let ptr = Box::into_raw(boxed);
                    let load_rc = crate::ported::exec::loadautofn(ptr, 0, 0, 0);
                    unsafe {
                        let _ = Box::from_raw(ptr);
                    }
                    // c:Src/exec.c:5713-5719 — `if (prog == &dummy_eprog) {
                    //     zwarn("%s: function definition file not found",
                    //           shf->node.nam); … return NULL; }`, and
                    // c:5635-5644 execautofn: `if (!loadautofn(...)) return 1;`
                    // A failed load is TERMINAL: C has already replaced
                    // shf->funcdef with the mkautofn trampoline (c:3180), so
                    // nothing of the old stub body survives to be re-run.
                    // zshrs keeps the stub's TEXT on the shfunc node, and the
                    // `if let Some(body)` arm below would hand that text back
                    // to run_autoload_definition — re-executing the very
                    // `autoload -X` that triggered this load. `cod() {
                    // autoload -XUz }; cod` recursed until FUNCNEST and
                    // printed the diagnostic 500 times (C04funcdef:38,39,40).
                    if load_rc != 0 {
                        return Some(1); // c:5719 NULL → c:5644 `return 1`
                    }
                    // c:5657 — preserve the fpath dir + PM_LOADDIR across the
                    // funcdef re-register (which stamps filename="zsh"), so
                    // `whence -v` reports the source. See the twin site below.
                    let loaded_dir = crate::ported::utils::getshfunc(name)
                        .and_then(|f| f.filename)
                        .filter(|d| d != "zsh");
                    // c:Src/exec.c:5682-5760 — C loads the body IN PLACE on the
                    // existing Shfunc, so every stub flag except PM_UNDEFINED
                    // survives. See the twin site below for why PM_ABSPATH_USED
                    // in particular has to come back.
                    let abspath_used =
                        (stub.node.flags as u32 & crate::ported::zsh_h::PM_ABSPATH_USED) != 0;
                    let ksh_style = autoload_is_ksh_style(name); // c:5781 (pre-registration)
                    if let Some(body) = crate::ported::utils::getshfunc(name).and_then(|f| f.body) {
                        _autoload_file_guard = Some(AutoloadFileGuard::enter(name));
                        let AutoloadSource {
                            text: registered,
                            from_wordcode,
                            parse_failed,
                        } = autoload_register_source(name, &body);
                        {
                            // c:Src/exec.c:5735-5760 — C INSTALLS the parsed Eprog
                            // as the function body; it executes nothing at load
                            // time, so the global `lineno` still holds the line the
                            // CALL was made on when doshfunc records
                            // `funcsave->fstack.lineno = lineno` (c:6013). zshrs
                            // installs the body by RUNNING `name() { … }` through
                            // the pipeline, which walks the counter to the file's
                            // last line — so the very first call of an autoloaded
                            // function reported its caller's line as that instead:
                            // `$functrace` read `script.zsh:1` where zsh reads
                            // `script.zsh:4`, and inside completion `_subscript:0`
                            // where zsh reads `_subscript:125`. Every LATER call
                            // was already correct, because the load only happens
                            // once.
                            let caller_lineno = crate::ported::lex::lineno();
                            // c:5384-5388 assigns `shf->lineno` only when a
                            // `name() { … }` STATEMENT defines the function. An
                            // autoload stub's Shfunc keeps the 0 it was created
                            // with, and loadautofn replaces only `funcdef`, so zsh
                            // reports `funcsourcetrace` as `<file>:0`. Running a
                            // synthesized wrapper here stamps line 1 instead, so
                            // put the stub's value back when the wrapper was ours.
                            let synthesized = registered != body;
                            let _ = self.run_autoload_definition(
                                name,
                                &registered,
                                ksh_style,
                                from_wordcode,
                                parse_failed,
                            );
                            crate::ported::lex::set_lineno(caller_lineno);
                            if synthesized {
                                // c:5384-5388 sets `shf->lineno` only where a
                                // `name() { … }` STATEMENT defines the function; an
                                // autoload stub keeps the 0 it was created with and
                                // loadautofn replaces only `funcdef`, so
                                // `funcsourcetrace` reads `<file>:0`. Executing our
                                // synthesized wrapper records a line base of 1
                                // instead. -1 marks "autoload-installed" so the
                                // call-time clamp below can tell that apart from an
                                // INLINE `f() { … }`, whose base underflows to 0 but
                                // whose def line really is >= 1.
                                self.function_line_base.insert(name.to_string(), -1);
                            }
                        }
                    }
                    if let Some(dir) = loaded_dir.as_deref() {
                        restore_loaddir(name, dir, abspath_used, ksh_style);
                    }
                } else if let Some(body) = stub.body.clone() {
                    // c:Src/exec.c:5978 — the body runs under the stub's sticky
                    // emulation; see AutoloadStickyGuard.
                    let _sticky_load = AutoloadStickyGuard::enter(&stub);
                    // c:Src/builtin.c:3180 (eval_autoload) — `autoload +X NAME`
                    // loads the body EAGERLY through `loadautofn`, which sets
                    // `body` + `filename`/PM_LOADDIR and clears PM_UNDEFINED
                    // but leaves no compiled chunk behind. The first CALL of
                    // such a function therefore lands in THIS arm, never the
                    // PM_UNDEFINED arm above, so it needs the same
                    // post-registration restore — otherwise `autoload +X
                    // /abs/dir/NAME` lost the pair before the body ran and a
                    // sibling `autoload -Uz SIB` inside it failed with
                    // "function definition file not found" where zsh loads
                    // /abs/dir/SIB. `functions[name]=body` (parameter.c
                    // setpmfunction) reaches this arm too and simply has no
                    // PM_LOADDIR, so the restore is skipped for it.
                    let loaded_dir = ((stub.node.flags as u32 & crate::ported::zsh_h::PM_LOADDIR)
                        != 0)
                        .then(|| stub.filename.clone())
                        .flatten();
                    let abspath_used =
                        (stub.node.flags as u32 & crate::ported::zsh_h::PM_ABSPATH_USED) != 0;
                    // c:Src/Modules/parameter.c:295-315 — a body that arrived
                    // through `functions[NAME]=BODY` is NOT a file. See
                    // `body_came_from_param_assignment`.
                    let param_body = body_came_from_param_assignment(stub.node.flags);
                    let ksh_style = !param_body && autoload_is_ksh_style(name); // c:5781 (pre-registration)
                    _autoload_file_guard = Some(AutoloadFileGuard::enter(name));
                    // A `functions[name]=body` assignment is already a parsed
                    // body, so it takes no file parse and cannot have reported
                    // one (`parse_failed` is false by construction).
                    let (registered, from_wordcode, parse_failed) = if param_body {
                        (param_definition_source(name, &body), false, false)
                    } else {
                        let AutoloadSource {
                            text,
                            from_wordcode,
                            parse_failed,
                        } = autoload_register_source(name, &body);
                        (text, from_wordcode, parse_failed)
                    };
                    {
                        // c:Src/exec.c:5735-5760 — C INSTALLS the parsed Eprog
                        // as the function body; it executes nothing at load
                        // time, so the global `lineno` still holds the line the
                        // CALL was made on when doshfunc records
                        // `funcsave->fstack.lineno = lineno` (c:6013). zshrs
                        // installs the body by RUNNING `name() { … }` through
                        // the pipeline, which walks the counter to the file's
                        // last line — so the very first call of an autoloaded
                        // function reported its caller's line as that instead:
                        // `$functrace` read `script.zsh:1` where zsh reads
                        // `script.zsh:4`, and inside completion `_subscript:0`
                        // where zsh reads `_subscript:125`. Every LATER call
                        // was already correct, because the load only happens
                        // once.
                        let caller_lineno = crate::ported::lex::lineno();
                        // c:5384-5388 assigns `shf->lineno` only when a
                        // `name() { … }` STATEMENT defines the function. An
                        // autoload stub's Shfunc keeps the 0 it was created
                        // with, and loadautofn replaces only `funcdef`, so zsh
                        // reports `funcsourcetrace` as `<file>:0`. Running a
                        // synthesized wrapper here stamps line 1 instead, so
                        // put the stub's value back when the wrapper was ours.
                        let synthesized = registered != body;
                        let _ = self.run_autoload_definition(
                            name,
                            &registered,
                            ksh_style,
                            from_wordcode,
                            parse_failed,
                        );
                        crate::ported::lex::set_lineno(caller_lineno);
                        if synthesized {
                            // c:5384-5388 sets `shf->lineno` only where a
                            // `name() { … }` STATEMENT defines the function; an
                            // autoload stub keeps the 0 it was created with and
                            // loadautofn replaces only `funcdef`, so
                            // `funcsourcetrace` reads `<file>:0`. Executing our
                            // synthesized wrapper records a line base of 1
                            // instead. -1 marks "autoload-installed" so the
                            // call-time clamp below can tell that apart from an
                            // INLINE `f() { … }`, whose base underflows to 0 but
                            // whose def line really is >= 1.
                            self.function_line_base.insert(name.to_string(), -1);
                        }
                    }
                    if let Some(dir) = loaded_dir.as_deref() {
                        restore_loaddir(name, dir, abspath_used, ksh_style);
                    }
                }
            }
        }
        let chunk = self.functions_compiled.get(name).cloned()?;
        // c:5626 — `execode(shf->funcdef, 1, 0, "loadautofunc")`. Held
        // across the body run and dropped with the VM below.
        let _load_ctx =
            did_autoload.then(|| crate::ported::exec::EvalContextFrame::push("loadautofunc"));
        // c:Src/exec.c:5551-5557 (zsh-5.9.1, execautofn_basic) — the freshly
        // loaded body runs with `scriptname = shf->node.nam` and
        // `scriptfilename = getshfuncfile(shf)`, restored afterwards.
        // `doshfunc` skips its own `scriptname = name` for a PM_UNDEFINED
        // function (c:5835-5836), so without this every diagnostic in a body
        // autoloaded here kept the CALLER's name: `_complete:117:` printed as
        // `_main_complete:117:`. `lineno` is zeroed for the body here rather
        // than in `doshfunc` (see the PM_UNDEFINED note there), because the
        // load above must still see the caller's line.
        let autofn_saved = did_autoload.then(|| {
            let saved = (
                crate::ported::utils::scriptname_get(),
                crate::ported::utils::scriptfilename_get(),
            );
            crate::ported::utils::set_scriptname(Some(name.to_string())); // c:5553
            crate::ported::utils::set_scriptfilename(crate::ported::hashtable::getshfuncfile(
                name,
            )); // c:5554
            crate::ported::lex::set_lineno(0);
            saved
        });
        let seed_status = self.last_status();
        let _ = args; // fusevm body reads $1..$N from PPARAMS
                      // Reuse a VM from the per-thread pool instead of building one from
                      // scratch every call. `register_builtins` installs ~hundreds of
                      // fn-pointer handlers into the VM's builtin_table; the table is
                      // identical for every VM, so re-running it per function call was
                      // pure waste (~130 profile samples in a tight call loop, the #2 hot
                      // spot after option lookups). `VM::reset(chunk)` clears execution
                      // state but PRESERVES builtin_table / host / JIT wiring, so a
                      // recycled VM is call-ready without re-registration. Fresh VMs pay
                      // the registration once. Nested calls simply check out additional
                      // VMs; the pool grows to the max call depth. Re-entrant and
                      // panic-safe: the VM is returned on the normal path below.
                      // c:Src/exec.c:4364 — a `return` out of a redirected compound
                      // command still runs `fixfds(save)`. See
                      // `unwind_redirect_scopes_to`.
        let redir_depth = self.redirect_scope_stack.len();
        // A `return` past an open pipeline leaves its job slot held; see
        // exec_jobs::execpline_slots_mark.
        let slots_entry = crate::exec_jobs::execpline_slots_mark();
        let mut vm = crate::vm_pool::acquire(chunk);
        vm.last_status = seed_status;
        let _ = vm.run();
        let status = vm.last_status;
        drop(vm);
        crate::exec_jobs::execpline_slots_release_to(slots_entry);
        self.unwind_redirect_scopes_to(redir_depth);
        if let Some((sn, sfn)) = autofn_saved {
            crate::ported::utils::set_scriptname(sn); // c:5556
            crate::ported::utils::set_scriptfilename(sfn); // c:5557
        }
        Some(status)
    }

    pub fn dispatch_function_call(&mut self, name: &str, args: &[String]) -> Option<i32> {
        // Held for the WHOLE call, not just the load: an autoloaded function is
        // registered TWICE — once when its file's text defines it, and again
        // (unchanged) when its chunk is compiled at call time — and the second
        // stamp would otherwise relabel it with the caller's scriptfilename.
        // See the AUTOLOAD_DEF_FILE consumer in fusevm_bridge.
        let mut _autoload_file_guard: Option<AutoloadFileGuard> = None;
        // Nested scope for `>(cmd)` fd ownership — builtins running
        // inside the function body must not close the CALLER's
        // pending psub fds (`myfn >(cmd)` keeps /dev/fd/N alive for
        // the whole function, like C's per-job filelist). See
        // PSUB_SCOPE_DEPTH in fusevm_bridge.rs.
        let _psub_scope = crate::fusevm_bridge::PsubScope::enter();
        // c:Src/exec.c — `disable -f NAME` flips the DISABLED flag on
        // the shfunctab entry. `lookupshfunc` (which dispatch consults)
        // returns NULL for DISABLED entries, falling through to PATH
        // lookup → "command not found". zshrs keeps the compiled body
        // in functions_compiled independently of the flag, so check
        // shfunctab and short-circuit when DISABLED is set. Bug #221
        // in docs/BUGS.md.
        let is_disabled = crate::ported::hashtable::shfunctab_lock()
            .read()
            .ok()
            .and_then(|t| {
                let entry = t.get_including_disabled(name)?;
                Some((entry.node.flags as u32 & crate::ported::zsh_h::DISABLED as u32) != 0)
            })
            .unwrap_or(false);
        if is_disabled {
            return None;
        }
        // `_regex_arguments NAME …` (e.g. `_regex_arguments _sed_expressions …`
        // in `_sed`) eval-defines a real shell function NAME in zsh. This port
        // stores it in a runtime registry keyed by NAME (a static router fn-ptr
        // can't carry a dynamic name). `run_function_body_only` already consults
        // that registry, but `dispatch_function_call` — the path an `_arguments`
        // action (`:sed script:_sed_expressions`) or any by-name caller takes —
        // did not, so the call fell through to the autoload prelude and errored
        // "function definition file not found" (`sed -<TAB>`). Consult the
        // registry here too, before autoload. Returned directly (like
        // run_function_body_only) — the regex body drives compsys globals, not
        // function locals, so it needs no doshfunc scope wrap.
        if let Some(rc) = crate::compsys::ported::_regex_arguments::dispatch_if_registered(name) {
            return Some(rc);
        }
        // zshrs-original: `[compsys] backend = "rust"` short-circuit.
        // When a `_NAME` has a Rust port AND the user opted into the
        // rust backend, run the Rust fn directly here — but still
        // through the canonical doshfunc scope-management path below
        // (we synthesize a body_runner from the fn pointer). Router
        // returns None for names without a Rust port → graceful
        // fallback to the shfunc autoload path.
        //
        // Note: `compcore::callcompfunc` (the compsys entry hit by
        // Tab) wraps doshfunc itself per C `compcore.c:835`, so the
        // Rust _main_complete dispatch lands HERE only when called
        // from a non-compcore caller (e.g. a user shell script
        // directly invoking `_main_complete`). The doshfunc scope
        // wrap below applies uniformly to both.
        let direct_rust_fn: Option<fn(&[String]) -> i32> =
            crate::compsys::router::try_rust_dispatch(name);
        // A plugin-registered override (ABI v4, `zmodload -R`) also
        // intercepts natively: it supplies the body, so no shell autoload
        // or compiled chunk is needed — same as a built-in Rust port.
        let has_plugin_override = crate::extensions::plugin_host::compfn_override(name).is_some();
        // c:Src/exec.c:3760-3763 — the twin of the gate in
        // `run_function_body_only`: a native compsys port stands in for the
        // COMMAND here, so it must not run when the argument expansion that
        // built its argument list already raised errflag. Scoped to the ported
        // names on purpose — this function is also the shim ports use to call
        // ordinary shell functions (src/ported/exec.rs:8588), and those keep
        // whatever behaviour the executor gives them.
        if (direct_rust_fn.is_some() || has_plugin_override)
            && (errflag.load(Ordering::Relaxed) & ERRFLAG_ERROR) != 0
        {
            crate::ported::builtin::LASTVAL.store(1, Ordering::Relaxed); // c:3761
            return Some(1); // c:3762 goto err
        }
        // c:Src/exec.c:5626 — the body of a function loaded on THIS call
        // runs through `execode(shf->funcdef, 1, 0, "loadautofunc")`
        // (execautofn_basic), nested inside runshfunc's "shfunc" frame.
        // zshrs performs the load here, before `doshfunc`, so the flag
        // carries the fact into the body_runner that pushes the frame.
        let mut did_autoload = false;
        // Autoload prelude skipped when a Rust port OR plugin override wins
        // — no upstream shell function to load.
        if direct_rust_fn.is_none()
            && !has_plugin_override
            && !self.functions_compiled.contains_key(name)
        {
            // c:Src/exec.c:3105-3109 — `execcmd` resolves a command word as
            //     if (!(cflags & (BINF_BUILTIN | BINF_COMMAND)) &&
            //         (hn = shfunctab->getnode(shfunctab, cmdarg))) {
            //         is_shfunc = 1; break; }
            // the identical gate repeating at c:3484-3488, then `builtintab`,
            // then `$PATH`, with a name that resolves nowhere ending at c:903
            // `zerr("command not found: %s", arg0)`. `getnode` finds a node
            // ALREADY IN `shfunctab` — a real definition, or the autoload STUB
            // that `autoload` / `compinit` put there. A file merely PRESENT in
            // `$fpath` is NOT a command in zsh; nothing autoloads it on demand.
            //
            // This used to probe `$fpath` with `getfpfunc` (c:Src/exec.c:6279)
            // for ANY `_`-prefixed name with no shfunctab entry and, on a hit,
            // run `autoload -rUz -- NAME` and execute the file. That gate keyed
            // on the FILENAME, where zsh keys on the file's TAG LINE: compinit
            // sh:511-525 reads `IFS=$' \t' read -rA _i_line < $_i_file` and then
            // `case $_i_tag in (\#compdef) compdef -na … ;; (\#autoload)
            // autoload -rUz "$_i_line[@]" ${_i_name} ;; esac`, so an UNTAGGED
            // `_`-file is registered by neither mechanism — yet zshrs ran it:
            //     fpath=(/tmp/d); __zzz_probe
            //     zsh    zsh:1: command not found: __zzz_probe   (rc 127)
            //     zshrs  RAN                                     (rc 0)
            // The cost was a SWALLOWED DIAGNOSTIC: with the untagged
            // `__fasd_files_comp` / `__fasd_dirs_comp` in `$fpath`, a `_files`
            // override offering them as `_alternative` actions makes zsh report
            // `_alternative:71: command not found: __fasd_files_comp`, where
            // zshrs reported nothing at all because it executed the file.
            //
            // Nothing replaces the probe. The providers that stand in for a
            // stock `$fpath` file already short-circuit ABOVE this block
            // (`direct_rust_fn`, `has_plugin_override`), and `compinit` installs
            // a real PM_UNDEFINED stub for every `#compdef`/`#autoload` file it
            // scans — on the scan path and from a dump alike
            // (`register_autoload_stubs`, src/compsys/ported/compinit.rs:831-855,
            // called at :1137). So the `getshfunc` below IS C's
            // `shfunctab->getnode`, and a name it misses falls through to
            // builtin → `$PATH` → command-not-found, exactly as `execcmd` does.
            if let Some(stub) = crate::ported::utils::getshfunc(name) {
                // c:Src/exec.c:5684-5704 (loadautofn) — `autoload -U` records
                // PM_UNALIASED, whose ONLY effect is that the autoloaded body is
                // PARSED with alias expansion disabled:
                //     int noalias = noaliases;
                //     noaliases = (shf->node.flags & PM_UNALIASED);
                //     prog = getfpfunc(...);        /* parses the file */
                //     noaliases = noalias;
                let unaliased = (stub.node.flags as u32 & crate::ported::zsh_h::PM_UNALIASED) != 0;
                let noalias_save = crate::ported::lex::noaliases(); // c:5684
                crate::ported::lex::set_noaliases(unaliased); // c:5697
                                                              // c:5704 — restored on EVERY exit from this block, including the
                                                              // early `return Some(1)` paths below.
                let _restore_noaliases = NoAliasesRestore(noalias_save);
                if (stub.node.flags as u32 & PM_UNDEFINED) != 0 {
                    did_autoload = true; // c:5626 — body runs as "loadautofunc"
                    let _sticky_load = AutoloadStickyGuard::enter(&stub);
                    let boxed = Box::new(stub.clone());
                    let ptr = Box::into_raw(boxed);
                    let load_rc = crate::ported::exec::loadautofn(ptr, 0, 0, 0);
                    unsafe {
                        let _ = Box::from_raw(ptr);
                    }
                    // c:Src/exec.c:5713-5719 / 5635-5644 — a failed load is
                    // TERMINAL: `loadautofn` already emitted "function
                    // definition file not found" and C's `execautofn` returns
                    // 1 without ever touching a body (C replaced shf->funcdef
                    // with the mkautofn trampoline at c:3180). zshrs still has
                    // the stub's TEXT on the shfunc node, and the `if let
                    // Some(body)` arm below would re-run it — for an
                    // `autoload -X` stub that means re-entering the autoload
                    // path, which recursed to FUNCNEST and printed the
                    // diagnostic 500 times (C04funcdef:38,39,40). The
                    // `else if load_rc != 0` arm below stays as the (now
                    // unreachable) faithful mirror of the same C line.
                    if load_rc != 0 {
                        return Some(1); // c:5719 NULL → c:5644 `return 1`
                    }
                    // c:Src/exec.c:5657 loadautofnsetfile — capture the fpath
                    // directory loadautofn wrote so it can be restored (as an
                    // absolutized path with PM_LOADDIR) after the funcdef pipeline
                    // below clobbers `filename` to scriptfilename ("zsh"). Without
                    // this, `whence -v <autoloaded>` printed "from zsh".
                    let loaded_dir = crate::ported::utils::getshfunc(name)
                        .and_then(|f| f.filename)
                        .filter(|d| d != "zsh");
                    // c:Src/exec.c:5682-5760 — C loads the body IN PLACE on the
                    // existing Shfunc: `shf->node.flags &= ~PM_UNDEFINED`
                    // (c:5751) is the only flag C clears, so PM_ABSPATH_USED —
                    // stamped by `autoload -Uz /abs/dir/NAME`
                    // (`add_autoload_function`, Src/builtin.c:3290-3291) —
                    // survives the load. zshrs re-registers the body through the
                    // funcdef pipeline, which builds a FRESH node and drops the
                    // whole flag word; `loadautofnsetfile` below puts filename +
                    // PM_LOADDIR back, and PM_ABSPATH_USED has to come back with
                    // them. It is read by `add_autoload_function`'s sibling arm
                    // (Src/builtin.c:3310-3323): when a function loaded by
                    // absolute path autoloads a sibling with a bare name, C
                    // inherits the CALLER's load directory — `if ((shf2 = ...
                    // getnode2(shfunctab, calling_f)) && (shf2->node.flags &
                    // PM_LOADDIR) && (shf2->node.flags & PM_ABSPATH_USED) && ...`
                    // Without the restore that test never fired, so
                    // `autoload -Uz $D/wrapper; wrapper` → `autoload -Uz sibling`
                    // failed with "function definition file not found" (zsh runs
                    // $D/sibling), and compsys `_`-names fell through to the Rust
                    // port instead of the user's file.
                    let abspath_used =
                        (stub.node.flags as u32 & crate::ported::zsh_h::PM_ABSPATH_USED) != 0;
                    if let Some(body) = crate::ported::utils::getshfunc(name).and_then(|f| f.body) {
                        let ksh_style = autoload_is_ksh_style(name); // c:5781 (pre-registration)
                        _autoload_file_guard = Some(AutoloadFileGuard::enter(name));
                        let AutoloadSource {
                            text: registered,
                            from_wordcode,
                            parse_failed,
                        } = autoload_register_source(name, &body);
                        // c:Src/exec.c:5739 — the ksh-autoload body runs via
                        // `execode(prog, 1, 0, "evalautofunc")` at the function
                        // invocation's locallevel, so a `return`/`break`/
                        // `continue` inside the file body is CONTAINED to the
                        // autoload call. add-zle-hook-widget's first line is
                        // `zmodload -e zsh/zle || return 1`; when a plugin has
                        // leaked `ksh_autoload` on (e.g. a bare `emulate sh`),
                        // that `return` must NOT propagate out and abort the
                        // caller's precmd/shell (zsh warns "not defined by file"
                        // and CONTINUES). Save & restore the control-flow flags
                        // around the body run to reinstate that boundary.
                        {
                            use crate::ported::builtin::{
                                BREAKS, EXIT_PENDING, EXIT_VAL, RETFLAG, SHELL_EXITING,
                            };
                            use std::sync::atomic::Ordering::Relaxed;
                            // c:Src/exec.c:5739 — `execode(prog, 1, 0,
                            // "evalautofunc")` runs the file body as part of the
                            // autoload invocation. add-zle-hook-widget's
                            // `zmodload -e zsh/zle || return 1` sits at the
                            // file's TOP LEVEL (above its anon-func wrapper); at
                            // script scope a top-level `return` is a shell EXIT,
                            // so running the body as a plain script aborted the
                            // caller's precmd/shell. `return` is contained when
                            // `locallevel || sourcelevel` (bin_return, c:5840) —
                            // raise SOURCELEVEL (the file-source counter, which
                            // unlike locallevel does NOT open a local scope, so
                            // the body's global assignments still land globally)
                            // so the top-level `return` returns from the load
                            // instead of exiting. Save/restore the control-flow
                            // flags so nothing leaks — matching zsh's
                            // warn-and-continue.
                            use crate::ported::init::sourcelevel;
                            let saved_retflag = RETFLAG.swap(0, Relaxed);
                            let saved_breaks = BREAKS.swap(0, Relaxed);
                            let saved_exit_pending = EXIT_PENDING.swap(0, Relaxed);
                            let saved_exit_val = EXIT_VAL.swap(0, Relaxed);
                            let saved_shell_exiting = SHELL_EXITING.swap(0, Relaxed);
                            sourcelevel.fetch_add(1, Relaxed);
                            {
                                // c:Src/exec.c:5739 — the ksh-autoload branch
                                // runs the file through
                                // `execode(prog, 1, 0, "evalautofunc")`, so
                                // that label is on `zsh_eval_context` while
                                // the file body executes.
                                let _ctx =
                                    crate::ported::exec::EvalContextFrame::push("evalautofunc");
                                {
                                    // c:Src/exec.c:5735-5760 — C INSTALLS the parsed Eprog
                                    // as the function body; it executes nothing at load
                                    // time, so the global `lineno` still holds the line the
                                    // CALL was made on when doshfunc records
                                    // `funcsave->fstack.lineno = lineno` (c:6013). zshrs
                                    // installs the body by RUNNING `name() { … }` through
                                    // the pipeline, which walks the counter to the file's
                                    // last line — so the very first call of an autoloaded
                                    // function reported its caller's line as that instead:
                                    // `$functrace` read `script.zsh:1` where zsh reads
                                    // `script.zsh:4`, and inside completion `_subscript:0`
                                    // where zsh reads `_subscript:125`. Every LATER call
                                    // was already correct, because the load only happens
                                    // once.
                                    let caller_lineno = crate::ported::lex::lineno();
                                    // c:5384-5388 assigns `shf->lineno` only when a
                                    // `name() { … }` STATEMENT defines the function. An
                                    // autoload stub's Shfunc keeps the 0 it was created
                                    // with, and loadautofn replaces only `funcdef`, so zsh
                                    // reports `funcsourcetrace` as `<file>:0`. Running a
                                    // synthesized wrapper here stamps line 1 instead, so
                                    // put the stub's value back when the wrapper was ours.
                                    let synthesized = registered != body;
                                    let _ = self.run_autoload_definition(
                                        name,
                                        &registered,
                                        ksh_style,
                                        from_wordcode,
                                        parse_failed,
                                    );
                                    crate::ported::lex::set_lineno(caller_lineno);
                                    if synthesized {
                                        // c:5384-5388 sets `shf->lineno` only where a
                                        // `name() { … }` STATEMENT defines the function; an
                                        // autoload stub keeps the 0 it was created with and
                                        // loadautofn replaces only `funcdef`, so
                                        // `funcsourcetrace` reads `<file>:0`. Executing our
                                        // synthesized wrapper records a line base of 1
                                        // instead. -1 marks "autoload-installed" so the
                                        // call-time clamp below can tell that apart from an
                                        // INLINE `f() { … }`, whose base underflows to 0 but
                                        // whose def line really is >= 1.
                                        self.function_line_base.insert(name.to_string(), -1);
                                    }
                                }
                            }
                            sourcelevel.fetch_sub(1, Relaxed);
                            RETFLAG.store(saved_retflag, Relaxed);
                            BREAKS.store(saved_breaks, Relaxed);
                            EXIT_PENDING.store(saved_exit_pending, Relaxed);
                            EXIT_VAL.store(saved_exit_val, Relaxed);
                            SHELL_EXITING.store(saved_shell_exiting, Relaxed);
                        }
                        if let Some(dir) = loaded_dir.as_deref() {
                            restore_loaddir(name, dir, abspath_used, ksh_style);
                        }
                        if !self.functions_compiled.contains_key(name) {
                            // c:Src/exec.c:5742-5745 — ksh-style load ran
                            // the file (`execode`, "evalautofunc") but it
                            // didn't define NAME:
                            //   `zwarn("%s: function not defined by file", n);`
                            // That diagnostic lives INSIDE C's
                            // `ksh == 2 || (ksh == 1 && isset(KSHAUTOLOAD))`
                            // branch (c:5726). The zsh-style branch (c:5753-
                            // 5758) installs the parsed program as the body
                            // outright and cannot fail this way, so zsh prints
                            // nothing there — and when the file did not parse,
                            // `getfpfunc` already returned NULL and the load
                            // ended at c:5722 with only the parse error.
                            // zshrs used to print it for every failed
                            // registration, so `g(){ emulate ksh -c _files }`
                            // gained a `_files: function not defined by file`
                            // line zsh never emits. Status still propagates:
                            // c:5644 `if (!loadautofn(...)) return 1`.
                            if ksh_style {
                                crate::ported::utils::zwarn(&format!(
                                    "{}: function not defined by file",
                                    name
                                ));
                            }
                            return Some(1);
                        }
                    } else if load_rc != 0 {
                        // c:Src/exec.c:5713-5719 / 5635-5644 —
                        // `execautofn`'s `if (!loadautofn(...)) return 1`
                        // propagates the loadautofn failure as the
                        // command's exit status. zshrs's previous
                        // path returned None here, falling through to
                        // execute_external which emitted a SECOND
                        // diagnostic (`command not found: NAME`) on
                        // top of loadautofn's `function definition
                        // file not found`. Mirror C: when load failed
                        // AND the stub still has no body, surface
                        // status=1 so the caller does NOT fall back
                        // to PATH search.
                        return Some(1);
                    }
                } else if let Some(body) = stub.body.clone() {
                    // c:Src/exec.c:5978 — the body runs under the stub's sticky
                    // emulation; see AutoloadStickyGuard.
                    let _sticky_load = AutoloadStickyGuard::enter(&stub);
                    // c:Src/Modules/parameter.c::setpmfunction — function
                    // registered via `functions[name]=body` lives in
                    // shfunctab with `body` set but `functions_compiled`
                    // empty (the canonical port stores the parsed eprog,
                    // not a fusevm Chunk). Lazy-compile here by feeding
                    // the body through the standard funcdef pipeline so
                    // the next CallFunction op finds the chunk.
                    //
                    // c:Src/builtin.c:3180 (eval_autoload) — `autoload +X NAME`
                    // reaches this arm as well: it loads the body EAGERLY via
                    // `loadautofn`, which sets `body` + `filename`/PM_LOADDIR
                    // and clears PM_UNDEFINED but leaves no compiled chunk, so
                    // the first CALL never sees the PM_UNDEFINED arm above.
                    // Restore the load directory after re-registration exactly
                    // as that arm does — otherwise `autoload +X /abs/dir/NAME`
                    // dropped PM_LOADDIR|PM_ABSPATH_USED before the body ran
                    // and a sibling `autoload -Uz SIB` inside it failed with
                    // "function definition file not found" where zsh loads
                    // /abs/dir/SIB. The `functions[name]=body` case has no
                    // PM_LOADDIR, so the restore is skipped for it.
                    let loaded_dir = ((stub.node.flags as u32 & crate::ported::zsh_h::PM_LOADDIR)
                        != 0)
                        .then(|| stub.filename.clone())
                        .flatten();
                    let abspath_used =
                        (stub.node.flags as u32 & crate::ported::zsh_h::PM_ABSPATH_USED) != 0;
                    // c:Src/Modules/parameter.c:295-315 — a body that arrived
                    // through `functions[NAME]=BODY` is NOT a file. See
                    // `body_came_from_param_assignment`.
                    let param_body = body_came_from_param_assignment(stub.node.flags);
                    let ksh_style = !param_body && autoload_is_ksh_style(name); // c:5781 (pre-registration)
                    _autoload_file_guard = Some(AutoloadFileGuard::enter(name));
                    // A `functions[name]=body` assignment is already a parsed
                    // body, so it takes no file parse and cannot have reported
                    // one (`parse_failed` is false by construction).
                    let (registered, from_wordcode, parse_failed) = if param_body {
                        (param_definition_source(name, &body), false, false)
                    } else {
                        let AutoloadSource {
                            text,
                            from_wordcode,
                            parse_failed,
                        } = autoload_register_source(name, &body);
                        (text, from_wordcode, parse_failed)
                    };
                    {
                        // c:Src/exec.c:5735-5760 — C INSTALLS the parsed Eprog
                        // as the function body; it executes nothing at load
                        // time, so the global `lineno` still holds the line the
                        // CALL was made on when doshfunc records
                        // `funcsave->fstack.lineno = lineno` (c:6013). zshrs
                        // installs the body by RUNNING `name() { … }` through
                        // the pipeline, which walks the counter to the file's
                        // last line — so the very first call of an autoloaded
                        // function reported its caller's line as that instead:
                        // `$functrace` read `script.zsh:1` where zsh reads
                        // `script.zsh:4`, and inside completion `_subscript:0`
                        // where zsh reads `_subscript:125`. Every LATER call
                        // was already correct, because the load only happens
                        // once.
                        let caller_lineno = crate::ported::lex::lineno();
                        // c:5384-5388 assigns `shf->lineno` only when a
                        // `name() { … }` STATEMENT defines the function. An
                        // autoload stub's Shfunc keeps the 0 it was created
                        // with, and loadautofn replaces only `funcdef`, so zsh
                        // reports `funcsourcetrace` as `<file>:0`. Running a
                        // synthesized wrapper here stamps line 1 instead, so
                        // put the stub's value back when the wrapper was ours.
                        let synthesized = registered != body;
                        let _ = self.run_autoload_definition(
                            name,
                            &registered,
                            ksh_style,
                            from_wordcode,
                            parse_failed,
                        );
                        crate::ported::lex::set_lineno(caller_lineno);
                        if synthesized {
                            // c:5384-5388 sets `shf->lineno` only where a
                            // `name() { … }` STATEMENT defines the function; an
                            // autoload stub keeps the 0 it was created with and
                            // loadautofn replaces only `funcdef`, so
                            // `funcsourcetrace` reads `<file>:0`. Executing our
                            // synthesized wrapper records a line base of 1
                            // instead. -1 marks "autoload-installed" so the
                            // call-time clamp below can tell that apart from an
                            // INLINE `f() { … }`, whose base underflows to 0 but
                            // whose def line really is >= 1.
                            self.function_line_base.insert(name.to_string(), -1);
                        }
                    }
                    if let Some(dir) = loaded_dir.as_deref() {
                        restore_loaddir(name, dir, abspath_used, ksh_style);
                    }
                }
            }
        }
        // When a Rust port is registered, skip the fusevm Chunk
        // lookup entirely — the body_runner closure below will run
        // the Rust fn pointer directly. Otherwise require a compiled
        // chunk for the autoloaded body.
        let mut chunk_opt = if direct_rust_fn.is_some() || has_plugin_override {
            None
        } else {
            Some(self.functions_compiled.get(name).cloned()?)
        };

        // c:Src/exec.c:5634 (execshfunc) — `xtrerr = stderr;`: the body traces
        // to the stderr the call's own redirections set up.
        crate::ported::utils::xtrerr.store(2, Ordering::Relaxed);

        // zshrs-specific bookkeeping that doshfunc doesn't own:
        // - prompt_funcstack (PS4 trace) push/pop
        // - local_scope_depth FUNCNEST guard
        //
        // c:Src/exec.c::funcnest_check — C zsh allows FUNCNEST=500 by
        // default. zshrs's per-call stack usage is heavier (vm_helper
        // state, fusevm closures, parse buffers), so on the default 8MB
        // stack a deep recursion overflowed around depth ~80-120 and
        // crashed. That is now fixed at the source: the shell runs on a
        // 512MB-stack thread (see bins/zshrs.rs::main), which comfortably
        // fits FUNCNEST (500) nested heavy frames. So the effective limit
        // is the user's FUNCNEST (default 500), matching zsh — no premature
        // clamp — with a generous hard ceiling as a last-resort backstop
        // that stays well under the big stack's capacity. Bug #519 (the
        // crash) / #643 (the false-positive clamp at 80 that broke
        // legitimately deep recursion). The authoritative FUNCNEST error
        // is also enforced in doshfunc (exec.rs) on the FS_FUNC depth.
        const FUNCNEST_RUST_CEILING: usize = 6000;
        let funcnest_user: usize = self
            .scalar("FUNCNEST")
            .and_then(|s| s.parse().ok())
            .unwrap_or(500);
        let funcnest_limit = funcnest_user.min(FUNCNEST_RUST_CEILING);
        if self.local_scope_depth >= funcnest_limit {
            // c:Src/exec.c:6060-6063 —
            //     zerr("maximum nested function level reached; increase FUNCNEST?");
            //     lastval = 1;
            //     goto undoshfunc;
            // `zerr` is what makes this FATAL: it raises errflag, so the
            // enclosing list stops and a non-interactive shell exits.
            // zsh 5.9:
            //     zsh -fc 'FUNCNEST=2; f() { f; }; f; printf after'
            // prints only the diagnostic and exits 1 — no `after`. bash
            // agrees ("Function invocations that exceed this nesting level
            // cause the current command to abort", bash(1) FUNCNEST), and
            // its own message is likewise followed by exit 1.
            //
            // This guard printed with a bare `eprintln!` and returned 1
            // WITHOUT raising errflag, so the runaway recursion stopped but
            // the script kept running — `printf after` ran and the shell
            // exited 0. The ported check in exec.rs::doshfunc already does
            // the C trio, but this one fires first (it is the zshrs-only
            // stack backstop, evaluated before dispatch reaches doshfunc),
            // so it has to carry the same side effects.
            //
            // The message is written here rather than through `zerr`
            // because C's prefix is the *function* name — `scriptname` is
            // the running function inside doshfunc — and this guard runs
            // before that switch; going through zerr would print the outer
            // script name instead. Byte-compared against zsh 5.9.
            // c:Src/utils.c zerr → zerrmsg prints `scriptname:lineno: msg`
            // whenever `scriptname` is set (which it is here: c:5963
            // `scriptname = dupstring(name)` runs BEFORE the c:6060 check).
            // The `:lineno` half was missing, so
            //   ( FUNCNEST=0; fn() { true; }; fn )
            // printed `fn: maximum …` where zsh prints `fn:4: maximum …`
            // (C04funcdef:46).
            // c:Src/utils.c:301-308 zerrmsg — the `lineno: ` part is only
            // printed when `lineno` is non-zero (else a single space), so a
            // recursion on a function's first line reads `f: maximum …`.
            let lineno = crate::ported::lex::lineno();
            let shows_lineno = (crate::ported::zsh_h::unset(crate::ported::zsh_h::SHINSTDIN)
                || crate::ported::params::locallevel.here() != 0)
                && lineno != 0;
            if shows_lineno {
                eprintln!(
                    "{}:{}: maximum nested function level reached; increase FUNCNEST?",
                    name, lineno
                );
            } else {
                eprintln!("{}: maximum nested function level reached; increase FUNCNEST?", name);
            }
            errflag.fetch_or(ERRFLAG_ERROR, Ordering::Relaxed); // c:6061 (zerr)
            crate::ported::builtin::LASTVAL.store(1, Ordering::Relaxed); // c:6062
            return Some(1);
        }
        let display_name = if name.starts_with("_zshrs_anon_") {
            "(anon)".to_string()
        } else {
            name.to_string()
        };
        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));
        self.local_scope_depth += 1;

        // Synthetic shfunc for doshfunc — carries the name + def-file
        // info so funcstack push gets a proper filename. funcdef/body
        // stay None because the wordcode body is irrelevant on this
        // path (body_runner runs the fusevm Chunk directly).
        // c:Src/exec.c:5390-5410 — execfuncdef records the
        // current `scriptfilename` on the shfunc at definition
        // time so funcsourcetrace can show file:line of the
        // function's source. The function_def_file map stores
        // this; fall back to the live scriptfilename so dynamic
        // / non-`compile_funcdef`-routed definitions still get a
        // sensible filename. Without the fallback, the synth_shf
        // saw None and the funcstack push at exec.rs:5719
        // defaulted to an empty string, which the funcsourcetrace
        // getfn rendered as `:N` (or worse, picked up the
        // function name from a parallel field). Bug #515.
        // c:Src/exec.c:5620/5625 — the source file is `getshfuncfile(shf)`,
        // which reads the shfunc's own `filename` (authoritative: set by
        // execfuncdef for a normally-defined function, and by loadautofn — as
        // the fpath dir with PM_LOADDIR — for an AUTOLOADED one). Prefer it.
        // `function_def_file` is a zshrs-only side map that, for an autoloaded
        // function, was stamped with the OUTER `scriptfilename` ("zsh") at
        // compile time, not the fpath file — so it must NOT override
        // getshfuncfile. Consulting it second still covers functions whose
        // shfunc `filename` wasn't recorded (compile_funcdef-routed defs);
        // scriptfilename is the final fallback. Without getshfuncfile winning,
        // funcsourcetrace reported "zsh" for every autoloaded completer, which
        // broke `_git`: its first git-completion.bash search path is
        // `"$(dirname ${funcsourcetrace[1]%:*})"/git-completion.bash` — "zsh"
        // resolved to `./git-completion.bash`, found nothing, and
        // `. "$script"` errored (`_git:.:48: no such file or directory`).
        let synth_filename = crate::ported::hashtable::getshfuncfile(name)
            .or_else(|| self.function_def_file.get(name).cloned().flatten())
            .or_else(|| self.scriptfilename.clone());
        // c:Src/exec.c:5409 — `shf->lineno = lineno;` (def line).
        // `function_line_base[name]` carries compile_funcdef's
        // `lineno_offset = first_body_line - 1` — equals the def line
        // for multi-line `f() {\n body }` but underflows to 0 for
        // INLINE `f() { body }` (def and body share a line). zsh's
        // funcsourcetrace reports the def line as 1-based, so clamp
        // to >= 1 to handle the inline case without rebuilding
        // line tracking through the parser. Bug #396.
        let synth_lineno = {
            let base = self.function_line_base.get(name).copied().unwrap_or(0);
            if base < 0 {
                // Autoload-installed (see the -1 marker at the install
                // site): c:5384 never runs for it, so the def line is 0.
                0
            } else {
                std::cmp::max(1i64, base)
            }
        };
        // Carry the REAL function's attribute flags over from shfunctab.
        // `functions -t/-T/-W` store PM_TAGGED / PM_TAGGED_LOCAL /
        // PM_WARNNESTED on the shfunctab node (builtin.rs c:3719), and
        // doshfunc turns PM_TAGGED* into XTRACE for the duration of the call
        // (exec.c:5954-5960). Hardcoding 0 here severed that link: the flags
        // were parsed and stored correctly, but the synthesized shfunc handed
        // to doshfunc always claimed "no attributes", so `functions -t f; f`
        // ran silently while `setopt xtrace` (a global option, not routed
        // through this struct) traced normally. Bug #1058.
        // The shfunctab key is the REGISTRATION name, which for an
        // anonymous function is the generated `_zshrs_anon_*` (only the
        // DISPLAY name is `(anon)` — c:Src/exec.c:5492 sets
        // `shf->node.nam = ANONYMOUS_FUNCTION_NAME` on the same struct
        // that already carries `tracing_flags` from c:5437). Looking the
        // flags up under the display name missed every anonymous
        // function, so `function -T { … }` ran untraced (E02xtrace:7,9).
        let synth_flags = crate::ported::hashtable::shfunctab_lock()
            .read()
            .ok()
            .and_then(|t| {
                t.get(name)
                    .or_else(|| t.get(display_name.as_str()))
                    .map(|s| s.node.flags)
            })
            .unwrap_or(0)
            // PM_LOADDIR is the ONE flag that must not ride along, because it
            // describes the `filename` FIELD and `synth_filename` above is not
            // that field — it is already `getshfuncfile`'s ANSWER.
            // c:Src/hashtable.c:1061 `zhtricat(shf->filename, "/", shf->node.nam)`
            // says PM_LOADDIR means "filename holds the fpath DIRECTORY, append
            // the name"; doshfunc re-applies exactly that when it builds the
            // funcstack frame (exec.rs c:6019, the PM_LOADDIR arm). Carrying
            // the flag onto a node whose filename is the resolved FILE appended
            // `/name` a SECOND time, so an autoloaded completer's
            // `$funcsourcetrace[1]` read `<dir>/_git/_git:0` where zsh reads
            // `<dir>/_git:0`. That is not cosmetic: `_git` (git's own zsh
            // wrapper) locates git-completion.bash with
            // `"$(dirname ${funcsourcetrace[1]%:*})"/git-completion.bash`, so
            // the doubled component sent it to a directory that does not exist,
            // left `$script` empty, and `. "$script"` failed with
            // `_git:.:48: no such file or directory:`. This silently undid
            // 8d8adf9c48, whose whole purpose was to make that search succeed.
            // `functions_source` / `whence -v` were unaffected — they call
            // `getshfuncfile` against the REAL shfunctab node, which is
            // correct; only the synthesized frame doubled.
            & !(crate::ported::zsh_h::PM_LOADDIR as i32);
        // c:Src/exec.c:5978 — `if (sticky_emulation_differs(shfunc->sticky))`
        // reads the STORED per-function sticky snapshot that
        // `shfunc_set_sticky` (c:5402) stamped at definition time. The
        // synthesized shfunc hardcoded `sticky: None`, so a function
        // defined under `emulate sh -c '...'` never re-entered its
        // emulation when called (B07emulate.ztst:6,7,8,12,13,14).
        // Carry it over from shfunctab like `synth_flags` above.
        let synth_sticky = crate::ported::hashtable::shfunctab_lock()
            .read()
            .ok()
            .and_then(|t| {
                t.get(name)
                    .or_else(|| t.get(display_name.as_str()))
                    .and_then(|s| {
                        s.sticky
                            .as_deref()
                            .map(|b| crate::ported::exec::sticky_emulation_dup(b, 0))
                    })
            });
        let mut synth_shf = crate::ported::zsh_h::shfunc {
            node: crate::ported::zsh_h::hashnode {
                next: None,
                nam: display_name.clone(),
                flags: synth_flags,
            },
            filename: synth_filename,
            lineno: synth_lineno,
            funcdef: None,
            redir: None,
            sticky: synth_sticky,
            body: None,
            redir_text: None,
        };
        // doshargs: C convention — argv[0] = function name (for
        // FUNCTIONARGZERO `$0`), argv[1..] = real positional args.
        let mut doshargs: Vec<String> = vec![display_name.clone()];
        doshargs.extend(args.iter().cloned());

        // Seed `$?` with the parent's last status — C zsh's
        // doshfunc inherits lastval automatically because it's a
        // process-global; the fusevm VM creates a fresh
        // `vm.last_status = 0` per call, so we mirror the inherit
        // explicitly. Without this, a function reading `$?` BEFORE
        // running any command sees 0 instead of the caller's status.
        let seed_status = self.last_status();
        let body_args: Vec<String> = args.to_vec();
        let name_owned = name.to_string();
        let body_runner = move || -> i32 {
            // c:Src/exec.c:5626 — `execode(shf->funcdef, 1, 0,
            // "loadautofunc")`. On the call that autoloaded the function,
            // C runs its body one `zsh_eval_context` frame deeper than
            // runshfunc's "shfunc", which is why zsh reports
            // `shfunc:loadautofunc:…` down a chain of freshly autoloaded
            // completers where zshrs reported a flat `shfunc:shfunc:…`.
            let _load_ctx =
                did_autoload.then(|| crate::ported::exec::EvalContextFrame::push("loadautofunc"));
            // Branch: plugin override (ABI v4) → built-in Rust port →
            // fusevm Chunk (autoloaded shell body). All run INSIDE
            // doshfunc's scope so prologue/epilogue applies identically.
            if let Some(rc) =
                crate::extensions::plugin_host::dispatch_compfn(&name_owned, &body_args)
            {
                return rc;
            }
            if let Some(f) = direct_rust_fn {
                return crate::compsys::router::run_port(&name_owned, &body_args, f);
            }
            // The function body is already this closure's own copy (taken at
            // dispatch, above), and fusevm's VM owns the chunk it runs. Move
            // it into the VM and take it back afterwards instead of copying
            // it again: compinit alone runs compdef ~15,000 times, and the
            // second deep copy of every body was the largest single cost in
            // its profile. `VM::run` never writes `vm.chunk`, so what comes
            // back is the same body. Taking it back also keeps a repeated
            // invocation working — C's runshfunc runs the body again when a
            // wrapper handler returns `cont` after running it
            // (Src/exec.c runshfunc: `while (wrap) { cont = handler(...);
            // if (!cont) return; ... } execode(prog, ...)`).
            let chunk = chunk_opt
                .take()
                .expect("chunk_opt must be Some when direct_rust_fn is None");
            crate::fusevm_disasm::maybe_print_stdout(
                &format!(
                    "function:{}",
                    body_args.first().map(|s| s.as_str()).unwrap_or("")
                ),
                &chunk,
            );
            let mut vm = crate::vm_pool::acquire(chunk);
            vm.last_status = seed_status;
            let _ = vm.run();
            chunk_opt = Some(std::mem::take(&mut vm.chunk));
            vm.last_status
        };

        // Enter executor context BEFORE doshfunc so the body_runner's
        // VM builtins can `with_executor(...)` to reach this state.
        // c:Src/exec.c:5572-5585 — execshfunc swaps in a FRESH, EMPTY cmdstack
        // for the duration of a shell-function call and restores the caller's
        // afterwards:
        //     ocs = cmdstack; ocsp = cmdsp;
        //     cmdstack = zalloc(CMDSTACKSZ); cmdsp = 0;
        //     doshfunc(shf, args, 0);
        //     free(cmdstack); cmdstack = ocs; cmdsp = ocsp;
        // The cmdstack is what `%_` renders, so without the swap a function
        // body inherits the CALLER's parser context: `f(){ print -rP "[%_]" }`
        // printed `[cursh]` inside `{ f }`, `[then]` inside an `if`, `[for]`
        // inside a loop and `[case]` inside a case arm, where zsh prints `[]`
        // in every one. Most visible under xtrace, whose default PS4 ends in
        // `%_`, so every traced line inside a called function carried a stale
        // field. `( f )` was already correct only because the subshell forks.
        // Bug #1059.
        let saved_cmdstack: Vec<u8> =
            crate::ported::prompt::CMDSTACK.with(|s| std::mem::take(&mut *s.borrow_mut()));
        // c:Src/exec.c:4364 — a `return` out of a redirected compound
        // command still runs `fixfds(save)`. See
        // `unwind_redirect_scopes_to`.
        let redir_depth = self.redirect_scope_stack.len();
        // c:Src/exec.c:5632-5638 — `if ((osfc = sfcontext) == SFC_NONE)
        // sfcontext = SFC_DIRECT; … doshfunc(shf, args, 0); sfcontext = osfc;`.
        // Read by the job-text gates (c:2060, c:3537): a command run inside a
        // function is not given the source text `time` reports as %J.
        let osfc = crate::ported::exec::sfcontext.load(std::sync::atomic::Ordering::Relaxed);
        if osfc == crate::ported::zsh_h::SFC_NONE {
            crate::ported::exec::sfcontext.store(
                crate::ported::zsh_h::SFC_DIRECT,
                std::sync::atomic::Ordering::Relaxed,
            ); // c:5633
        }
        let _ctx = ExecutorContext::enter(self);
        let status = crate::ported::exec::doshfunc(&mut synth_shf, doshargs, false, body_runner);
        drop(_ctx);
        crate::ported::exec::sfcontext.store(osfc, std::sync::atomic::Ordering::Relaxed); // c:5638
        self.unwind_redirect_scopes_to(redir_depth);
        crate::ported::prompt::CMDSTACK.with(|s| *s.borrow_mut() = saved_cmdstack);

        self.prompt_funcstack.pop();
        self.local_scope_depth -= 1;

        // 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> {
        // FORK_EVENTS is bumped at the real spawn site inside
        // execute_external_bg — this entry is only ONE of several
        // callers of that spawn (the common static-head command path
        // calls execute_external_bg directly), so counting here would
        // miss `time sleep 0` while double-counting this path.
        self.execute_external_bg(cmd, args, redirects, false, 0)
    }

    /// `command -p cmd …` — `execute(args, cflags, defpath=1)`.
    ///
    /// c:Src/exec.c:3212-3214 — the `command` precommand modifier's `-p`
    /// sets `use_defpath = 1`, and c:4369 `execute(args, cflags,
    /// use_defpath)` carries it into the exec. C never touches `$path` for
    /// this: the default-path search happens inside `execute()` alone
    /// (c:810-828), so `$PATH`, the child's environment and `cmdnamtab` all
    /// stay exactly as they were.
    pub(crate) fn execute_external_defpath(
        &mut self,
        cmd: &str,
        args: &[String],
        redirects: &[Redirect],
    ) -> Result<i32, String> {
        self.execute_external_bg(cmd, args, redirects, false, 1)
    }

    /// Port of `execute()` from `Src/exec.c:729` — C decl
    /// `execute(LinkList args, int flags, int defpath)`. `defpath` is the
    /// third C parameter and is non-zero only for `command -p`.
    fn execute_external_bg(
        &mut self,
        cmd: &str,
        args: &[String],
        _redirects: &[Redirect],
        background: bool,
        defpath: i32, // c:729
    ) -> Result<i32, String> {
        tracing::trace!(cmd, bg = background, "exec external");
        // c:Src/exec.c:3545-3547 — `setunderscore((args && nonempty(args)) ?
        // ((char *) getdata(lastnode(args))) : "")`. execcmd_exec sets `$_`
        // to the last word of the command it is about to run, in the PARENT,
        // before any builtin/plugin resolution or fork — so `cat /dev/null;
        // print $_` reports `/dev/null` and a pipeline's stages each leave
        // their own last word behind. This is the single funnel every
        // external spawn reaches (the static-head command path calls it
        // directly and bypasses ZshrsHost::exec / host_exec_external), so
        // the write belongs here. C's `args` list carries argv[0], hence the
        // fallback to `cmd` for a bare command.
        {
            let last = args.last().cloned().unwrap_or_else(|| cmd.to_string());
            crate::ported::params::set_zunderscore(std::slice::from_ref(&last));
            // c:3546
        }
        // !!! WARNING: RUST-ONLY — NO C COUNTERPART !!!
        // Native (Rust) plugin builtins registered via `zmodload -R`
        // (src/extensions/plugin_host.rs). fusevm compiles unknown
        // names into external execution, so a plugin command arrives
        // here as an "external". Resolve it BEFORE the PATH-unset guard
        // and the process spawn — plugin builtins are in-process and
        // need no PATH. This is the analog of C's `resolvebuiltin`
        // slot (Src/exec.c:2700), which likewise runs before the fork.
        // Bare names only: a `/`-qualified token is always a filesystem
        // path, never a plugin command name. Runs synchronously even
        // when backgrounded — zshrs is non-forking and an in-process
        // builtin has nothing to background.
        if !cmd.contains('/') {
            if let Some(status) = crate::plugin_host::dispatch(cmd, args) {
                return Ok(status);
            }
        }
        // !!! WARNING: RUST-ONLY — NO C COUNTERPART !!!
        // Host-registered native commands (`extensions/native_cmds.rs`) — the
        // sibling runtimes a fat binary links into the shell's address space:
        // `git` (zvcs), `arb` (arblang) and `stryke` (strykelang) in the
        // zshrs-native build. Same slot and same reason as the plugin-builtin
        // dispatch directly above: the compiler has never heard of these names,
        // so it lowered them to external execution and they arrive here — this
        // is where they must be caught, BEFORE the PATH guard and before the
        // spawn, because an in-process builtin needs no PATH and no process.
        //
        // Two escape hatches to the binary on disk stay open, and both are
        // checked here. A `/`-qualified token (`/usr/bin/git`) is a filesystem
        // path the user named, never a registry key. And `command git`
        // explicitly asks past the in-process one — the `command` handler
        // raises `native_cmds::force_external` around this call, exactly as
        // `command cat` already escapes the coreutils shadow.
        //
        // The registry's contract is full argv (argv[0] = the name as
        // invoked), which zvcs reads for its `git-<verb>` dashed form.
        //
        // Empty in the thin shell: one map lookup that always misses.
        if !cmd.contains('/')
            && !crate::native_cmds::is_forced_external()
            && crate::native_cmds::is_enabled(cmd)
        {
            let full: Vec<String> = std::iter::once(cmd.to_string())
                .chain(args.iter().cloned())
                .collect();
            if let Some(status) = crate::native_cmds::dispatch(cmd, &full) {
                return Ok(status);
            }
        }
        // c:Src/exec.c:824-876 — when arg0 has no `/`, C zsh requires
        // a PATH search. With PATH unset, the search yields no hit
        // and C emits `command not found: <cmd>`. Rust's
        // `Command::new(name)` delegates to libc `execvp`, which on
        // many platforms falls back to a built-in default PATH when
        // the env entry is missing — so `unset PATH; ls` still finds
        // `/bin/ls` and runs it, breaking the security boundary the
        // unset is supposed to establish (#416). Gate explicitly:
        // when cmd is a bare name (no `/`) and zshrs's own PATH
        // param is unset OR empty, emit the canonical
        // "command not found" diagnostic and return 127 BEFORE
        // touching libc.
        //
        // c:810-815 — `if (defpath) { … search_defpath(arg0, …) … }` runs
        // INSTEAD OF the `$path` walk, so `command -p` must not be judged by
        // `$PATH` at all: the oracle runs `PATH=; command -p awk …` fine.
        if !cmd.contains('/') && defpath == 0 {
            let path_set_and_nonempty = crate::ported::params::getsparam("PATH")
                .map(|p| !p.is_empty())
                .unwrap_or(false);
            if !path_set_and_nonempty {
                let sn =
                    crate::ported::utils::scriptname_get().unwrap_or_else(|| "zshrs".to_string());
                // c:Src/exec.c:811 `zerr("command not found: %s", arg0)`
                // — the diagnostic carries the CURRENT line, not a
                // hardcoded 1. `lineno()` is the same counter zwarning
                // (utils.rs:179) uses and is live during VM execution
                // (verified: read-only / div-by-zero errors already
                // report the right line). Emitted directly (not via
                // zerr) to avoid setting errflag — command-not-found is
                // non-fatal and the script must continue.
                // Inline Rust FFI export: needs no PATH, so run it here rather
                // than reporting not-found when PATH is unset/empty.
                if let Some(rc) = self.try_registered_ffi_command(cmd, args) {
                    return Ok(rc);
                }
                eprintln!("{}: command not found: {}", zerr_prefix(&sn), crate::ported::utils::nicedupstring(&cmd));
                return Ok(127);
            }
        }
        // c:Src/exec.c:2700-2724 resolvebuiltin — names registered via
        // `zmodload -ab MOD NAME` resolve through builtintab BEFORE
        // PATH search in C (execcmd's builtin lookup precedes the
        // external fork). Names the compiler didn't know as builtins
        // land here; consult the autoload ledger, load the module,
        // and re-dispatch through the builtin chokepoint. Without
        // this, `zmodload -ab zsh/bogus mybltn; mybltn` skipped the
        // C autoload-fire entirely (PATH miss → 127 instead of the
        // load_module diagnostic → 1).
        if !cmd.contains('/') {
            if let Some(rc) = crate::ported::exec::resolvebuiltin(cmd) {
                if rc != 0 {
                    return Ok(1);
                }
                return Ok(crate::fusevm_bridge::dispatch_builtin_raw(
                    cmd,
                    args.to_vec(),
                ));
            }
        }
        // c:Src/exec.c:3655-3675 — execcmd_exec's external-command
        // resolution, the step that populates `cmdnamtab`:
        //
        //     hn = cmdnamtab->getnode(cmdnamtab, cmdarg);           c:3661
        //     if (!hn && dohashcmd && strcmp(cmdarg, "..")) {       c:3671
        //         for (s = cmdarg; *s && *s != '/'; s++);           c:3672
        //         if (!*s) hn = (HashNode) hashcmd(cmdarg, ...);    c:3674
        //     }
        //
        // and c:831-869 in `execute()`, which turns the resulting node into
        // the pathname it hands `zexecve`: a HASHED entry execs `cn->u.cmd`
        // verbatim, an unhashed one execs `"<*cn->u.name>/<arg0>"`.
        //
        // Neither step ran here. This is the funnel every statically-spelled
        // external command reaches (`awk …` compiles to a fusevm exec op →
        // host_exec_external → here), and it handed the bare word straight to
        // `Command::new`, i.e. to libc `execvp`, which does its own PATH walk
        // and knows nothing about the shell's table. Two consequences:
        // `cmdnamtab` stayed empty for the whole life of the shell, so `hash`
        // listed nothing after running a command and everything reading the
        // table (`hash`, `unhash`, `whence`, `$commands`, completion) saw an
        // empty one; and an explicit `hash awk=/bin/echo` was ignored at exec
        // time because libc re-derived the path from `$PATH`. Only the
        // run-time-resolved head (`c=awk; $c …`) went through execcmd_exec
        // and hashed correctly, which is why the gap was invisible from the
        // ported side.
        //
        // `hashed_prog` also records that the pathname came from the table,
        // so the ENOENT arms below can fall back to the bare name the way
        // c:877 `execute_skip_exec:` falls through to a full `$path` walk
        // when the cmdnamtab candidate fails to exec.
        let mut hashed_prog: Option<String> = None;
        // c:3672-3673 — bare names only; a `/` in the word means the user
        // named a file and C never consults the table for it. c:3671 —
        // `..` is excluded by name.
        if !cmd.contains('/') && cmd != ".." {
            // c:3661 — `cmdnamtab->getnode(cmdnamtab, cmdarg)`.
            let mut have = crate::ported::hashtable::cmdnamtab_lock()
                .read()
                .ok()
                .and_then(|t| t.get(cmd).cloned());
            // c:3659 + c:3671 — `dohashcmd = isset(HASHCMDS)`.
            if have.is_none() && crate::ported::zsh_h::isset(crate::ported::zsh_h::HASHCMDS) {
                // c:3674 — `hashcmd(cmdarg, checkpath)`. Passing the whole
                // `$path` matches the sibling call in execcmd_exec
                // (exec.rs:11106) and hashcmd's own indexing of `pathchecked`.
                let dirs: Vec<String> = crate::ported::params::getsparam("PATH")
                    .unwrap_or_default()
                    .split(':')
                    .map(String::from)
                    .collect();
                have = crate::ported::exec::hashcmd(cmd, &dirs);
            }
            if have.is_some() {
                // c:834 / c:861 — `cn->u.cmd` for a HASHED node, else
                // `"<*cn->u.name>/<arg0>"`. `get_full_path` is that arm.
                hashed_prog = crate::ported::hashtable::cmdnamtab_lock()
                    .read()
                    .ok()
                    .and_then(|t| t.get_full_path(cmd))
                    .map(|p| p.display().to_string());
            }
        }
        // c:Src/exec.c:3650-3652 + c:3678-3685 — AUTOCD. With no command
        // found, a one-word command with no redirections, in a shell
        // reading commands from its input (SHINSTDIN), that names a
        // directory — or, under CDABLEVARS, a parameter or user whose value
        // or home is one — runs as `cd -- DIR`:
        //     trycd = isset(AUTOCD) && isset(SHINSTDIN) && (!redir ||
        //             empty(redir)) && args && !empty(args) &&
        //             !nextnode(firstnode(args)) && *peekfirst(args);
        //     if (!hn && trycd && (s = cancd(peekfirst(args)))) { … "cd" … }
        // The ported execcmd_exec carries this; the compiled path every
        // literal command takes reaches only here, so `tmp` from `/`,
        // `/tmp` or a CDABLEVARS name reported "command not found".
        if hashed_prog.is_none()
            && defpath == 0
            && args.is_empty()
            && !cmd.is_empty()
            && crate::ported::zsh_h::isset(crate::ported::zsh_h::AUTOCD)
            && crate::ported::zsh_h::isset(crate::ported::zsh_h::SHINSTDIN)
            && !crate::fusevm_bridge::own_redirect_scope(self)
        {
            if let Some(dir) = crate::ported::exec::cancd(cmd) {
                return Ok(crate::fusevm_bridge::dispatch_builtin_raw(
                    "cd",
                    vec!["--".to_string(), dir],
                ));
            }
        }
        // c:Src/exec.c:810-828 — `/* for command -p, search the default path */
        //     if (defpath) {
        //         char pbuf[MAXCMDLEN];
        //         if (!search_defpath(arg0, pbuf, MAXCMDLEN)) {
        //             if (commandnotfound(arg0, args) == 0) _realexit();
        //             zerr("command not found: %s", arg0);
        //             _exit(127);
        //         }
        //         ee = zexecve(pbuf, argv, newenvp);
        //     } else { … cmdnamtab / $path walk … }`
        //
        // The two arms are mutually exclusive in C, so under `-p` the exec'd
        // pathname is the DEFAULT_PATH hit and nothing else — no `$path` walk,
        // no bare-name retry, and a miss is final even when the name sits on
        // `$PATH`. The `cmdnamtab` population above still runs because it is
        // NOT part of `execute()`: it belongs to `execcmd_exec` in the parent
        // (c:3671-3674), which hashes `cmdarg` against `$path` regardless of
        // `use_defpath`. That asymmetry is visible in the oracle — after
        // `PATH=<dir-with-a-fake-awk>:…; command -p awk`, the REAL
        // `/usr/bin/awk` runs while the table records the fake one.
        //
        // c:798-808 runs before this and execs a `/`-bearing arg0 directly, so
        // `defpath` never applies to a name the user spelled as a path.
        let mut defpath_prog: Option<String> = None;
        if defpath != 0 && !cmd.contains('/') {
            // c:815 — `if (!search_defpath(arg0, pbuf, MAXCMDLEN))`
            match crate::ported::exec::search_defpath(cmd, libc::PATH_MAX as usize) {
                // c:822 — `ee = zexecve(pbuf, argv, newenvp)`
                Some(pbuf) => defpath_prog = Some(pbuf),
                None => {
                    // c:816-817 — `if (commandnotfound(arg0, args) == 0)
                    // _realexit();`. The `command_not_found_handler` hook
                    // runs for a default-path miss exactly as it does for a
                    // `$path` miss, and its status is the command's status.
                    // The `$path` miss reaches the same hook from the ENOENT
                    // arm further down, after the spawn has failed; there is
                    // no spawn to fail here, so the call is explicit.
                    let mut hook_args = Vec::with_capacity(args.len() + 1);
                    hook_args.push(cmd.to_string());
                    hook_args.extend_from_slice(args);
                    if let Some(rc) =
                        self.dispatch_function_call("command_not_found_handler", &hook_args)
                    {
                        return Ok(rc);
                    }
                    let sn = crate::ported::utils::scriptname_get()
                        .unwrap_or_else(|| "zshrs".to_string());
                    // c:818 — `zerr("command not found: %s", arg0)`. Emitted
                    // directly rather than through `zerr` for the same reason
                    // as the PATH-unset arm above: command-not-found is
                    // non-fatal and must not raise errflag.
                    eprintln!("{}: command not found: {}", zerr_prefix(&sn), crate::ported::utils::nicedupstring(&cmd));
                    return Ok(127); // c:819 `_exit(127)`
                }
            }
        }
        // c:Src/exec.c:758-776 — "If ARGV0 is in the commands environment, we
        // use that as argv[0] for this external command" and unsetenv it; else
        // "if the pre-command `-' was given, we add `-' to the front of
        // argv[0] for this command."
        let carrier = crate::fusevm_bridge::take_exec_carrier();
        let job_text = crate::fusevm_bridge::take_job_text();
        let exec_dash = carrier & crate::fusevm_bridge::EXEC_CARRIER_DASH != 0;
        // c:Src/exec.c:4369 — this process was forked for the command
        // (BUILTIN_EXEC_FORKED_SIMPLE): exec it here rather than spawn.
        //
        // !!! WARNING: RUST-ONLY !!! C's multio helpers are forked tee/cat
        // processes (closemn, c:Src/exec.c:2288), so they outlive the execve
        // that replaces the shell. zshrs runs them as threads of the shell
        // (multios_scope_stack), and an execve kills every thread: the
        // concatenator of `cat <o1 <<<x` died before writing (cat read EOF)
        // and the splitter of `/bin/echo hi >a >b` left the command writing
        // into a pipe nobody reads (SIGPIPE, both files empty). While any
        // such thread is live the command is spawned and waited for instead,
        // which lets the threads finish before the shell exits. The command
        // still takes the shell's place for SHLVL, as it does in C.
        let exec_forked = !background && carrier & crate::fusevm_bridge::EXEC_CARRIER_FORKED != 0;
        let multio_threads_live = self.multios_scope_stack.iter().any(|scope| !scope.is_empty());
        let in_place = exec_forked && !multio_threads_live;
        if exec_forked && carrier & crate::fusevm_bridge::EXEC_CARRIER_SHLVL != 0 {
            crate::fusevm_bridge::exec_shlvl_decrement(); // c:Src/exec.c:4334-4336
        }
        let argv0_env = std::env::var("ARGV0").ok(); // c:760 zgetenv("ARGV0")
        let mut argv: Vec<String> = Vec::with_capacity(args.len() + 1);
        argv.push(match &argv0_env {
            Some(z) => z.clone(),                      // c:761
            None if exec_dash => format!("-{}", cmd), // c:775-776
            None => cmd.to_string(),
        });
        argv.extend_from_slice(args);

        // c:Src/jobs.c — `time` reports only on JOBS (forked work). This
        // is the single chokepoint where an external process is actually
        // spawned (both fg and bg, all callers), AFTER the
        // command-not-found and resolvebuiltin early-returns above — so
        // counting here makes BUILTIN_TIME_SUBLIST report `time sleep 0`
        // / `time /usr/bin/true` (external → fork) while staying silent
        // for `time true` (builtin, never reaches this point). The
        // subshell entry counts separately (fusevm_bridge.rs:9573).
        FORK_EVENTS.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
        // c:Src/exec.c:4352 `closem(FDT_INTERNAL, 0)` before execve.
        crate::lowfd::cloexec_internal_fds();

        // Redirect handling lives in fusevm's WithRedirectsBegin/End
        // ops at compile time; `_redirects` arrives empty here.
        let spawned = if background {
            execute_spawn(cmd, &argv, defpath_prog.as_deref(), hashed_prog.as_deref(), argv0_env.is_some(), false)
                .map_err(|eno| (eno, None))
        } else {
            // Queue signals across the wait so zshrs's SIGCHLD reaper
            // (waitpid(-1) in wait_for_processes, delivered on any thread)
            // can't reap this child before the wait does, and claim the
            // status back when it wins anyway — see foreground_status.
            let _wait_guard = crate::fusevm_bridge::ForegroundWaitGuard::enter();
            match execute_spawn(cmd, &argv, defpath_prog.as_deref(), hashed_prog.as_deref(), argv0_env.is_some(), in_place) {
                Ok(pid) => match crate::fusevm_bridge::wait_pid_status(pid) {
                    Ok(status) => {
                        use std::os::unix::process::ExitStatusExt as _;
                        drop(_wait_guard);
                        // c:Src/jobs.c:645-650 — update_job reports the finished job.
                        crate::exec_jobs::foreground_job_report(
                            status.into_raw(),
                            job_text,
                            !self.subshell_snapshots.is_empty(),
                        );
                        // c:Src/jobs.c:654-679 — update_job's foreground tail.
                        crate::exec_jobs::foreground_job_signalled(status.into_raw());
                        return Ok(crate::exec_jobs::wait_status_val(status));
                    }
                    Err(e) => Err((0, Some(e))),
                },
                Err(eno) => Err((eno, None)),
            }
        };
        let sn = crate::ported::utils::scriptname_get().unwrap_or_else(|| "zshrs".to_string());
        let eno = match spawned {
            Ok(pid) => {
                let cmd_str = format!("{} {}", cmd, args.join(" "));
                let job_id = self.jobs.add_pid_job(pid, cmd_str, JobState::Running);
                println!("[{}] {}", job_id, pid);
                return Ok(0);
            }
            Err((_, Some(e))) => return Err(format!("{}: {}: {}", sn, cmd, e)),
            Err((eno, None)) => eno,
        };
        // c:Src/exec.c:871-881 — `if (eno) zerr("%e: %s", eno, arg0); else
        // if (commandnotfound(arg0, args) == 0) _realexit(); else
        // zerr("command not found: %s", arg0); _exit((eno == EACCES || eno
        // == ENOEXEC) ? 126 : 127);`. Emitted directly rather than through
        // `zerr`: C prints from the doomed child, so the parent's errflag is
        // never raised and the script continues.
        if eno != 0 {
            eprintln!(
                "{}: {}: {}",
                zerr_prefix(&sn),
                crate::ported::utils::zsh_errno_msg(eno),
                cmd
            );
            return Ok(if eno == libc::EACCES || eno == libc::ENOEXEC { 126 } else { 127 });
        }
        // c:873 — the `command_not_found_handler` user hook; its status is
        // the command's status. Documented in zshmisc(1) under "Special
        // Functions". Bug #426.
        if !background {
            let mut hook_args = Vec::with_capacity(args.len() + 1);
            hook_args.push(cmd.to_string());
            hook_args.extend_from_slice(args);
            if let Some(rc) = self.dispatch_function_call("command_not_found_handler", &hook_args) {
                return Ok(rc);
            }
        }
        // Inline Rust FFI export: consulted after builtins, functions, PATH
        // search, and command_not_found_handler have all missed — real
        // commands keep priority. In the background an in-process FFI call
        // has nothing to background, so it runs synchronously.
        if let Some(rc) = self.try_registered_ffi_command(cmd, args) {
            return Ok(rc);
        }
        eprintln!("{}: command not found: {}", zerr_prefix(&sn), crate::ported::utils::nicedupstring(&cmd));
        Ok(127)
    }
    /// !!! WARNING: RUST-ONLY — NO C COUNTERPART !!!
    /// Inline Rust FFI fallback: when `cmd` names a function exported by a
    /// `rust { ... }` block (registered by the `__rust_compile` builtin) run it
    /// as a command. Consulted only when `cmd` resolved to nothing else — not a
    /// builtin, function, plugin, external on `$PATH`, or
    /// `command_not_found_handler` — so real commands keep priority. Positional
    /// args are marshalled as strings; fusevm coerces each to the export's
    /// signature (`i64` / `f64` / `*const c_char`). The return value is printed
    /// to stdout (the redirect-aware process fd 1) and the command exits 0.
    /// Bare names only — a `/`-qualified token is a filesystem path, never an
    /// FFI export. Returns `None` when `cmd` is not a registered export, so the
    /// caller emits its normal "command not found".
    fn try_registered_ffi_command(&self, cmd: &str, args: &[String]) -> Option<i32> {
        if cmd.contains('/') || !fusevm::ffi::is_registered(cmd) {
            return None;
        }
        let vals: Vec<fusevm::Value> = args.iter().map(|a| fusevm::Value::str(a.clone())).collect();
        match fusevm::ffi::try_call(cmd, &vals) {
            Some(Ok(v)) => {
                use std::io::Write as _;
                let mut out = io::stdout().lock();
                let _ = writeln!(out, "{}", v.to_str());
                let _ = out.flush();
                Some(0)
            }
            Some(Err(e)) => {
                eprintln!("zshrs: {e}");
                Some(1)
            }
            // Registered a moment ago but the entry vanished (registry race) —
            // treat as unresolved and let the caller report command-not-found.
            None => None,
        }
    }

    /// 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);
        // Context-isolated nested parse (c:Src/exec.c:283 parse_string) —
        // same rationale as run_command_substitution: process-sub argv
        // extraction runs during execution and must not clobber the outer
        // single-event reader's lexer/input position.
        let prog = parse_isolated(cmd_str);
        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);
                    singsub(&untoked)
                })
                .collect()
        } else {
            Vec::new()
        }
    }
    /// `run_command_substitution` — see implementation.
    /// The SQLite mirror, opened the first time anything asks for it.
    ///
    /// Returns `None` when no cache file exists yet (or it failed to open),
    /// which is the same answer the eager constructor produced.
    pub fn compsys_cache(&self) -> Option<&CompsysCache> {
        self.compsys_cache
            .get_or_init(|| {
                let cache_path = crate::compsys::cache::default_cache_path();
                if !cache_path.exists() {
                    tracing::debug!("compsys: no cache at {}", cache_path.display());
                    return None;
                }
                let db_size = 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 mirror opened (dbview/SQL inspection only; rkyv shards are the authoritative cache)"
                        );
                        Some(c)
                    }
                    Err(e) => {
                        tracing::warn!(error = %e, "compsys: failed to open cache");
                        None
                    }
                }
            })
            .as_ref()
    }

    pub fn run_command_substitution(&mut self, cmd_str: &str) -> String {
        // c:Src/subst.c / Src/lex.c — the text inside `$(…)` is a FRESH
        // command line. The double quotes that may surround the substitution
        // apply to its RESULT, not to the words inside it: in `"$(f $x)"` the
        // `$x` is unquoted. `in_dq_context` is the runtime signal the
        // `${(flags)…}` bridges read for paramsubst's `qt` (c:1625), and it
        // stayed set for the whole body, so every flag-expansion inside a
        // DQ command substitution ran as if quoted.
        //
        // What that broke: `qt` suppresses RC_EXPAND_PARAM's word removal, so
        // under `setopt rcexpandparam` an EMPTY array kept a word instead of
        // deleting it (c:4327's `while ((x = *aval++))` emits nothing for an
        // empty array; the `!plan9` single-empty-word path at c:4261 is the
        // one that must NOT run):
        //     setopt rcexpandparam
        //     f() { declare -a x; print "n=$(set -- H ${(q)x}; print $#)" }
        //     f            # zsh: n=1, zshrs was n=2
        // Only the `"$(…)"` spelling was affected — unquoted `$(…)`,
        // backticks, and `v=$(…)` were all already correct, which is what
        // made it look like a quoting bug rather than an option bug.
        //
        // Bit through compsys: completion runs with rcexpandparam ON, and
        // `_git`'s __git_recent_commits passes `${(q)commit_opts}` to
        // `_call_program` inside `"$(…)"`. The stray empty word became a
        // bogus `''` argument to `git rev-list`, the command failed, and
        // `git checkout <TAB>` lost its whole recent-commits group.
        //
        // `SUBEXP_SCALAR_CTX` carries the same thing one level down — it is
        // what a NESTED expansion reads as `subexp_dq` (subst.rs:18873) to
        // learn that its OUTER `${…}` was quoted. A `$(…)` inside a quoted
        // outer expansion is still a fresh command line, so it has to be
        // cleared too:
        //     setopt rcexpandparam
        //     f() { declare -a co; local -a c
        //           c=("${(f)"$(cmd HEAD ${(q)co})"}") }
        // is `_git`'s exact shape, and the leaked context flipped c:4354's
        // `mark_empty`, keeping the empty element that plan9 must delete.
        let saved_dq = std::mem::replace(&mut self.in_dq_context, 0);
        let saved_subexp = crate::ported::subst::SUBEXP_SCALAR_CTX.with(|c| c.replace(0));
        let out = self.run_command_substitution_inner(cmd_str, false);
        crate::ported::subst::SUBEXP_SCALAR_CTX.with(|c| c.set(saved_subexp));
        self.in_dq_context = saved_dq;
        out
    }

    /// ksh93 funsub `${ list; }` / mksh valsub `${| list; }` — capture the
    /// output of `cmd_str` WITHOUT the subshell isolation `$( … )` applies.
    ///
    /// ksh(1), Command Substitution: "${ command;} … the command is
    /// executed in the current shell environment", so an assignment or a
    /// `cd` inside survives:
    ///   `ksh -c 'x=0; y=${ x=5; print -n out; }; print "x=$x y=$y"'`
    ///   → `x=5 y=out`, where the same body in `$( … )` leaves `x` at 0.
    /// mksh behaves identically for both of its forms.
    ///
    /// Same capture machinery as `$( … )` — only the parent-state
    /// snapshot/restore is skipped, which is exactly the difference the
    /// two references document.
    ///
    /// !!! RUST-ONLY ENTRY POINT — zsh has no funsub/valsub !!!
    pub fn run_shared_state_substitution(&mut self, cmd_str: &str) -> String {
        let saved_dq = std::mem::replace(&mut self.in_dq_context, 0);
        let saved_subexp = crate::ported::subst::SUBEXP_SCALAR_CTX.with(|c| c.replace(0));
        let out = self.run_command_substitution_inner(cmd_str, true);
        crate::ported::subst::SUBEXP_SCALAR_CTX.with(|c| c.set(saved_subexp));
        self.in_dq_context = saved_dq;
        out
    }

    /// `shared_state`: skip the parent-state snapshot/restore that makes
    /// `$( … )` a subshell. Only the ksh/mksh funsub-valsub entry point
    /// passes true.
    fn run_command_substitution_inner(&mut self, cmd_str: &str, shared_state: bool) -> 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();
            // c:Src/lex.c — the `$(<file)` shortcut ONLY applies when
            // the body is exactly `<` + ONE word. Anything else (extra
            // args, redirects, semicolons, pipes) is a regular command
            // list and must go through the full parse path so `2>/dev/null`
            // / `>file` / `|cmd` / `; next` etc. work. Without this
            // gate, `$(< file 2>/dev/null)` treated `file 2>/dev/null`
            // as the literal filename and errored on the missing file.
            // Bug #615.
            let is_single_word = !filename.is_empty()
                && !filename.chars().any(|c| {
                    matches!(
                        c,
                        ' ' | '\t'
                            | '\n'
                            | ';'
                            | '&'
                            | '|'
                            | '<'
                            | '>'
                            | '('
                            | ')'
                            | '`'
                            | '"'
                            | '\''
                    )
                });
            if is_single_word {
                // Expand any leading $ / tilde in the filename so
                // `$(< $f)` and `$(< ~/x)` work.
                let resolved = if filename.contains('$') || filename.starts_with('~') {
                    singsub(filename)
                } else {
                    filename.to_string()
                };
                let resolved = resolved.to_string();
                // c:Src/exec.c `readoutput` — `$(<file)` reads the file a
                // BYTE at a time and metafies (`if (imeta(c)) { *ptr++ =
                // Meta; ... }`); it does not require UTF-8.
                match crate::script_bytes::read_script_file(&resolved) {
                    Ok(contents) => {
                        return contents.trim_end_matches('\n').to_string();
                    }
                    Err(e) => {
                        // c:Src/exec.c:4797-4800 — `zwarn("%e: %s", errno, s);
                        // lastval = cmdoutval = 1; return newlinklist();`.
                        // zwarn carries the real `<script>:<line>:` prefix.
                        crate::ported::utils::zwarn(&format!(
                            "{}: {}",
                            crate::ported::utils::zsh_errno_msg(
                                e.raw_os_error().unwrap_or(libc::ENOENT)
                            ),
                            resolved
                        ));
                        self.set_last_status(1); // c:4799
                        crate::ported::exec::cmdoutval.store(1, Ordering::Relaxed);
                        return String::new();
                    }
                }
            }
            // Multi-word / has-redirects → fall through to full parse.
        }

        // Port of getoutput(char *cmd, int qt) from Src/exec.c. Parse and compile via
        // the lex+parse free ported + ZshCompiler pipeline, run on a
        // sub-VM with the host wired up. Stdout is captured through
        // an in-process pipe via dup2 — no fork. 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.
        //
        // c:Src/exec.c:4753 — `if (mpipe(pipes) < 0)`. mpipe (c:5160)
        // moves BOTH pipe ends to fd >= 10 via movefd and marks them
        // FDT_INTERNAL. This is load-bearing: zsh's invariant is that
        // shell-internal fds never live below 10, so user redirections
        // like `exec 9>&-` (which close fd<10 unconditionally, no
        // FDT_INTERNAL guard — c:Src/exec.c:3856-3868) can never hit
        // them. A raw pipe() here landed the read end on fd 9 when
        // fresh-HOME init held fds 3-7, and A04redirect's %prep
        // `exec 9>&-` closed our own capture pipe → SIGPIPE killed
        // the whole shell.
        let (read_fd, write_fd) = {
            let mut fds = [0i32; 2];
            if crate::ported::exec::mpipe(&mut fds) < 0 {
                return String::new();
            }
            // The read end stays open while the body runs in process; C's
            // forked body closes it (c:Src/exec.c:4839), so it must not sit
            // where the body's `{var}` allocations land.
            (crate::lowfd::movefd_past_script(fds[0]), fds[1])
        };
        // c:Src/utils.c:1996 — `movefd(dup(fd))`: saved copies of the
        // user-visible fds are shell-internal (FDT_INTERNAL), and since
        // they exist only for the in-process body they sit past the
        // script's `{var}` range too (movefd_past_script).
        // A CLOSED stdout saves as -1 and is closed again on the way out
        // (c:Src/utils.c:2047-2048 redup `if (x < 0) zclose(y)`). C's forked
        // getoutput child needs no save at all (c:4840 `redup(pipes[1], 1)`),
        // so the body runs either way: bailing out here lost everything the
        // body did, `{ x=$(print b >&2) } >&-` never printed `b`.
        let saved_stdout =
            crate::lowfd::movefd_past_script(unsafe { libc::dup(libc::STDOUT_FILENO) });
        // Flush Rust's stdout BufWriter against the ORIGINAL fd before
        // dup2 swaps fd 1 to the capture pipe. Without this, bytes left
        // buffered by a prior `print -n` get drained to fd 1 AFTER the
        // dup2, which routes them into the cmd-subst's pipe — they end
        // up in the captured result and disappear from terminal output.
        //
        // Bug #10 in docs/BUGS.md — `print -n "A"; v=$(true); print -n
        // "B"; v=$(true); print -n "C"; echo` printed only `C` because
        // `A` and `B` were redirected into the empty cmd-subst's pipe
        // and discarded as its "output". C zsh's getoutput() forks, so
        // the child inherits the buffer COPY and the parent's buffer
        // stays untouched; zshrs runs cmd-subst in-process so the
        // parent buffer is the only one — must flush before the swap.
        let _ = io::stdout().flush();
        // c:Bug #56 — publish the saved outer stdout so a trap firing
        // during the nested run routes body output to the parent's
        // real stdout instead of the cmdsub's pipe-bound fd 1.
        // Same as saved_stdout above.
        let saved_stderr_for_trap =
            crate::lowfd::movefd_past_script(unsafe { libc::dup(libc::STDERR_FILENO) });
        // A job the body forks must not keep them: they belong to the
        // parent C never forked the body from (see mark_saved_fd).
        crate::fusevm_bridge::mark_saved_fd(saved_stdout);
        crate::fusevm_bridge::mark_saved_fd(saved_stderr_for_trap);
        crate::fusevm_bridge::CMDSUBST_OUTER_FDS
            .with(|s| s.borrow_mut().push((saved_stdout, saved_stderr_for_trap)));
        unsafe {
            libc::dup2(write_fd, libc::STDOUT_FILENO);
        }
        // zclose (not raw close) so the FDT_INTERNAL mark set by mpipe
        // is cleared from fdtable — c:Src/utils.c:2137.
        crate::ported::utils::zclose(write_fd);

        // Drain the capture pipe CONCURRENTLY on a background reader
        // thread. The sub-VM (and any children it forks, which inherit
        // fd 1) writes to the pipe; reading it only AFTER vm.run()
        // returns deadlocks the moment the output exceeds the OS pipe
        // buffer (~64KB): the writer blocks on a full pipe that nothing
        // is draining, so vm.run() never returns. `$(alias)` over
        // zpwr's 2000+ aliases (~177KB) hung the whole shell a few
        // prompts in (thefuck's `fuck()` init runs `TF_SHELL_ALIASES=
        // $(alias)`). C's getoutput (Src/exec.c) forks the writer child
        // so the parent reads concurrently; this reader thread is the
        // in-process analog. It does only raw fd reads (no shell state /
        // thread-locals). EOF arrives once every write end closes — fd 1
        // restored below plus any forked child exiting.
        let reader_handle = std::thread::spawn(move || {
            let mut buf: Vec<u8> = Vec::new();
            let mut chunk = [0u8; 65536];
            loop {
                let n = unsafe {
                    libc::read(
                        read_fd,
                        chunk.as_mut_ptr() as *mut libc::c_void,
                        chunk.len(),
                    )
                };
                if n < 0 {
                    // Retry on EINTR (a signal interrupted the read);
                    // any other error ends the drain.
                    let e = std::io::Error::last_os_error().raw_os_error().unwrap_or(0);
                    if e == libc::EINTR {
                        continue;
                    }
                    break;
                }
                if n == 0 {
                    break; // EOF — all write ends closed.
                }
                buf.extend_from_slice(&chunk[..n as usize]);
            }
            buf
        });

        // c:Src/exec.c:1161 — forked cmdsub child runs entersubsh()
        // which does `zsh_subshell++`; in-process equivalent (RAII,
        // restored on every return path below).
        // A funsub/valsub is NOT a subshell — ksh(1) says the command runs
        // "in the current shell environment" — so it must not bump the
        // nesting counter `$ZSH_SUBSHELL` / `$BASH_SUBSHELL` reads.
        let _subshell_bump = if shared_state {
            None
        } else {
            Some(crate::fusevm_bridge::CmdSubstSubshellBump::enter())
        };

        // c:Src/exec.c:1208-1209 — the same forked child clears
        // `opts[USEZLE]` and `zleactive`. Without it a substitution run
        // from inside a widget still looks "in ZLE", so `fc` refuses with
        // "no interactive history within ZLE" (c:Src/builtin.c:1523-1527)
        // and history-based completers come back empty. Placed here rather
        // than in exec::getoutput so the bridge's own cmdsubst paths
        // (BUILTIN_CMD_SUBST_TEXT, backtick) are covered too.
        let _subsh_state = crate::ported::exec::SubshStateGuard::enter();

        // 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.
        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 = 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) nested_lineno_base maps
        // inner line N → outer_lineno + (N - 1), outer 0 included.
        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);
        // Context-isolated nested parse (c:Src/exec.c:283 parse_string).
        // The outer loop()/parse_event reader may be mid-stream when this
        // cmd-subst executes (single-event mode), so a destructive
        // parse_init/lex_init would clobber its next read. parse_isolated
        // brackets the parse with zcontext_save/restore + inpush/inpop.
        let parsed = parse_isolated_at(cmd_str, Some(outer_lineno)); // c:4778 parse_string(cmd, 0)
        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.nested_lineno_base = Some(outer_lineno); // c:Src/exec.c:4778
            let chunk = compiler.compile(&prog);
            if !chunk.ops.is_empty() {
                crate::fusevm_disasm::maybe_print_stdout("run_command_substitution", &chunk);
                // c:Src/exec.c:4783 — `$(...)` runs in a subshell, so
                // assignments / setopt / cd / trap changes inside
                // mustn't leak to the parent. zsh forks; we run
                // in-process and snapshot/restore manually. Same
                // snapshot shape used by host_subshell_begin/end for
                // the `(...)` subshell form.
                let paramtab_snap = crate::ported::params::paramtab()
                    .read()
                    .ok()
                    .map(|t| t.clone())
                    .unwrap_or_default();
                let paramtab_hashed_snap = crate::ported::params::paramtab_hashed_storage()
                    .lock()
                    .ok()
                    .map(|m| m.clone())
                    .unwrap_or_default();
                let pparams_snap = self.pparams();
                let opts_snap = crate::ported::options::opt_state_snapshot();
                // c:Src/exec.c:1161 — a command substitution runs in a
                // subshell, so IFS changes inside it must NOT leak to the
                // parent. IFS lives in the external `ifs_lock` global (not
                // paramtab), so the paramtab snapshot above doesn't cover
                // it: `echo $(IFS=:; set -- a b c; echo "$*")` set IFS=":"
                // which both produced "a:b:c" AND then word-split the
                // UNQUOTED result on the leaked ":" → "a b c". Snapshot the
                // global IFS here and restore it (with inittyptab) below.
                let ifs_snap = crate::ported::params::ifs_lock()
                    .lock()
                    .map(|g| g.clone())
                    .unwrap_or_default();
                let traps_snap = crate::ported::builtin::traps_table()
                    .lock()
                    .map(|t| t.clone())
                    .unwrap_or_default();
                // c:Src/exec.c:4783 — function definitions / unfunction
                // inside `$(...)` must also be isolated from the parent.
                // C zsh's getoutput() forks, so the child's shfunctab
                // mutations die with the child. zshrs's in-process
                // cmd-subst needs to snapshot/restore the function
                // tables manually alongside the param/opts/trap snaps
                // already in this block. Bug #455.
                let shfunctab_snap = crate::ported::hashtable::shfunctab_lock()
                    .read()
                    .ok()
                    .map(|t| t.snapshot())
                    .unwrap_or_default();
                let functions_compiled_snap = self.functions_compiled.clone();
                let function_source_snap = self.function_source.clone();
                // c:Src/exec.c:4816 — what the forked child owns a copy of:
                // hash tables, `environ`, cwd, umask, rlimits, …; see
                // SubshForkCopy.
                // A funsub/valsub runs in the current shell and keeps it all.
                let tables_snap = (!shared_state).then(crate::ported::exec::SubshForkCopy::save);
                let locale_snap = (!shared_state).then(subsh_locale_save).flatten();
                let fd_frame = (!shared_state).then(crate::ported::exec::SubshFdFrame::enter);
                // c:Src/exec.c:1127-1131 — the child's `entersubsh` unsets
                // every trap that is not function-form (`$(trap)` lists
                // nothing), in ITS copy of `sigtrapped[]`. Keep the
                // parent's for the restore, and route signals that arrive
                // meanwhile to it — same as `( … )`, see
                // fusevm_bridge::subshell_defer_signal.
                let sigtrapped_snap = (!shared_state).then(|| {
                    let parent = crate::ported::signals::sigtrapped
                        .lock()
                        .map(|g| g.clone())
                        .unwrap_or_default();
                    crate::fusevm_bridge::subshell_signal_enter();
                    crate::fusevm_bridge::entersubsh_reset_traps();
                    parent
                });
                // c:Src/exec.c:4782 — getoutput's child runs
                // `entersubsh(ESUB_PGRP|ESUB_NOMONITOR)`, and c:1219
                // `if (flags & ESUB_PGRP) clearjobtab(monitor)` hands
                // that child an EMPTY job table. The oldjobtab snapshot
                // (c:Src/jobs.c:1800) is monitor-only, so a
                // non-interactive shell keeps nothing at all — which is
                // why zsh prints nothing for `sleep 5 & print $(jobs)`.
                // The `(...)` and pipeline-stage paths already call
                // clearjobtab in their forked children; cmd-subst runs
                // in-process, so snapshot the globals clearjobtab
                // mutates and restore them below. freejob (c:1457) is
                // struct-local — no waitpid/kill — so the restore is
                // exact.
                // c:Src/exec.c:4782 — same fork, one more thing it copies:
                // the completion-match arena (c:Src/Zle/compcore.c:124-259).
                // A `compadd` run inside `$(…)` lands in the CHILD's
                // `matches`/`amatches`/`mgroup`, which die with it, so the
                // completing parent never sees those matches. zshrs's
                // in-process cmd-subst shares the arena, so `_tmux`'s
                // `desc="$(_tmux-backup)"` description probe leaked five
                // whole completion groups into `tmux <TAB>` (551 matches vs
                // zsh's 450). Snapshot/restore it by hand, exactly as the
                // param/opts/trap/job snaps above do.
                let comp_arena_snap = crate::comp_match_handles::comp_arena_save();
                // !!! WARNING: RUST-ONLY LOCK DISCIPLINE !!! zhandler's SIGCHLD
                // branch locks JOBTAB (c:Src/signals.c:429-431 → update_bg_job)
                // on whichever thread the signal interrupts. C's jobtab is a
                // plain array; here a SIGCHLD landing while this thread holds
                // the JOBTAB mutex (the snapshot, clearjobtab, and the restore
                // below, which also drops the child's table under the lock)
                // blocks the handler forever: `echo $(echo a &) w` hung.
                // Queue signals across both windows (c:Src/signals.c:410-424).
                crate::ported::signals_h::queue_signals();
                let jobtab_snap = crate::ported::jobs::JOBTAB
                    .get()
                    .and_then(|t| t.lock().ok().map(|g| g.clone()));
                let maxjob_snap = crate::ported::jobs::MAXJOB
                    .get()
                    .and_then(|m| m.lock().ok().map(|g| *g));
                let thisjob_snap = crate::ported::jobs::THISJOB
                    .get()
                    .and_then(|t| t.lock().ok().map(|g| *g));
                // curjob/prevjob (c:Src/jobs.c) are plain globals in C,
                // so the forked child's setcurjob calls never reach the
                // parent — restore them alongside the table, else the
                // `+`/`-` markers are lost after a `$(jobs)`.
                let curjob_snap = crate::ported::jobs::CURJOB
                    .get()
                    .and_then(|t| t.lock().ok().map(|g| *g));
                let prevjob_snap = crate::ported::jobs::PREVJOB
                    .get()
                    .and_then(|t| t.lock().ok().map(|g| *g));
                // Pipeline job slots the body takes come from the cleared
                // table below; their records go when the parent's comes back.
                let slots_snap = crate::exec_jobs::execpline_slots_mark();
                {
                    let monitor = crate::ported::zsh_h::isset(crate::ported::zsh_h::MONITOR) as i32;
                    crate::ported::jobs::clearjobtab(&mut self.jobs, monitor);
                }
                crate::ported::signals_h::unqueue_signals();
                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();
                // `exit N` inside a cmd-subst should terminate ONLY
                // the sub-shell (C zsh: cmd-subst forks, the child
                // `_exit(N)`s; status reaches the parent as
                // cmd-subst exit). zshrs runs in-process, so we
                // route through the SUBSHELL_DEPTH-gated deferred
                // path inside zexit (builtin.rs:7713): bump
                // SUBSHELL_DEPTH so `exit` sets EXIT_PENDING/
                // EXIT_VAL instead of calling realexit (which would
                // process::exit and kill the parent shell). After
                // the sub-VM returns, harvest EXIT_PENDING/EXIT_VAL
                // as the cmd-subst's status, then restore the
                // parent's flags so the outer VM continues normally.
                use crate::ported::builtin::{
                    BREAKS, EXIT_PENDING, EXIT_VAL, RETFLAG, SHELL_EXITING, SUBSHELL_DEPTH,
                };
                use std::sync::atomic::Ordering::Relaxed;
                let saved_exit_pending = EXIT_PENDING.swap(0, Relaxed);
                let saved_exit_val = EXIT_VAL.swap(0, Relaxed);
                let saved_shell_exiting = SHELL_EXITING.swap(0, Relaxed);
                let saved_retflag = RETFLAG.swap(0, Relaxed);
                let saved_breaks = BREAKS.swap(0, Relaxed);
                // c:Src/exec.c:4784 — `execode(prog, 0, 1, "cmdsubst");`.
                // execode (c:1245-1266) APPENDS its `context` argument to
                // `zsh_eval_context` for the duration of the body, so code
                // inside `$(…)` / backticks sees `cmdarg:cmdsubst` where the
                // top level sees just `cmdarg`. zshrs pushed "shfunc" at the
                // function-call site but never pushed "cmdsubst", so
                // `$(print $ZSH_EVAL_CONTEXT)` reported `cmdarg` and
                // `$(f)` reported `cmdarg:shfunc` instead of
                // `cmdarg:cmdsubst:shfunc`. Popped on every return path by the
                // guard below, mirroring execode's stack discipline.
                // Bug #1065.
                let sync_eval_ctx = |stack: &[String]| {
                    let joined = stack.join(":");
                    if let Ok(mut tab) = crate::ported::params::paramtab().write() {
                        if let Some(pm) = tab.get_mut("zsh_eval_context") {
                            pm.u_arr = Some(stack.to_vec());
                            pm.node.flags &= !(crate::ported::zsh_h::PM_UNSET as i32);
                        }
                        if let Some(pm) = tab.get_mut("ZSH_EVAL_CONTEXT") {
                            pm.u_str = Some(joined);
                            pm.node.flags &= !(crate::ported::zsh_h::PM_UNSET as i32);
                        }
                    }
                };
                if let Ok(mut ctx) = crate::ported::exec::zsh_eval_context.lock() {
                    ctx.push("cmdsubst".to_string());
                    sync_eval_ctx(&ctx);
                }
                struct CmdsubstEvalCtxGuard<F: Fn(&[String])>(F);
                impl<F: Fn(&[String])> Drop for CmdsubstEvalCtxGuard<F> {
                    fn drop(&mut self) {
                        if let Ok(mut ctx) = crate::ported::exec::zsh_eval_context.lock() {
                            ctx.pop();
                            (self.0)(&ctx);
                        }
                    }
                }
                let _cs_eval_ctx_guard = CmdsubstEvalCtxGuard(sync_eval_ctx);
                SUBSHELL_DEPTH.fetch_add(1, Relaxed);
                let _ctx = ExecutorContext::enter(self);
                let _ = vm.run();
                let inner_exit_pending = EXIT_PENDING.load(Relaxed);
                let inner_exit_val = EXIT_VAL.load(Relaxed);
                let inner_status = if inner_exit_pending != 0 {
                    inner_exit_val & 0xFF
                } else {
                    vm.last_status
                };
                cmd_status = Some(inner_status);
                SUBSHELL_DEPTH.fetch_sub(1, Relaxed);
                // c:Src/exec.c — `$(…)` is a FORK in C: an errflag
                // abort inside the child ends the child (its lastval
                // becomes the cmd-subst status) and the flag dies
                // with the child process — the parent's lists keep
                // running. zsh 5.9: `v=$(typeset -A q; q=(odd));
                // echo "after $?"` prints `after 1`. Mirror the fork
                // isolation by clearing ERRFLAG_ERROR at the
                // cmd-subst boundary.
                //
                // ERRFLAG_HARD dies here too: `${u:?msg}` inside the
                // child sets it (c:Src/subst.c:3344) then `_exit(1)`s
                // (c:3353) — C's parent never sees the bit. A leaked
                // HARD bit makes every later zerr() silent
                // (c:Src/utils.c:175-177) and silently fails every
                // later parse. Same fix as subshell_end.
                // A nofork `${ … }` is no fork: c:Src/subst.c:2056 leaves the
                // body's errflag set, so the command around it aborts.
                if !shared_state {
                    errflag.fetch_and(
                        !(ERRFLAG_ERROR | crate::ported::zsh_h::ERRFLAG_HARD),
                        Relaxed,
                    );
                }
                // c:Src/exec.c:4783 execcmdoutsubst — `$(...)` is a
                // subshell, and zsh fires the EXIT trap when the
                // subshell ends BUT only if the trap was installed
                // INSIDE the subshell. An EXIT trap inherited from
                // the parent fires when the parent shell exits, not
                // again at cmdsub end. Detect "installed inside" by
                // comparing the current traps_table["EXIT"] entry
                // against the pre-cmdsub snapshot — fire only when
                // the body differs (newly set, removed, or replaced).
                // Pop the body before execute_script to avoid the
                // re-fire inside execute_script_zsh_pipeline's own
                // EXIT-handler tail at vm_helper.rs:1490. Bug #354.
                let snap_exit = traps_snap.get("EXIT").cloned();
                let live_exit = crate::ported::builtin::traps_table()
                    .lock()
                    .ok()
                    .and_then(|t| t.get("EXIT").cloned());
                if !shared_state && live_exit != snap_exit {
                    if let Some(body) = live_exit {
                        if let Ok(mut t) = crate::ported::builtin::traps_table().lock() {
                            t.remove("EXIT");
                        }
                        let _ = crate::ported::exec::execute_script(&body);
                    }
                }
                // c:Src/signals.c::dotrap(SIGEXIT) — also fire the
                // TRAPEXIT() function-named form (ZSIG_FUNC) — but
                // only if it was defined INSIDE the subshell (the
                // parent's TRAPEXIT fires at parent exit, not here).
                // ZSIG_FUNC bit on sigtrapped[SIGEXIT] tells us
                // whether a TRAPEXIT function is registered; check
                // BEFORE the snapshot restore.
                // Skip for now — function-form detection mirrors the
                // raw-body check above; deferred until a clean
                // sigtrapped snapshot/restore pair exists.
                // Restore parent's exit / loop / function-return
                // state so the outer VM continues normally.
                //
                // A nofork `${ … }` runs in the CURRENT shell, so only `return`
                // stops at it (c:Src/subst.c:2049-2053 `if (retflag) { retflag
                // = 0; breaks = obreaks; }`): an `exit` stays pending for the
                // caller's c:2094 zexit and a `break` keeps unwinding the loop
                // around the command.
                if shared_state {
                    if RETFLAG.load(Relaxed) != 0 {
                        RETFLAG.store(saved_retflag, Relaxed); // c:2051
                        BREAKS.store(saved_breaks, Relaxed); // c:2052
                    }
                } else {
                    EXIT_PENDING.store(saved_exit_pending, Relaxed);
                    EXIT_VAL.store(saved_exit_val, Relaxed);
                    SHELL_EXITING.store(saved_shell_exiting, Relaxed);
                    RETFLAG.store(saved_retflag, Relaxed);
                    BREAKS.store(saved_breaks, Relaxed);
                }
                // Restore parent state. The inner cmd-subst's stdout
                // (the captured pipe contents) is the only thing
                // that leaks out.
                //
                // A funsub/valsub skips ALL of it: that is the entire
                // difference between `${ list; }` and `$(list)`.
                if !shared_state {
                    // First: rolling a module back looks its parameters up
                    // in the LIVE paramtab (see SubshForkCopy::restore).
                    if let Some(snap) = tables_snap {
                        snap.restore();
                    }
                    // Before fd 1 and 2 go back to the parent below.
                    drop(fd_frame);
                    if let Ok(mut t) = crate::ported::params::paramtab().write() {
                        *t = paramtab_snap;
                    }
                    if let Ok(mut m) = crate::ported::params::paramtab_hashed_storage().lock() {
                        *m = paramtab_hashed_snap;
                    }
                    self.set_pparams(pparams_snap);
                    crate::ported::options::opt_state_restore(opts_snap);
                    // Restore the parent's IFS (subshell isolation): the body's
                    // `IFS=` must not leak out and word-split the parent's use
                    // of the cmdsub result. Runtime word-splitting reads the
                    // IFS *string* (this `ifs_lock` global), so restoring it is
                    // sufficient. Deliberately do NOT call inittyptab() here —
                    // that rewrites the process-global typtab the LEXER reads
                    // on every character, and firing it per-cmdsub races
                    // concurrent lexing in zshrs's worker threads, producing
                    // spurious "parse error" flakes (HEAD ran clean 3/3; the
                    // per-cmdsub inittyptab flaked ~50%). The typtab only
                    // affects re-lexing — the parent is already compiled — and
                    // leaving it at the body's value is strictly less divergent
                    // than the prior behavior, which leaked the whole IFS.
                    // Except when the body CHANGED IFS: its `ifssetfn` (or the
                    // unset's c:Src/params.c:4748-4749) already rebuilt the typtab
                    // that word splitting reads, so the parent's table has to come
                    // back with its value (`IFS=:; print $(IFS=,; :); s="p,q";
                    // print -rl -- ${=s}` is one word in zsh). Only that case
                    // rebuilds, so the per-cmdsub race above does not return.
                    let ifs_changed = crate::ported::params::ifs_lock()
                        .lock()
                        .map(|mut g| {
                            let changed = *g != ifs_snap;
                            *g = ifs_snap;
                            changed
                        })
                        .unwrap_or(false);
                    if ifs_changed {
                        crate::ported::utils::inittyptab();
                    }
                    // The body's `LC_ALL=` / `LANG=` changed only the
                    // forked child's locale in C.
                    subsh_locale_restore(locale_snap.as_deref());
                    if let Ok(mut t) = crate::ported::builtin::traps_table().lock() {
                        *t = traps_snap;
                    }
                    // The trap flags, and the `sigaction`s the body installed
                    // for its own traps, go back to the parent's.
                    if let Some(parent) = &sigtrapped_snap {
                        let child = match crate::ported::signals::sigtrapped.lock() {
                            Ok(mut st) => std::mem::replace(&mut *st, parent.clone()),
                            Err(_) => Vec::new(),
                        };
                        crate::fusevm_bridge::subshell_restore_signal_dispositions(parent, &child);
                    }
                    // Restore function tables (parallel to the trap/param
                    // restore above). Bug #455.
                    if let Ok(mut t) = crate::ported::hashtable::shfunctab_lock().write() {
                        t.restore(shfunctab_snap);
                    }
                    self.functions_compiled = functions_compiled_snap;
                    self.function_source = function_source_snap;
                    // Discard anything the substitution added to the completion
                    // arena — the in-process stand-in for the forked child's
                    // address space going away (see comp_arena_save above).
                    crate::comp_match_handles::comp_arena_restore(comp_arena_snap);
                    // Undo the clearjobtab above — in C the cleared table
                    // belongs to the forked child and dies with it, so the
                    // parent's table must come back untouched. Signals stay
                    // queued while the job mutexes are held (see the snapshot).
                    crate::ported::signals_h::queue_signals();
                    if let (Some(js), Some(t)) = (jobtab_snap, crate::ported::jobs::JOBTAB.get()) {
                        if let Ok(mut g) = t.lock() {
                            *g = js;
                        }
                    }
                    if let (Some(mj), Some(m)) = (maxjob_snap, crate::ported::jobs::MAXJOB.get()) {
                        if let Ok(mut g) = m.lock() {
                            *g = mj;
                        }
                    }
                    if let (Some(tj), Some(t)) = (thisjob_snap, crate::ported::jobs::THISJOB.get())
                    {
                        if let Ok(mut g) = t.lock() {
                            *g = tj;
                        }
                    }
                    if let (Some(cj), Some(t)) = (curjob_snap, crate::ported::jobs::CURJOB.get()) {
                        if let Ok(mut g) = t.lock() {
                            *g = cj;
                        }
                    }
                    if let (Some(pj), Some(t)) = (prevjob_snap, crate::ported::jobs::PREVJOB.get())
                    {
                        if let Ok(mut g) = t.lock() {
                            *g = pj;
                        }
                    }
                    crate::exec_jobs::execpline_slots_forget_to(slots_snap);
                    crate::ported::signals_h::unqueue_signals();
                    // Now that the parent's traps are back, run the ones
                    // whose signal arrived during the body.
                    if sigtrapped_snap.is_some() {
                        crate::fusevm_bridge::subshell_signal_leave();
                    }
                } // if !shared_state
            }
        }
        // Restore LINENO so outer xtrace sees the outer line. LINENO
        // carries PM_READONLY (matching zsh's `integer-readonly-special`
        // GSU), so the restore must bypass the generic readonly guard
        // exactly like BUILTIN_SET_LINENO (fusevm_bridge.rs:5156) — write
        // the param's `u_val` directly and mirror the file-static /
        // lexer line counters. The previous `set_scalar` went through the
        // readonly-checked path: harmless on the `-c` route (LINENO not
        // yet flagged readonly there) but fatal on the faithful
        // loop()/zsh_main route, where every `$(...)` in piped/redirected
        // input died with `read-only variable: LINENO`.
        if let Some(ln) = saved_lineno {
            let n: crate::ported::zsh_h::zlong = ln.parse().unwrap_or(0);
            if let Ok(mut tab) = crate::ported::params::paramtab().write() {
                if let Some(pm) = tab.get_mut("LINENO") {
                    // c:Src/utils.c:121 `zlong lineno` — the value lives in the C
                    // GLOBAL, reached through LINENO's GSU. A `typeset -h +g LINENO`
                    // local shadow has no PM_SPECIAL and no GSU, so C's `lineno = N`
                    // never touches it; skip the paramtab mirror for the same reason.
                    if (pm.node.flags & crate::ported::zsh_h::PM_SPECIAL as i32) != 0 {
                        pm.u_val = n;
                        pm.node.flags &= !(crate::ported::zsh_h::PM_UNSET as i32);
                    }
                }
            }
            crate::ported::utils::set_lineno(n as i32);
            crate::ported::lex::set_lineno(n as u64);
        }
        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.
        let final_status = cmd_status.unwrap_or(0);
        self.set_last_status(final_status);
        // c:Src/exec.c:4775 — `getoutput` (the C cmd-subst path used by
        // both `$(…)` and `` `…` ``) propagates the inner exit through
        // `cmdoutval`, then the caller does `LASTVAL = cmdoutval`. Mirror
        // by writing the cmd-subst's exit into the ported `cmdoutval`
        // global so `getoutput()`'s post-call `LASTVAL = cmdoutval` (at
        // exec.rs:559-562) and the C-equivalent `cmdoutval = lastval`
        // bookkeeping in execcmd_exec's assignment paths both see the
        // real exit. Without this, backtick assignments (`a=\`false\`;
        // echo $?`) reported 0 because getoutput's caller path read a
        // cmdoutval that was never updated by the in-process hook.
        crate::ported::exec::cmdoutval.store(final_status, std::sync::atomic::Ordering::Relaxed);

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

        // Pop the trap-routing stack BEFORE restoring stdout so any
        // trap that fires during the restore goes to the cmdsub's
        // pipe (matching what zsh's forked cmdsub would do — the
        // child's fd 1 is the pipe right up until the child exits).
        crate::fusevm_bridge::CMDSUBST_OUTER_FDS.with(|s| {
            s.borrow_mut().pop();
        });
        // c:Bug #353 — restore fd 2 from the saved outer stderr. A
        // body that ran `exec 2>&1` (no command, just redirects)
        // would have committed fd 2 → the cmdsub's pipe write end.
        // In zsh's forked cmdsub the committed redirect dies with
        // the child; zshrs's in-process cmdsub would leak the dup
        // back to the parent and keep the pipe write-end alive,
        // blocking the parent's read on the read_end forever.
        // Always restoring fd 2 here rolls back any commit so the
        // pipe write-end count drops to zero when we drop the
        // local write_fd reference (which already happened above).
        if saved_stderr_for_trap >= 0 {
            unsafe {
                libc::dup2(saved_stderr_for_trap, libc::STDERR_FILENO);
            }
            crate::ported::utils::zclose(saved_stderr_for_trap);
        }
        // Restore stdout and read what was captured.
        if saved_stdout >= 0 {
            unsafe {
                libc::dup2(saved_stdout, libc::STDOUT_FILENO);
            }
            crate::ported::utils::zclose(saved_stdout);
        } else {
            unsafe { libc::close(libc::STDOUT_FILENO) }; // c:2048 zclose(y)
        }
        // Collect the concurrently-drained output. With fd 1 restored
        // above, the last shell-side write end is closed, so the reader
        // hits EOF and join() returns the full buffer regardless of
        // size — no pipe-full deadlock. The reader only read (never
        // closed) read_fd, so zclose still clears its FDT_INTERNAL mark
        // (c:Src/utils.c:2137).
        let bytes = reader_handle.join().unwrap_or_default();
        crate::ported::utils::zclose(read_fd);
        // This is the `$( cmd )` counterpart of `readoutput`'s c:4835-4849
        // conversion, and it has to be just as lossless: with
        // `String::from_utf8_lossy` a helper that emitted a latin-1 byte —
        // which is routine for the legacy completion corpus, where
        // `_call_program` shells out to tools whose descriptions predate
        // UTF-8 — had that byte replaced by U+FFFD before any completer saw
        // it. `decode_script_bytes` Meta-encodes only what is not valid
        // UTF-8, and `utils::unmetafy_str` restores the byte on output.
        let mut output = crate::script_bytes::decode_script_bytes(&bytes);

        // POSIX: trailing newlines stripped from cmd-sub result.
        // c:Src/subst.c:1908 + c:2064-2069 — a nofork `${ … }` does its own
        // trim (`trim = !qt` under zsh emulation: ONE newline unquoted, NONE
        // quoted), so its caller gets the bytes untouched. Stripping them all
        // here left `"${ print INNER } $?"` as `INNER 7`, zsh `INNER\n 7`.
        while !shared_state && output.ends_with('\n') {
            output.pop();
        }
        // !!! RUST-ONLY: provenance tap. `$(…)` is a lineage ORIGIN —
        // these bytes did not exist in the shell before the inner list
        // ran. This is the in-process cmd-subst funnel (the host
        // `ShellHost::cmd_subst` path taps the same event for chunks
        // that reach the VM as sub-chunks instead of source text).
        if crate::provenance::active() {
            crate::provenance::on_cmd_subst(cmd_str, &output);
        }
        if parse_failed {
            // c:Src/exec.c:4778-4780 — `getoutput` returns NULL when
            // `parse_string` fails, and its caller raises the error:
            // c:Src/subst.c:400-402 `zerr("parse error in command
            // substitution"); return NULL;`, abandoning the command. Only a
            // body parsed at run time gets here (`` `…` ``); the lexer has
            // already parsed a `$(…)` body.
            crate::ported::utils::zerr("parse error in command substitution");
        }
        output
    }
}

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

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

    /// A `zsh/parameter` param is an autoload stub until it is READ; the read
    /// materializes it. `$parameters` enumerations type a stub as "undefined"
    /// (Src/Modules/parameter.c:49-50) and never resolve it, which is what
    /// puts those names in the right `_parameters -g` bucket.
    ///
    /// Reference behavior (`zsh -f`):
    ///   `m=( ${(kv)parameters} ); print $m[aliases]`            → undefined
    ///   `${parameters[aliases]}` first, then the same scan      → association-…
    #[test]
    fn module_params_are_autoload_stubs_until_read() {
        let _g = crate::test_util::global_state_lock();
        // `jobstates` is not touched by shell STARTUP, but
        // `MATERIALIZED_MODULE_PARAMS` is a process-global side-set and 10k
        // tests share one process — `compsys::_jobs` and friends read the job
        // parameters, so by the time this runs the stub may already have been
        // materialized. The lock serialises but restores nothing, so put the
        // name back to its untouched state here rather than assume nothing
        // else in the binary ever reads it. The assertions below are
        // unchanged: an untouched stub reads as a stub, and a read
        // materializes it.
        unmark_module_param_used("jobstates");
        assert!(
            module_param_is_autoload_stub("jobstates"),
            "untouched module param must read as a stub"
        );
        mark_module_param_used("jobstates");
        assert!(
            !module_param_is_autoload_stub("jobstates"),
            "a read must materialize it"
        );
        // A core special (not module-provided) is never a stub.
        assert!(!module_param_is_autoload_stub("path"));
        assert!(!module_param_is_autoload_stub("PATH"));
    }

    /// Phase 3 diagnostic: a worker must be able to run a USER-DEFINED function
    /// (defined on the main executor) — the function source lives in the shared
    /// shfunctab, and the worker lazy-compiles it from there. Its `typeset -g`
    /// must reach the global param table. This is what `async_precmd` needs.
    #[test]
    fn phase3_worker_runs_user_defined_function() {
        let _g = crate::test_util::global_state_lock();
        let mut main = ShellExecutor::new();
        main.execute_script("phase3fn() { typeset -g PHASE3_FN_RESULT=fn_ran }")
            .unwrap();
        // sanity: it ran on main? (define only — not called yet)
        assert_eq!(getsparam("PHASE3_FN_RESULT"), None);

        let pool = std::sync::Arc::new(crate::worker::WorkerPool::new(2));
        let pool2 = std::sync::Arc::clone(&pool);
        let (tx, rx) = std::sync::mpsc::channel::<()>();
        pool.submit(move || {
            let mut wex = ShellExecutor::new_worker(pool2);
            let _ = wex.execute_script_zsh_pipeline("phase3fn");
            let _ = tx.send(());
        });
        rx.recv().expect("worker completed");
        assert_eq!(
            getsparam("PHASE3_FN_RESULT"),
            Some("fn_ran".to_string()),
            "worker could not run the user-defined function from shared shfunctab"
        );
    }

    /// Phase 1 of the in-process thread-execution model: prove a shell body
    /// runs on a POOL WORKER THREAD via `new_worker` and that its `typeset -g`
    /// lands in the GLOBAL (RwLock-synchronized) param table. Each worker writes
    /// a DISTINCT key, so a green run shows: (a) `ExecutorContext::enter` +
    /// `execute_script_zsh_pipeline` work off the main thread, and (b) N
    /// concurrent writers don't corrupt the shared table. This is the linchpin
    /// for converting the subprocess-forking parallel builtins to threads.
    #[test]
    fn phase1_worker_shell_writes_reach_global_paramtab() {
        let _g = crate::test_util::global_state_lock();
        // Seed the globals (options, default params) exactly as a live session
        // would — workers SHARE these; new_worker() never re-seeds them.
        let _main = ShellExecutor::new();

        let pool = std::sync::Arc::new(crate::worker::WorkerPool::new(4));
        const N: usize = 16;
        let (tx, rx) = std::sync::mpsc::channel::<usize>();
        for i in 0..N {
            let tx = tx.clone();
            let pool_for_worker = std::sync::Arc::clone(&pool);
            pool.submit(move || {
                // Lightweight per-worker executor; shares the global tables.
                let mut wex = ShellExecutor::new_worker(pool_for_worker);
                let _ =
                    wex.execute_script_zsh_pipeline(&format!("typeset -g PHASE1_WK_{i}=val_{i}"));
                let _ = tx.send(i);
            });
        }
        drop(tx);
        // Barrier: wait for all N workers.
        let mut done = 0usize;
        while rx.recv().is_ok() {
            done += 1;
        }
        assert_eq!(done, N, "all {N} workers completed");

        // Every worker's write must be visible in the global param table.
        for i in 0..N {
            assert_eq!(
                getsparam(&format!("PHASE1_WK_{i}")),
                Some(format!("val_{i}")),
                "worker {i} typeset -g did not reach the global paramtab"
            );
        }
    }

    #[test]
    fn test_if_true() {
        let _g = crate::test_util::global_state_lock();
        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 _g = crate::test_util::global_state_lock();
        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 _g = crate::test_util::global_state_lock();
        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 _g = crate::test_util::global_state_lock();
        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 _g = crate::test_util::global_state_lock();
        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() {
        let _g = crate::test_util::global_state_lock();
        use std::sync::atomic::Ordering;
        let prev = crate::ported::exec::FORKLEVEL.load(Ordering::Relaxed);
        // Default state at process start: zero (matches C's BSS init
        // of `int forklevel;` to 0).
        crate::ported::exec::FORKLEVEL.store(0, Ordering::Relaxed);
        assert_eq!(crate::ported::exec::FORKLEVEL.load(Ordering::Relaxed), 0);
        // Simulate the c:1221 store: `forklevel = locallevel;`.
        crate::ported::exec::FORKLEVEL.store(3, Ordering::Relaxed);
        assert_eq!(crate::ported::exec::FORKLEVEL.load(Ordering::Relaxed), 3);
        crate::ported::exec::FORKLEVEL.store(prev, Ordering::Relaxed);
    }

    /// `zexecve_recover` is the PARENT-side half of C's `#!`-recovery block
    /// (c:Src/exec.c:534-627). Every `execve` in that block is preceded by
    /// `winch_unblock()` (c:565/570/580/584/626) because C is inside the
    /// forked child and is about to be replaced. This port returns to the
    /// caller instead, so those unblocks left the shell's standing
    /// `winch_block()` (c:Src/init.c:1458) dropped with nothing to re-arm
    /// it — and a SIGWINCH delivered inside a widget makes `calclist`
    /// (c:Src/Zle/compresult.c:1495) count display strings against a width
    /// they were not built at.
    ///
    /// The mask is per-thread, so blocking here cannot leak into other
    /// tests.
    #[test]
    #[cfg(unix)]
    fn zexecve_recover_keeps_sigwinch_blocked_in_the_parent() {
        fn sigwinch_blocked() -> bool {
            unsafe {
                let mut cur: libc::sigset_t = std::mem::zeroed();
                libc::pthread_sigmask(libc::SIG_BLOCK, std::ptr::null(), &mut cur);
                libc::sigismember(&cur, libc::SIGWINCH) == 1
            }
        }

        let dir = std::env::temp_dir().join(format!(
            "zshrs_winch_recover_{}_{:?}",
            std::process::id(),
            std::thread::current().id()
        ));
        std::fs::create_dir_all(&dir).unwrap();

        // c:611-627 — shebang-less text file: the `/bin/sh` fallback.
        let noshebang = dir.join("noshebang");
        std::fs::write(&noshebang, "echo hi\n").unwrap();
        // c:576-585 — `#!` line naming an absolute interpreter.
        let shebang = dir.join("shebang");
        std::fs::write(&shebang, "#!/bin/cat -v\necho hi\n").unwrap();

        let saved = sigwinch_blocked();
        crate::ported::signals_h::winch_block(); // c:Src/init.c:1458
        assert!(sigwinch_blocked(), "precondition: winch_block() holds");

        let argv = vec!["script".to_string()];
        let sh = zexecve_recover(noshebang.to_str().unwrap(), &argv, libc::ENOEXEC);
        assert_eq!(
            sh.as_ref().map(|(p, _)| p.as_str()),
            Ok("/bin/sh"),
            "c:625-627 — a shebang-less script re-execs through /bin/sh"
        );
        assert!(
            sigwinch_blocked(),
            "c:626 — the /bin/sh recovery must not unblock SIGWINCH in the parent"
        );

        let interp = zexecve_recover(shebang.to_str().unwrap(), &argv, libc::ENOEXEC);
        assert_eq!(
            interp.as_ref().map(|(p, _)| p.as_str()),
            Ok("/bin/cat"),
            "c:576-585 — the `#!` line names the interpreter"
        );
        assert!(
            sigwinch_blocked(),
            "c:580/c:584 — the `#!` recovery must not unblock SIGWINCH in the parent"
        );

        if !saved {
            crate::ported::signals_h::winch_unblock();
        }
        let _ = std::fs::remove_dir_all(&dir);
    }

    /// c:Src/exec.c:544 `*argv = pth;` — the shebang-less `/bin/sh`
    /// fallback (c:611-627) hands sh the PATH being executed and applies the
    /// c:616 `-`/`+` guard to it, not to the command word the user typed.
    /// `PATH=-dir tstcmd` (A05execution.ztst, workers/52515) resolves to
    /// `-dir/tstcmd`, which sh must see as an operand.
    #[test]
    #[cfg(unix)]
    fn zexecve_recover_sh_fallback_passes_the_path_not_the_word() {
        let dir = std::env::temp_dir().join(format!(
            "zshrs_recover_argv_{}_{:?}",
            std::process::id(),
            std::thread::current().id()
        ));
        std::fs::create_dir_all(&dir).unwrap();
        let script = dir.join("tstcmd");
        std::fs::write(&script, "echo no shebang\n").unwrap();
        let pth = script.to_str().unwrap().to_string();
        // A word spelled like an option must neither be handed to sh nor
        // trip the guard: only the executed path counts.
        let argv = vec!["-tstcmd".to_string(), "arg".to_string()];
        let got = zexecve_recover(&pth, &argv, libc::ENOEXEC);
        let _ = std::fs::remove_dir_all(&dir);
        let want: Vec<String> = vec!["sh".to_string(), pth.clone(), "arg".to_string()];
        assert_eq!(got, Ok(("/bin/sh".to_string(), want)));
    }
}

// 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(),
            );
        }
    }
}

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` variant.
    Parent(i32), // Contains child PID
    /// `Child` variant.
    Child,
}

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

use crate::fusevm_bridge::with_executor;
use crate::ported::glob::*;
use crate::ported::hist::*;
use crate::ported::jobs::*;
use crate::ported::math::*;
use crate::ported::module::*;
use crate::ported::modules::cap::*;
use crate::ported::modules::terminfo::*;
use crate::ported::options::*;
use crate::ported::params::*;
use crate::ported::pattern::*;
use crate::ported::prompt::*;
use crate::ported::signals::*;
use crate::ported::subst::*;
use crate::ported::utils::{zerr, zerrnam, zwarn, zwarnnam};
use ::regex::{Error as RegexError, Regex, RegexBuilder};

pub use crate::ported::modules::regex::posix_ere_bracket_escape;

impl ShellExecutor {
    /// Every option name in `ZSH_OPTIONS_SET` (port of `optns[]` at
    /// `Src/options.c:79+`).
    pub(crate) fn all_zsh_options() -> Vec<&'static str> {
        ZSH_OPTIONS_SET.iter().copied().collect()
    }

    /// `name → default-on` map via canonical `default_on_options`
    /// (port of `defset()` macro at `Src/options.c:73`).
    pub(crate) fn default_options() -> HashMap<String, bool> {
        let on = default_on_options();
        Self::all_zsh_options()
            .into_iter()
            .map(|n| (n.to_string(), on.contains(n)))
            .collect()
    }
}
impl ShellExecutor {
    /// PURE PASSTHRU to the canonical `params::getsparam` (C port of
    /// `Src/params.c::getsparam`). Every special-name case the old
    /// 316-line body handled lives in `params::lookup_special_var` +
    /// `getsparam`'s paramtab/env walk. Returns an empty string for
    /// unset names (matching the old fn's signature; callers that
    /// need the set/unset distinction call `scalar` / `has_scalar`
    /// directly).
    pub(crate) fn get_variable(&self, name: &str) -> String {
        getsparam(name).unwrap_or_default()
    }
}

// Source-form registration step used by the autoload-load path
// (`dispatch_function_call` / `run_function_body_only`). Decides
// whether to feed the file body to the funcdef pipeline VERBATIM
// (zsh-style: the body's own `function NAME() {...}` definition
// registers the function on execution) or to WRAP it in
// `NAME() {...}` (ksh-style or multi-statement: the body is just
// commands or includes additional statements past the def).
//
// The classification mirrors c:Src/exec.c:5725 + 5750 — KSHAUTOLOAD-
// equivalent vs zsh-style autoload. The structural check is the
// canonical `stripkshdef` (Src/exec.c:6291, ported at exec.rs:10548):
// parse the body to Eprog, run stripkshdef, and check whether it
// returned a stripped (different-length wordcode) Eprog. When it
// did, the file is the single-funcdef shape `[function] NAME [()] {
// INNER }`; running the file source directly through the funcdef
// pipeline registers NAME via the WC_FUNCDEF opcode at
// fusevm_bridge.rs:6330, matching C's `shf->funcdef = stripkshdef(
// prog, name)` semantics (the inner body becomes the function's
// body). When it didn't strip — single statement that isn't a
// funcdef, or multiple list nodes (e.g. `function ztm() {...}` +
// trailing `ztm "$@"` self-call) — we fall back to wrap-and-run so
// the canonical funcdef opcode still fires and any extra
// statements run inside the registered body, matching C's
// behavior of using the whole prog as funcdef in that case.
/// Restore `noaliases` on scope exit.
///
/// C's `loadautofn` (Src/exec.c:5684-5704) saves `noaliases`, sets it from the
/// function's PM_UNALIASED bit for the duration of the body parse, and restores
/// it unconditionally. The zshrs autoload block has early `return` paths, so the
/// restore has to ride on Drop rather than a trailing statement — otherwise a
/// `-U` autoload that failed to load would leave alias expansion disabled for
/// the rest of the shell.
struct NoAliasesRestore(bool);

impl Drop for NoAliasesRestore {
    fn drop(&mut self) {
        crate::ported::lex::set_noaliases(self.0); // c:5704
    }
}

/// c:Src/exec.c:5735 `loadautofnsetfile(shf, fdir)` + c:5751 — put the load
/// directory (and the absolute-path marker) back on a function whose body
/// zshrs just re-registered through the funcdef pipeline.
///
/// C loads an autoloaded body IN PLACE on the existing `Shfunc`, so
/// `filename`, PM_LOADDIR and PM_ABSPATH_USED all survive the load:
/// `shf->node.flags &= ~PM_UNDEFINED` (c:5751) is the only flag C clears.
/// zshrs re-registers the body as SOURCE through the WC_FUNCDEF pipeline,
/// which builds a FRESH node whose `filename` is the enclosing script and
/// whose flag word starts at zero. Both have to be reinstated, or `whence -v`
/// names the calling script instead of the definition file, and the
/// PM_LOADDIR|PM_ABSPATH_USED pair that `add_autoload_function`
/// (Src/builtin.c:3310-3323) tests — to hand a sibling `autoload -Uz NAME`
/// the caller's directory — is gone.
///
/// One helper rather than four inline copies: all four
/// `autoload_register_source` call sites need the identical restore.
///
/// `ksh_style` must be sampled BEFORE the re-registration (the fresh node's
/// flag word no longer carries PM_KSHSTORED / PM_ZSHSTORED, so re-deriving it
/// here would read the wrong answer): c:Src/exec.c:5792-5806 is the one arm
/// where C does NOT reload the body in place. It runs the whole FILE at top
/// level (`execode(prog, 1, 0, "evalautofunc")`, c:5795) and then REFETCHES
/// the node (`shf = shfunctab->getnode(shfunctab, n)`, c:5797) because the
/// file's own `NAME() { … }` created a brand-new Shfunc. There is no
/// `loadautofnsetfile` call on that arm, so zsh itself loses `filename`,
/// PM_LOADDIR and PM_ABSPATH_USED there. Verified against the reference shell:
///
/// ```text
/// $ zsh -f -c 'autoload -k /D/kw; kw'
/// ksh-kw ran
/// kw: ksib: function definition file not found
/// $ zsh -f -c 'autoload -k /D/kw; kw >/dev/null; whence -v kw'
/// kw is a shell function from zsh
/// ```
///
/// Restoring on that arm would make a ksh-autoloaded function inherit its
/// directory to siblings where zsh does not.
fn restore_loaddir(name: &str, dir: &str, abspath_used: bool, ksh_style: bool) {
    if ksh_style {
        return; // c:5792-5806 — no loadautofnsetfile on the ksh arm
    }
    if let Ok(mut tab) = crate::ported::hashtable::shfunctab_lock().write() {
        if let Some(shf) = tab.get_mut(name) {
            crate::ported::exec::loadautofnsetfile(shf, Some(dir)); // c:5735
            if abspath_used {
                shf.node.flags |= crate::ported::zsh_h::PM_ABSPATH_USED as i32; // c:5751
            }
        }
    }
}

/// !!! WARNING: RUST-ONLY HELPER — NO C COUNTERPART !!!
///
/// C never has to ask this question. `Src/Modules/parameter.c:295-315`
/// (`setfunction`, the `functions[NAME]=BODY` setter) parses the assigned text
/// with `parse_string(val, 1)` and stores the result AS THE BODY —
/// `shf->funcdef = dupeprog(prog, 0)` (c:313) — so the function is fully
/// defined the moment the assignment runs. `loadautofn`
/// (`Src/exec.c:5723-5806`), which reads a FILE and therefore has to decide
/// between "the file IS the body" and "the file DEFINES the function"
/// (c:5781 `ksh == 2 || (ksh == 1 && isset(KSHAUTOLOAD))`), is a different
/// entry point that a parameter assignment never reaches.
///
/// zshrs stores the assigned text on `shfunc.body` with no compiled chunk, so
/// the first CALL lands in the same autoload prelude a real `autoload` stub
/// uses — and that prelude was applying `loadautofn`'s file rules to it. The
/// two cases are told apart by the flag `loadautofn` stamps and a parameter
/// assignment does not: `loadautofnsetfile` sets PM_LOADDIR (c:5657) on the
/// node it loaded, while `setfunction` leaves the flag word at `dis` (c:314).
/// The `loaded_dir` capture at both call sites already reads the same bit for
/// the same reason.
fn body_came_from_param_assignment(flags: i32) -> bool {
    (flags as u32 & crate::ported::zsh_h::PM_LOADDIR) == 0
}

/// !!! WARNING: RUST-ONLY HELPER — NO C COUNTERPART !!!
///
/// The text to run to install a `functions[NAME]=BODY` assignment: ALWAYS the
/// `NAME() { … }` wrap, never the verbatim run that
/// [`autoload_definition_source`] falls back to for a file whose contents are
/// already a definition of `NAME`. c:Src/Modules/parameter.c:313 makes the
/// parsed text the funcdef unconditionally, so text that happens to READ as
/// `NAME () { … }` is a BODY whose execution defines `NAME` — measured
/// against the reference shell:
///
/// ```text
/// $ zsh -f -c 'functions[g]="g () { print inner }"; g; print "[${functions[g]}]"'
/// [	print inner]
/// ```
///
/// Nothing is printed: the call ran the definition. Running that text verbatim
/// at install time instead printed `inner` and defined `g` a call too early.
fn param_definition_source(name: &str, body: &str) -> String {
    format!("{name}() {{\n{body}\n}}")
}

/// c:Src/exec.c:5781 — `if (ksh == 2 || (ksh == 1 && isset(KSHAUTOLOAD)))`,
/// the ksh-style load branch. `ksh` derives from the stub's stored-style bits
/// per c:5762-5766 (`PM_KSHSTORED ? 2 : PM_ZSHSTORED ? 0 : 1`; a decisive
/// `.zwc` header flag was already folded into these bits by `loadautofn`).
///
/// Two zshrs steps need the same answer — `autoload_register_source` (wrap vs
/// verbatim) and `restore_loaddir` (whether the load kept the original node)
/// — so the decision lives in one place.
fn autoload_is_ksh_style(name: &str) -> bool {
    let flags = crate::ported::utils::getshfunc(name)
        .map(|f| f.node.flags as u32)
        .unwrap_or(0);
    let ksh = if flags & crate::ported::zsh_h::PM_KSHSTORED != 0 {
        2 // c:5765
    } else if flags & crate::ported::zsh_h::PM_ZSHSTORED != 0 {
        0 // c:5766
    } else {
        1 // c:5766
    };
    ksh == 2 || (ksh == 1 && crate::ported::zsh_h::isset(crate::ported::zsh_h::KSHAUTOLOAD))
    // c:5781
}

/// The cache key for an autoloaded function: `(resolved fpath dir,
/// SHA-256 of the definition text)`, or `None` when the directory
/// cannot be pinned down.
///
/// `loadautofn` records the resolved fpath directory on the shfunc
/// (`filename` + `PM_LOADDIR`, c:Src/exec.c:5657); a function whose
/// `filename` is still the placeholder `"zsh"` was not resolved through
/// `$fpath` and is not cached.
///
/// The hash is over `registered` — the exact string about to be
/// compiled — and NOT over a `stat` of `<dir>/<name>`. Those are not the
/// same thing: `getfpfunc` prefers a `<dir>.zwc` digest over the plain
/// file whenever the digest is newer (c:Src/parse.c:3771-3777), so the
/// body being installed may have no relationship to the bytes of the
/// file that path names. Stamping the path let a chunk built from one
/// text be served for another.
///
/// `from_wordcode` salts the digest because it changes what the same bytes
/// COMPILE TO: a wordcode-derived body is compiled under [`ZwcRelexGuard`],
/// so it resolves quotes and aliases the way `zcompile` did, while a
/// plain-file body of those same bytes resolves them against the live
/// RCQUOTES / alias state. One cache line must never be served for both.
fn autoload_source_key(
    name: &str,
    registered: &str,
    from_wordcode: bool,
) -> Option<(String, [u8; 32])> {
    let dir = crate::ported::utils::getshfunc(name)
        .and_then(|f| f.filename)
        .filter(|d| d != "zsh")?;
    let sha = if from_wordcode {
        crate::autoload_cache::source_digest(&format!("\0zwc\0{registered}"))
    } else {
        crate::autoload_cache::source_digest(registered)
    };
    Some((dir, sha))
}

/// !!! WARNING: RUST-ONLY HELPER — NO C COUNTERPART !!!
///
/// Raises `noerrs` (c:Src/utils.c:175 — the gate every `zerr`/`zwarn`
/// consults) for the life of the guard, so a pass that only exists because
/// zshrs parses text where C carries a parsed `Eprog` cannot report an error
/// C would report exactly once. `ERRFLAG_ERROR` is still set while muted, so
/// callers that read errflag still see the failure.
struct ZerrMute(i32);

impl ZerrMute {
    fn enter() -> Self {
        let mut g = crate::ported::utils::noerrs_lock().lock().unwrap();
        let prev = *g;
        *g = 1;
        Self(prev)
    }
}

impl Drop for ZerrMute {
    fn drop(&mut self) {
        if let Ok(mut g) = crate::ported::utils::noerrs_lock().lock() {
            *g = self.0;
        }
    }
}

/// What an autoload of one name will hand the compiler.
struct AutoloadSource {
    /// The definition text: the file body verbatim, or the `name() { … }` wrap.
    text: String,
    /// The body is a `.zwc` deparse, so the compile needs [`ZwcRelexGuard`].
    from_wordcode: bool,
    /// c:Src/exec.c:6264 — `parse_string` rejected the file and has ALREADY
    /// reported the error against the loadee's name. C returns NULL from
    /// `getfpfunc`, so `loadautofn` abandons the load right there (c:5726) and
    /// prints nothing more. zshrs still runs `text` through the compiler
    /// (that is where the body becomes a chunk), so the caller silences THAT
    /// pass instead — otherwise the same parse error lands twice, the second
    /// time one line off because of the wrap's leading `name() {` line.
    parse_failed: bool,
}

/// Returns the text to run to install `name`, plus whether that text came out
/// of a `.zwc` (see [`autoload_note_wordcode_body`]) and therefore has to be
/// lexed under [`ZwcRelexGuard`] wherever it is lexed, and whether the file's
/// one parse rejected it.
fn autoload_register_source(name: &str, body: &str) -> AutoloadSource {
    let ksh_style = autoload_is_ksh_style(name);
    // `loadautofn` took this body from autoloads.rkyv: the registration it
    // was stored with is the one the parse below would produce.
    if let Some((text, from_wordcode, parse_failed)) =
        crate::autoload_cache::take_hit(name, body, ksh_style)
    {
        return AutoloadSource {
            text,
            from_wordcode,
            parse_failed,
        };
    }
    // c:Src/exec.c:5725 `stripkshdef(prog, …)` — the ksh-vs-zsh wrap decision
    // below PARSES `body`, so it is itself a second lex of the deparse and
    // needs the same pin as the compile that follows it.
    let from_wordcode = autoload_body_from_wordcode(name, body);
    let _relex = from_wordcode.then(ZwcRelexGuard::enter);
    let (text, parse_failed) = autoload_definition_source(name, body, ksh_style);
    crate::autoload_cache::commit_search(name, body, &text, parse_failed, ksh_style);
    AutoloadSource {
        text,
        from_wordcode,
        parse_failed,
    }
}

/// !!! WARNING: RUST-ONLY HELPER — NO C COUNTERPART !!!
///
/// Pins the lexer to the spelling a `.zwc` deparse was written in, for the
/// duration of one compile.
///
/// C never needs this: the compiled arm of `source()` is `execode(prog, 1,
/// 0, "filecode")` (c:Src/init.c:1621) and the ksh-autoload arm is
/// `execode(prog, 1, 0, "evalautofunc")` (c:Src/exec.c:5795) — the wordcode
/// runs as it stands and NOTHING is lexed. A `.zwc` is resolved once, at
/// `zcompile` time. zshrs has no execute-the-wordcode path: it deparses back
/// to source with `getpermtext` and lexes that, so every piece of LEXER-TIME
/// state that C bypassed has to be neutralised by hand, or the second lex
/// resolves the text differently from the first.
///
/// Two such pieces are known to change the result:
///
///   * **RCQUOTES.** `untokenize` (c:Src/exec.c:2134) renders every quote
///     null through `ztokens[Snull - Pound]`, and that entry is a bare
///     single quote (c:Src/lex.c:38), so a closing null followed by an
///     opening one deparses to two adjacent quotes. Under RCQUOTES the lexer
///     reads that pair inside a quoted word as one LITERAL quote
///     (c:Src/lex.c:1328) rather than as two delimiters. `zsh-expand`'s
///     plugin entry does `setopt rcquotes` at its line 39, so every later
///     `.zwc`-sourced alias with adjacent quoted segments — the whole
///     `zsh-openshift-aliases` set — gained literal quotes zsh never had.
///
///   * **Aliases.** `checkalias` (c:Src/lex.c:1909) fires from the lexer, so
///     an alias installed before the `source` rewrote words INSIDE the
///     compiled program: with `alias mycmd=…` live, a `.zwc` whose second
///     line is `mycmd` ran the alias where zsh runs the function. Global
///     aliases are worse — they rewrite any word, so `print -r -- GA: x`
///     became `print -r -- GA: LEAKED` under `alias -g x=LEAKED`. This is
///     C's `noaliases` (c:Src/lex.c:135), the same switch `par_case` uses to
///     keep `in` from being alias-expanded.
///
/// Both are restored on drop, so the restore survives a panic out of the
/// compiler — and, more importantly, the program's own RUNTIME lexing is
/// unaffected: a `setopt rcquotes` the `.zwc` performs still takes effect
/// and still outlives the source, and a function or `eval` body it runs is
/// lexed later, against the live alias table.
///
/// One residual case is out of reach here and needs a real
/// execute-the-wordcode path: a `.zwc` COMPILED while RCQUOTES was set holds
/// an unescaped literal quote in its tokenized word (c:Src/lex.c:1329 adds
/// the character with no `Bnull` prefix), and `untokenize` cannot tell that
/// apart from a quote null. No option state at re-lex time recovers it.
///
/// `noaliases` is a thread-local (`LEX_NOALIASES`), but the option store is
/// process-wide, so the RCQUOTES window is visible to a worker thread that
/// lexes concurrently. The window is one synchronous compile.
pub(crate) struct ZwcRelexGuard {
    rcquotes: bool,
    noaliases: bool,
}

impl ZwcRelexGuard {
    pub(crate) fn enter() -> Self {
        let rcquotes = crate::ported::zsh_h::isset(crate::ported::zsh_h::RCQUOTES);
        if rcquotes {
            crate::ported::options::opt_state_set("rcquotes", false);
        }
        let noaliases = crate::ported::lex::noaliases();
        crate::ported::lex::set_noaliases(true); // c:Src/lex.c:1909
        Self {
            rcquotes,
            noaliases,
        }
    }
}

impl Drop for ZwcRelexGuard {
    fn drop(&mut self) {
        if self.rcquotes {
            crate::ported::options::opt_state_set("rcquotes", true);
        }
        crate::ported::lex::set_noaliases(self.noaliases);
    }
}

/// !!! WARNING: RUST-ONLY HELPER — NO C COUNTERPART !!!
///
/// The RCQUOTES state each shell-defined function's body was resolved
/// under at DEFINITION time, keyed by name and digested body text.
///
/// C has no such fact to carry. `execfuncdef` compiles the body into
/// wordcode when the definition runs (c:Src/exec.c:5389-5391 —
/// `shf->funcdef = dupeprog(...)`), and `printshfuncnode` renders THAT
/// program back with `getpermtext(f->funcdef, NULL, 1)`
/// (c:Src/hashtable.c:954). Every lexer-time decision is already settled
/// in the wordcode, so printing cannot revisit it — `functions f` gives
/// the same text no matter which options are set when it runs.
///
/// zshrs has no `Eprog` for a shell-defined function: `shfunc::body` keeps
/// the raw source and `printshfuncnode`'s stand-in RE-LEXES it at print
/// time. Under RCQUOTES an adjacent quote pair inside a quoted word lexes
/// as one LITERAL quote (c:Src/lex.c:1328) instead of as two delimiters,
/// so one unchanged function deparsed two different ways across a
/// `setopt rcquotes` — docs/BUGS.md #1105. Pinning the print-time lex to
/// defaults is wrong in the other direction: a function defined WHILE
/// RCQUOTES was set has to keep printing the RCQUOTES resolution, which is
/// why the state has to be recorded rather than assumed.
///
/// The state is sampled where the definition INSTALLS (the
/// `BUILTIN_REGISTER_COMPILED_FN` handler), not where its body was lexed.
/// In C those are the same instant, because zsh lexes one command list at
/// a time as it runs it; zshrs compiles a whole script ahead of running
/// it, so a runtime `setopt rcquotes` on an earlier line of the same file
/// is already in force at install time but was NOT in force at the ahead
/// -of-time lex. Install time is the one that matches zsh's printed
/// output (`setopt rcquotes` on line 1, `f() { … }` on line 2 →
/// C prints the RCQUOTES resolution), and it collapses onto lex time the
/// day the compiler stops running ahead of execution.
///
/// The mark is a DIGEST of the body rather than a bare flag, exactly like
/// [`AUTOLOAD_WORDCODE_BODY`]: `functions[name]=…`, an autoload, and a
/// plain redefinition all install different text, and a stale entry
/// simply stops matching instead of pinning the lexer for a body it never
/// described.
static FUNCDEF_LEX_RCQUOTES: Mutex<Option<HashMap<String, ([u8; 32], bool)>>> = Mutex::new(None);

/// !!! WARNING: RUST-ONLY HELPER — NO C COUNTERPART !!!
///
/// Record the RCQUOTES state `name`'s definition was installed under.
/// See [`FUNCDEF_LEX_RCQUOTES`]; called from the funcdef install path
/// (c:Src/exec.c:5389 `shf->funcdef = …`, where C bakes the same fact
/// into the wordcode instead).
pub(crate) fn funcdef_note_rcquotes(name: &str, body: &str, rcquotes: bool) {
    let digest = crate::autoload_cache::source_digest(body);
    // The state the body was LEXED under wins when the parser recorded it
    // (see FUNCDEF_PARSE_RCQUOTES); install time is only the fallback.
    let rcquotes = FUNCDEF_PARSE_RCQUOTES
        .lock()
        .as_ref()
        .and_then(|m| m.get(&digest).copied())
        .unwrap_or(rcquotes);
    FUNCDEF_LEX_RCQUOTES
        .lock()
        .get_or_insert_with(HashMap::new)
        .insert(
            name.to_string(),
            (digest, rcquotes),
        );
}

/// !!! WARNING: RUST-ONLY HELPER STATE — NO C COUNTERPART !!!
///
/// RCQUOTES as it stood when the parser lexed each captured function body,
/// keyed by the body digest. C bakes the `''` decision into the wordcode at
/// lex time (c:Src/lex.c:1326-1328), and zsh lexes one list at a time, so
/// `setopt rcquotes; f() { print 'a''b' }` on ONE line lexes `f` before the
/// option is on and prints `'a''b'`, while a definition on a later line (or
/// through `eval`) prints `'a'b'`. Install time cannot tell those apart.
static FUNCDEF_PARSE_RCQUOTES: Mutex<Option<HashMap<[u8; 32], bool>>> = Mutex::new(None);

/// !!! WARNING: RUST-ONLY HELPER STATE — NO C COUNTERPART !!!
///
/// Digests of function bodies the parser captured, which are ALIAS-RESOLVED.
///
/// C's par_funcdef compiles the body to wordcode after alias expansion, so
/// `functions` (getpermtext, c:Src/hashtable.c:954) shows exactly what the
/// parse saw, whatever the alias table holds later: an alias removed or
/// redefined after the definition changes nothing, and one defined after the
/// parse (a `-c` string is parsed whole, c:Src/init.c:1568 execstring) never
/// appears. `funcdef_capture::body_text` hands the parser that same
/// post-expansion text, so re-lexing it with aliases ON expands a second time
/// — `alias ls='ls -G'` listed `ls -G -G x` — and a body recorded here is
/// always re-lexed with aliases off. Keyed by digest like
/// [`FUNCDEF_LEX_RCQUOTES`]; text that did not come from a capture
/// (`functions[f]=…`, an autoload file) has no entry and keeps the live table.
static FUNCDEF_ALIAS_RESOLVED: Mutex<Option<std::collections::HashSet<[u8; 32]>>> =
    Mutex::new(None);

/// !!! WARNING: RUST-ONLY HELPER — NO C COUNTERPART !!!
///
/// Called by the parser right after it captures a function body. See
/// [`FUNCDEF_ALIAS_RESOLVED`].
pub(crate) fn funcdef_note_resolved_body(body: Option<&str>) {
    let Some(body) = body else { return };
    let digest = crate::autoload_cache::source_digest(body);
    FUNCDEF_ALIAS_RESOLVED
        .lock()
        .get_or_insert_with(std::collections::HashSet::new)
        .insert(digest);
    // Same parse-time capture point: record the RCQUOTES the body was lexed
    // under (FUNCDEF_PARSE_RCQUOTES).
    FUNCDEF_PARSE_RCQUOTES
        .lock()
        .get_or_insert_with(HashMap::new)
        .insert(digest, crate::ported::zsh_h::isset(crate::ported::zsh_h::RCQUOTES));
}

/// !!! WARNING: RUST-ONLY HELPER — NO C COUNTERPART !!!
///
/// Pin RCQUOTES to the value `name`'s body was defined under, for the
/// duration of one deparse of that body.
///
/// This is [`ZwcRelexGuard`]'s sibling: same problem (zshrs lexes text
/// where C runs wordcode), same RAII shape, but the target value is the
/// RECORDED one rather than "off" — the definition may itself have been
/// made under RCQUOTES, and then the RCQUOTES resolution is the correct
/// one to print. With no record for this exact body (a function installed
/// through a path that does not record — `functions[f]=…`, the ported
/// walker, an autoload stub) nothing is pinned and the live option stands,
/// which is the behaviour that predates the record.
///
/// The option store is process-wide, so the pin is visible to a worker
/// thread that lexes concurrently; the window is one synchronous deparse,
/// as it is for [`ZwcRelexGuard`].
pub(crate) fn funcdef_lex_pin(name: &str, body: &str) -> FuncdefLexPin {
    // c:Src/hashtable.c:954 renders the STORED wordcode, where every alias the
    // body's parse expanded is already baked in and nothing else can expand.
    // The re-lex runs with `noaliases` (c:Src/lex.c:135) whenever the text is
    // already resolved: the parser captured it (FUNCDEF_ALIAS_RESOLVED), or —
    // for an autoload body not yet parsed, as after `autoload +X` — it was
    // loaded under `autoload -U` (PM_UNALIASED, c:Src/exec.c:5746) or rendered
    // from a `.zwc`. Any other body keeps the live alias table.
    let noaliases = crate::ported::lex::noaliases();
    // c:Src/exec.c:5389 execfuncdef — C deparses the wordcode parsed when the
    // function was DEFINED, and a definition inside `emulate sh -c` is parsed
    // under that emulation (stamped as `shf->sticky`, c:5527-5532). Re-lex
    // under the same emulation (installemulation + its on/off options, as
    // doshfunc applies it at c:5977-6010), so an sh-mode `( one | two )` case
    // pattern keeps its separate alternatives and prints `(one | two)`. Only a
    // function carrying a sticky emulation is touched: `eval` / `-z` / `+X`
    // bodies keep the live state.
    let sticky_restore = crate::ported::utils::getshfunc(name)
        .and_then(|f| f.sticky.clone())
        .filter(|s| crate::ported::exec::sticky_emulation_differs(Some(s)) != 0)
        .map(|s| install_sticky_emulation(&s));
    let captured = FUNCDEF_ALIAS_RESOLVED
        .lock()
        .as_ref()
        .is_some_and(|set| set.contains(&crate::autoload_cache::source_digest(body)));
    let deparse_noaliases = captured
        || crate::ported::utils::getshfunc(name).is_some_and(|f| {
            (f.node.flags as u32 & crate::ported::zsh_h::PM_UNALIASED) != 0
        })
        || autoload_body_from_wordcode(name, body);
    if deparse_noaliases {
        crate::ported::lex::set_noaliases(true); // c:Src/lex.c:1909
    }
    let want = {
        let slot = FUNCDEF_LEX_RCQUOTES.lock();
        slot.as_ref()
            .and_then(|map| map.get(name))
            .filter(|(sha, _)| *sha == crate::autoload_cache::source_digest(body))
            .map(|(_, rcquotes)| *rcquotes)
    };
    let live = crate::ported::zsh_h::isset(crate::ported::zsh_h::RCQUOTES);
    match want {
        Some(w) if w != live => {
            crate::ported::options::opt_state_set("rcquotes", w);
            FuncdefLexPin {
                restore: Some(live),
                noaliases,
                sticky_restore,
            }
        }
        _ => FuncdefLexPin {
            restore: None,
            noaliases,
            sticky_restore,
        },
    }
}

/// !!! WARNING: RUST-ONLY HELPER — NO C COUNTERPART !!!
///
/// RAII half of [`funcdef_lex_pin`]. `restore` is `None` when nothing was
/// changed, so the common path costs one hash lookup and no option write.
pub(crate) struct FuncdefLexPin {
    restore: Option<bool>,
    noaliases: bool,
    /// Options and emulation in force before a sticky emulation was applied
    /// for the re-lex; put back on drop.
    sticky_restore: Option<(Vec<bool>, i32, i32, bool)>,
}

impl Drop for FuncdefLexPin {
    fn drop(&mut self) {
        if let Some(live) = self.restore {
            crate::ported::options::opt_state_set("rcquotes", live);
        }
        crate::ported::lex::set_noaliases(self.noaliases);
        if let Some(saved) = self.sticky_restore.take() {
            restore_sticky_emulation(saved);
        }
    }
}

/// Options and emulation cells saved by [`install_sticky_emulation`].
type SavedEmulation = (Vec<bool>, i32, i32, bool);

/// !!! WARNING: RUST-ONLY HELPER — NO C COUNTERPART !!!
///
/// The option half of doshfunc's sticky-emulation entry (c:Src/exec.c:
/// 5991-6008): `installemulation(emulation, opts)` then the on/off option
/// lists. Returns what it overwrote for [`restore_sticky_emulation`].
fn install_sticky_emulation(s: &crate::ported::zsh_h::emulation_options) -> SavedEmulation {
    use std::sync::atomic::Ordering;
    let size = crate::ported::zsh_h::OPT_SIZE as usize;
    let saved: Vec<bool> = (0..size)
        .map(|optno| {
            optno > 0
                && crate::ported::options::opt_state_get(crate::ported::zsh_h::opt_name(optno as i32))
                    .unwrap_or(false)
        })
        .collect();
    let saved_emu = (
        crate::ported::options::emulation.load(Ordering::Relaxed),
        crate::ported::options::EMULATION.load(Ordering::Relaxed),
        crate::ported::options::FULLY_EMULATING.load(Ordering::Relaxed),
    );
    let mut new_opts = [-1i8; crate::ported::zsh_h::OPT_SIZE as usize];
    crate::ported::options::installemulation(s.emulation, &mut new_opts); // c:5993
    for (optno, &v) in new_opts.iter().enumerate().skip(1) {
        if v >= 0 {
            crate::ported::options::opt_state_set(crate::ported::zsh_h::opt_name(optno as i32), v == 1);
        }
    }
    for on in &s.on_opts {
        crate::ported::options::opt_state_set(crate::ported::zsh_h::opt_name(*on as i32), true); // c:5995-6001
    }
    for off in &s.off_opts {
        crate::ported::options::opt_state_set(crate::ported::zsh_h::opt_name(*off as i32), false); // c:6002-6008
    }
    let emu_base = s.emulation & !crate::ported::zsh_h::EMULATE_FULLY;
    crate::ported::options::emulation.store(emu_base, Ordering::Relaxed);
    crate::ported::options::EMULATION.store(emu_base, Ordering::Relaxed);
    crate::ported::options::FULLY_EMULATING
        .store((s.emulation & crate::ported::zsh_h::EMULATE_FULLY) != 0, Ordering::Relaxed);
    (saved, saved_emu.0, saved_emu.1, saved_emu.2)
}

/// !!! WARNING: RUST-ONLY HELPER — NO C COUNTERPART !!!
///
/// Undo [`install_sticky_emulation`].
fn restore_sticky_emulation((opts, emu, emu_cell, fully): SavedEmulation) {
    use std::sync::atomic::Ordering;
    for (optno, on) in opts.into_iter().enumerate().skip(1) {
        crate::ported::options::opt_state_set(crate::ported::zsh_h::opt_name(optno as i32), on);
    }
    crate::ported::options::emulation.store(emu, Ordering::Relaxed);
    crate::ported::options::EMULATION.store(emu_cell, Ordering::Relaxed);
    crate::ported::options::FULLY_EMULATING.store(fully, Ordering::Relaxed);
}

/// !!! WARNING: RUST-ONLY HELPER — NO C COUNTERPART !!!
///
/// C loads an autoloaded body from INSIDE doshfunc: the stub's funcdef is
/// the `mkautofn` trampoline, so `execautofn` → `loadautofn` → `getfpfunc`
/// (c:Src/exec.c:5640, 5697) parses the file after doshfunc has entered the
/// stub's sticky emulation (c:5978-6010), and the body is installed IN
/// PLACE on the same Shfunc, keeping `shf->sticky` (stamped by
/// `shfunc_set_sticky` in bin_autoload, c:Src/builtin.c:3766). zshrs loads
/// and registers the body before doshfunc runs, so this guard opens the
/// same window for the load: the stub's emulation for the parse, and the
/// stub's snapshot as the pending `sticky` so the re-registration stamps it
/// onto the loaded function.
struct AutoloadStickyGuard {
    saved_opts: SavedEmulation,
    saved_sticky: Option<crate::ported::zsh_h::Emulation_options>,
}

impl AutoloadStickyGuard {
    fn enter(stub: &crate::ported::zsh_h::shfunc) -> Option<Self> {
        let s = stub.sticky.as_deref()?;
        if crate::ported::exec::sticky_emulation_differs(Some(s)) == 0 {
            return None;
        }
        let dup = crate::ported::exec::sticky_emulation_dup(s, 1);
        let saved_opts = install_sticky_emulation(&dup);
        let saved_sticky = std::mem::replace(
            &mut *crate::ported::options::sticky
                .lock()
                .unwrap_or_else(|e| e.into_inner()),
            Some(dup),
        );
        Some(Self {
            saved_opts,
            saved_sticky,
        })
    }
}

impl Drop for AutoloadStickyGuard {
    fn drop(&mut self) {
        *crate::ported::options::sticky
            .lock()
            .unwrap_or_else(|e| e.into_inner()) = self.saved_sticky.take();
        restore_sticky_emulation(std::mem::take(&mut self.saved_opts));
    }
}

/// !!! WARNING: RUST-ONLY HELPER — NO C COUNTERPART !!!
///
/// Names whose installed autoload body was rendered back from WORDCODE
/// (`getpermtext` over a `.zwc` program) rather than read from a source file,
/// each mapped to a digest of that body.
///
/// C has no such fact to carry. `loadautofn` hands the dump's program
/// straight to `shf->funcdef = stripkshdef(prog, …)` (c:Src/exec.c:5753-5755),
/// and the ksh-style arm runs it with `execode(prog, 1, 0, "evalautofunc")`
/// (c:Src/exec.c:5795): a dump-loaded funcdef is never lexed again, at load
/// time or ever. zshrs executes function bodies as TEXT, so `loadautofn`
/// deparses the program and the REAL compile happens later — at the call that
/// installs the function, through [`ShellExecutor::run_autoload_definition`].
/// The two are separated by arbitrary user code, so "this text came from
/// wordcode" has to survive the gap or the deparse is re-lexed against
/// whatever RCQUOTES / alias state is live at call time. See
/// [`ZwcRelexGuard`] for exactly what that costs; the `source` leg of the same
/// bug is fixed by [`ShellExecutor::execute_zwc_program`].
///
/// The mark is a DIGEST of the body, not a bare flag, so it self-invalidates.
/// `functions[name]=…` (c:Src/Modules/parameter.c setpmfunction) and a later
/// load of the same name from a plain file both install different text, and
/// the digest simply stops matching — no writer anywhere else has to know this
/// table exists, and a stale entry cannot pin the lexer for a body that was
/// never wordcode.
static AUTOLOAD_WORDCODE_BODY: Mutex<Option<HashMap<String, [u8; 32]>>> = Mutex::new(None);

/// !!! WARNING: RUST-ONLY HELPER — NO C COUNTERPART !!!
///
/// Record (`Some`) or drop (`None`) the "body came from wordcode" mark for
/// `name`. Called from `loadautofn` (c:Src/exec.c:5682) on every load, so a
/// plain-file load clears a mark an earlier dump load left.
pub(crate) fn autoload_note_wordcode_body(name: &str, body: Option<&str>) {
    let mut slot = AUTOLOAD_WORDCODE_BODY.lock();
    match body {
        Some(text) => {
            slot.get_or_insert_with(HashMap::new)
                .insert(name.to_string(), crate::autoload_cache::source_digest(text));
        }
        None => {
            if let Some(map) = slot.as_mut() {
                map.remove(name);
            }
        }
    }
}

/// !!! WARNING: RUST-ONLY HELPER — NO C COUNTERPART !!!
///
/// True when `body` is the exact text [`autoload_note_wordcode_body`] recorded
/// for `name` — i.e. this is a `.zwc` deparse about to be lexed a second time.
pub(crate) fn autoload_body_from_wordcode(name: &str, body: &str) -> bool {
    let slot = AUTOLOAD_WORDCODE_BODY.lock();
    slot.as_ref()
        .and_then(|map| map.get(name))
        .is_some_and(|sha| *sha == crate::autoload_cache::source_digest(body))
}

/// The exact source text an autoload of `name` installs — either the
/// file body verbatim (ksh style, or a file that already defines the
/// function) or `name() { <body> }`.
///
/// Split out of [`autoload_register_source`] with the ksh decision
/// passed IN so the prewarm (`autoload_prewarm`, which has no shfunc
/// flags to consult because nothing is registered yet) compiles
/// byte-identical text to what the loader will run. The two drifting
/// apart is precisely what made the pre-v2 shard unusable: it cached a
/// different program than the one the loader installs.
/// Returns the definition text plus whether that parse REJECTED the body
/// (c:Src/exec.c:6264 `r = parse_string(d, 1)` returning NULL, which makes
/// `loadautofn` abandon the load at c:5726 with no further diagnostic).
pub(crate) fn autoload_definition_source(
    name: &str,
    body: &str,
    ksh_style: bool,
) -> (String, bool) {
    // c:Src/exec.c:5781 — a ksh-style load executes the file contents at top
    // level (c:5795 `execode(prog, 1, 0, "evalautofunc")`) and expects the
    // file itself to define the function — so the body goes through the
    // pipeline VERBATIM, never wrapped.
    if ksh_style {
        return (body.to_string(), false); // c:5795 execode(prog, ..., "evalautofunc")
    }
    // c:6257-6265 — `getfpfunc` parses the file under the LOADEE's name:
    //     char *oldscriptname = scriptname;
    //     scriptname = dupstring(s);
    //     r = parse_string(d, 1);
    //     scriptname = oldscriptname;
    // so a syntax error in an autoloaded file is reported as
    // `_files:40: parse error: …`, not against the frame that triggered the
    // load. zshrs runs the only parse of the raw body right here, so the
    // same window belongs around it — without it the diagnostic came out as
    // `g:40:` for `g(){ emulate ksh -c _files }`.
    //
    // `scriptname` is one process-wide cell where C's is a single-thread
    // global, and a worker-thread compile prints nothing anyway (`zwarning`,
    // utils.rs:150, routes its diagnostics to the log) — so only the shell
    // thread takes the window, and no worker can blank out a prefix the shell
    // thread is in the middle of writing.
    let swap_scriptname = !crate::worker::in_worker_thread();
    let old_scriptname = crate::ported::utils::scriptname_get(); // c:6257
    if swap_scriptname {
        crate::ported::utils::set_scriptname(Some(name.to_string())); // c:6263
    }
    let saved_errflag = crate::ported::utils::errflag.load(std::sync::atomic::Ordering::Relaxed);
    crate::ported::utils::errflag.fetch_and(
        !crate::ported::utils::ERRFLAG_ERROR,
        std::sync::atomic::Ordering::Relaxed,
    );
    let prog = crate::ported::exec::parse_string(body, 1); // c:6329 `r = parse_string(d, 1);` — reset_lineno: errors count lines within the file
    let parse_failed = (crate::ported::utils::errflag.load(std::sync::atomic::Ordering::Relaxed)
        & crate::ported::utils::ERRFLAG_ERROR)
        != 0
        || prog.is_none();
    crate::ported::utils::errflag.store(saved_errflag, std::sync::atomic::Ordering::Relaxed);
    if swap_scriptname {
        crate::ported::utils::set_scriptname(old_scriptname); // c:6265
    }
    let stripped = prog
        .map(|prog| {
            let original_len = prog.prog.len();
            // stripkshdef returns the input untouched when the prog
            // doesn't match the single-`function NAME` shape, and a
            // shorter (body-only) prog when it does. Compare the
            // wordcode length to detect the strip without owning the
            // post-strip Eprog (we only need the yes/no answer here).
            let prog_box = Box::new(prog);
            crate::ported::exec::stripkshdef(Some(prog_box), name)
                .map(|p| p.prog.len() != original_len)
                .unwrap_or(false)
        })
        .unwrap_or(false);
    let text = if stripped {
        body.to_string()
    } else {
        format!("{name}() {{\n{body}\n}}")
    };
    (text, parse_failed)
}

// zsh_eval_context push/pop/sync relocated 2026-06-12 INTO doshfunc
// (src/ported/exec.rs) — its sole caller, and `zsh_eval_context` is
// that module's own static. The shell-visible mirror writes inline
// at the push site + the guard's Drop. No bridge indirection.

impl ShellExecutor {
    /// Execute the trap body for a signal name from the REPL signal
    /// loop (bins/zshrs.rs CtrlC/CtrlD dispatch). Thin passthru to
    /// `traps_table` lookup + `execute_script` — kept as a method
    /// because the REPL loop owns `&mut ShellExecutor` and needs a
    /// single call point. The async signal-handler dispatch path
    /// goes through `crate::ported::signals::dotrap` instead.
    pub fn run_trap(&mut self, signal: &str) {
        let action = crate::ported::builtin::traps_table()
            .lock()
            .ok()
            .and_then(|t| t.get(signal).cloned());
        if let Some(body) = action {
            if !body.is_empty() {
                let _ = self.execute_string_without_exit_hooks(&body);
            }
        }
    }
}

impl ShellExecutor {
    /// Expand glob pattern via canonical `glob_path` (port of
    /// `Src/glob.c::zglob`). Adds executor-side `current_command_glob_failed`
    /// cell so the dispatch layer skips the current command on NOMATCH +
    /// looks_like_glob instead of exiting the shell.
    pub fn expand_glob(&self, pattern: &str) -> Vec<String> {
        // c:Src/glob.c:1230-1233 — `if (unset(GLOBOPT) || !haswilds(ostr) ||
        // unset(EXECOPT)) { untokenize(ostr); return; }`: under NO_EXEC zglob
        // never globs, so no word (the command word included) can report
        // NOMATCH.
        if !crate::ported::zsh_h::isset(crate::ported::zsh_h::EXECOPT) {
            return vec![crate::ported::lex::untokenize(pattern)];
        }
        let errflag_before =
            crate::ported::utils::errflag.load(std::sync::atomic::Ordering::Relaxed);
        let expanded = glob_path(pattern);
        if !expanded.is_empty() {
            // c:Src/glob.c:1871-1872 — `if (matchct) badcshglob |= 2;`
            // (at least one expansion on this command line worked).
            // Only real glob patterns count — C's zglob early-returns
            // before the matchct accounting for non-wild words, so
            // gate on haswilds like the failure path below. Consumed
            // per command by fusevm_bridge::consume_badcshglob.
            if crate::ported::zsh_h::isset(crate::ported::zsh_h::CSHNULLGLOB) {
                let mut pattern_tok = pattern.to_string();
                crate::ported::glob::tokenize(&mut pattern_tok);
                if crate::ported::pattern::haswilds(&pattern_tok) {
                    crate::ported::glob::BADCSHGLOB
                        .fetch_or(2, std::sync::atomic::Ordering::Relaxed);
                }
            }
            return expanded;
        }
        // c:Src/glob.c:1786-1788 — `if (errflag) { restore_globstate(saved);
        // return; }`. A qualifier-parse error returns from `zglob` outright,
        // so C never reaches the c:1873-1886 nullglob/nomatch dispatch below.
        // The port has to re-derive `gf_nullglob` from the pattern because
        // `glob_path` hands back only a `Vec` — and that SECOND qualifier
        // parse re-runs every diagnostic the first one already emitted. It is
        // normally invisible because `zerr` suppresses itself while
        // ERRFLAG_ERROR is set (c:Src/utils.c:175), but a subscript qualifier
        // runs the lexer (`getindex` → `parse_subscript` → `strinbeg` →
        // `hbegin`, c:Src/hist.c:1115 `errflag &= ~ERRFLAG_ERROR`), which
        // clears exactly that bit — so `*(N[1,])` printed `bad math
        // expression: empty string` twice. Bail out where C's `return` lands.
        if crate::ported::utils::errflag.load(std::sync::atomic::Ordering::Relaxed) != 0 {
            // A diagnostic THIS glob raised (`bad pattern: a[B`, a bad
            // qualifier) belongs to the same per-command carrier as the
            // c:1877 NOMATCH below. C runs an external command's prefork
            // expansion in the child forked at Src/exec.c:3719, so the
            // `zerr` there only costs that child (status 1) and the list
            // goes on; a builtin expands in the shell and the errflag aborts
            // the list. The dispatch layer makes exactly that split for
            // `current_command_glob_failed`; without it `/bin/echo a[B;
            // print after` aborted the list and the `find` shadow ran with
            // the raw word after printing the diagnostic.
            if errflag_before == 0 {
                self.current_command_glob_failed.set(true);
            }
            return Vec::new();
        }
        // c:1871-1872 — `if (matchct) badcshglob |= 2;`: files DID match and
        // only the `[first,last]` subscript left none (`*([100])`), so this
        // is not a failed expansion — the word simply expands to nothing.
        if crate::ported::glob::CURGLOBDATA
            .lock()
            .unwrap_or_else(|e| e.into_inner())
            .matchct
            > 0
        {
            if crate::ported::zsh_h::isset(crate::ported::zsh_h::CSHNULLGLOB) {
                crate::ported::glob::BADCSHGLOB.fetch_or(2, std::sync::atomic::Ordering::Relaxed);
            }
            return Vec::new();
        }
        // No matches. Mirror zsh's `setopt nullglob` / `nomatch`
        // dispatch (Src/glob.c:1873-1886) here because glob_path
        // returns an empty Vec without knowing executor state.
        // c:Src/glob.c:1567-1569 `gf_nullglob` per-glob — the `(N)`
        // qualifier acts like `setopt nullglob` for this expression
        // alone. parse_qualifiers detects the suffix `(...)` block;
        // the resulting `qualifiers.nullglob` mirrors C's gf_nullglob
        // carrier.
        let per_glob_nullglob = crate::ported::glob::parse_qualifiers(pattern)
            .1
            .map(|q| q.nullglob)
            .unwrap_or(false);
        let nullglob = opt_state_get("nullglob").unwrap_or(false) || per_glob_nullglob;
        if nullglob {
            // c:Src/glob.c:1888-1894 —
            //   `else if (in_expandredir) {`
            //     `/* if completing for redirection, we can't remove the`
            //     `   pattern even if NULL_GLOB is in effect */`
            //     `zerr("redirection failed (no match): %s", ostr);`
            //     `zfree(matchbuf, 0);`
            //     `restore_globstate(saved);`
            //     `return;`
            //   `}`
            // Reached ONLY when gf_nullglob is set (the `else if` chain at
            // c:1873 owns every other no-match case), which is exactly the
            // `> file(N)` shape: dropping the word would leave the
            // redirection with no target at all, so `echo > nope(N)` failed
            // with an empty filename in `no such file or directory:`.
            if crate::ported::glob::IN_EXPANDREDIR.load(std::sync::atomic::Ordering::SeqCst) != 0 {
                zerr(&format!(
                    "redirection failed (no match): {}",
                    crate::ported::lex::untokenize(pattern)
                )); // c:1891
                self.current_command_glob_failed.set(true);
                return Vec::new(); // c:1894
            }
            return Vec::new();
        }
        let nomatch = opt_state_get("nomatch").unwrap_or(true);
        // Use canonical `haswilds` (port of Src/pattern.c:4306-4376)
        // instead of the Rust-only `looks_like_glob`. C zsh's
        // `Src/glob.c:1876` NOMATCH branch fires whenever the input
        // tripped haswilds during the `zglob` entry check —
        // including patterns whose internal `(` / `)` form a group
        // or alternation but don't end with `)` (e.g. `abc(a)def`,
        // `(abc`). The previous `looks_like_glob` only caught
        // trailing-`(...)` qualifiers, leaving mid-word groups and
        // unclosed parens to fall through to the literal-passthrough
        // branch. #170 in docs/BUGS.md.
        //
        // haswilds scans TOKENIZED strings (C's zglob gets the
        // lexer-tokenized word at Src/glob.c:1230); this entry point
        // receives untokenized fast-path patterns, so tokenize a
        // local copy first — the same preparation C applies to
        // runtime-built strings (compcore.c:2231 tokenizes fignore
        // entries before its haswilds call). tokenize Bnull's
        // backslash-escaped metachars, so `\*` stays literal here
        // exactly as in C. Bug #627: plain multibyte text (`↔`)
        // passes through tokenize unchanged and matches no token.
        let mut pattern_tok = pattern.to_string();
        crate::ported::glob::tokenize(&mut pattern_tok); // c:Src/glob.c:3548
        let is_glob = crate::ported::pattern::haswilds(&pattern_tok);
        // c:Src/glob.c:1874-1875 — `if (isset(CSHNULLGLOB)) {
        // badcshglob |= 1; }` — the else-if chain means neither the
        // NOMATCH error nor the literal passthrough runs: the failed
        // word is silently DROPPED here, and the per-command boundary
        // (fusevm_bridge::consume_badcshglob, Src/subst.c:505-507)
        // emits the csh-style `no match` iff NO glob on the line
        // matched.
        if is_glob && crate::ported::zsh_h::isset(crate::ported::zsh_h::CSHNULLGLOB) {
            crate::ported::glob::BADCSHGLOB.fetch_or(1, std::sync::atomic::Ordering::Relaxed);
            return Vec::new();
        }
        if nomatch && is_glob {
            // c:Src/glob.c:1876-1880 — `else if (isset(NOMATCH)) {`
            //   `zerr("no matches found: %s", ostr);`
            //   `zfree(matchbuf, 0);`
            //   `restore_globstate(saved);`
            //   `return;`
            // `}`
            // C aborts via ERRFLAG_ERROR set by zerr() at c:Src/utils.c
            // and the matchbuf/state cleanup. The Rust port mirrors
            // both: zerr() in utils.rs sets ERRFLAG_ERROR via
            // `errflag.fetch_or(ERRFLAG_ERROR, ...)` already; we then
            // re-set explicitly (defensive — historically this line
            // had `fetch_and(!ERRFLAG_ERROR)` which CLEARED the flag
            // immediately after zerr, making `echo /never/*` print
            // the literal and exit 0 instead of erroring like zsh —
            // parity bug #13).
            // c:1877 `zerr("no matches found: %s", ostr);` — `ostr` is
            // the TOKENIZED word, and zerrmsg's `%s` arm renders it
            // through `nicezputs` → `sb_niceformat`, which calls
            // `untokenize(ums)` (Src/utils.c). Without that step the
            // token bytes are dropped by the terminal and the message
            // reads `no matches found: /tmp/nope_.txt`.
            zerr(&format!(
                "no matches found: {}",
                crate::ported::lex::untokenize(pattern)
            )); // c:1877
            self.current_command_glob_failed.set(true);
            // c:Src/glob.c:1876-1880 — zerr sets ERRFLAG_ERROR and
            // glob_failed cell carries the signal. The ERRFLAG_ERROR
            // clear (so subsequent sublists run) now lives at the
            // dispatcher's post-command-boundary at
            // fusevm_bridge.rs:299 where current_command_glob_failed
            // is consumed — matches C's execlist behavior of clearing
            // command-error errflag between sublists.
            return Vec::new(); // c:1880 return
        }
        // Pattern has no glob meta — pass through literally.
        // c:Src/glob.c:1882-1886 — `/* treat as an ordinary string */
        // untokenize(matchptr->name = dupstring(ostr));`. The word
        // arrives here in LEXER-TOKENIZED form (c:1221 `ostr =
        // getdata(np)`), so the literal fallback MUST untokenize or the
        // raw token bytes reach stdout: `unsetopt nomatch; echo
        // /tmp/nope_*.txt` printed `/tmp/nope_\u{e187}.txt`.
        vec![crate::ported::lex::untokenize(pattern)]
    }
    /// 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
    }
}

impl ShellExecutor {
    pub(crate) fn copy_dir_recursive(src: &Path, dest: &Path) -> io::Result<()> {
        if !dest.exists() {
            fs::create_dir_all(dest)?;
        }
        for entry in 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 {
                fs::copy(&src_path, &dest_path)?;
            }
        }
        Ok(())
    }
}

// Magic-assoc scan-by-name aggregator. C's per-table getfn/scanfn
// pointers in paramdef[] (Src/Modules/parameter.c:825+) handle this
// indirectly via paramtab dispatch; this Rust-only helper exposes a
// single `partab_get` / `partab_scan_keys` entry that the bridge
// uses for name → keys lookup.
use std::cell::RefCell;
thread_local! {
    static SCAN_KEYS: RefCell<Vec<String>> = const { RefCell::new(Vec::new()) };
}

/// Lookup helper for `${name[key]}` magic-assoc reads — dispatches
/// through canonical `PARTAB` (Src/Modules/parameter.c:2235 ports).
/// Returns `None` if name isn't a known magic-assoc.
/// Module parameters that have actually been touched this session.
///
/// zshrs-original bookkeeping for a C behavior that falls out of the module
/// system there. zsh registers `zsh/parameter`'s params (`aliases`,
/// `commands`, `functions`, …) as PM_AUTOLOAD stubs in `realparamtab`;
/// touching ONE of them materializes only that name — its siblings stay
/// stubs even though the module is now loaded. `paramtypestr`
/// (Src/Modules/parameter.c:49-50) reports a PM_AUTOLOAD node as
/// "undefined", which is what an enumeration of `$parameters` shows.
/// zshrs seeds all of them eagerly (init_partab_params), so without this
/// set every one reported its real type and `${(@k)parameters[(R)a*]}`
/// matched 56 names against zsh's 18 — putting them in the wrong
/// `_parameters -g` bucket (`unset <TAB>`: 418 entries vs zsh's 496).
static MATERIALIZED_MODULE_PARAMS: std::sync::OnceLock<Mutex<HashSet<String>>> =
    std::sync::OnceLock::new();

/// Record that `name` was read/written, so `$parameters` stops reporting it
/// as an unmaterialized autoload stub. See [`MATERIALIZED_MODULE_PARAMS`].
pub fn mark_module_param_used(name: &str) {
    let set = MATERIALIZED_MODULE_PARAMS.get_or_init(|| Mutex::new(HashSet::new()));
    let first_touch = {
        let mut g = set.lock();
        // Drop the guard before the module load below — `boot_` runs shell
        // code (setsparam/setiparam) that can re-enter this function.
        g.insert(name.to_string())
    };
    if first_touch {
        materialize_module_param(name);
    }
}

/// The side effect C's `loadparamnode` (`Src/params.c:563-585`) has beyond
/// clearing PM_AUTOLOAD: `(void)ensurefeature(mn, "p:", nam)`
/// (`Src/module.c:3419-3432`) actually LOADS the owning module, running its
/// `setup_`/`boot_`. `zsh/watch`'s `boot_` (`Src/Modules/watch.c:750-753`)
/// seeds `WATCHFMT`/`LOGCHECK` when absent, so in zsh
/// `${parameters[watch]}` leaves `${parameters[LOGCHECK]}` == "integer".
///
/// !!! WARNING: RUST-ONLY HELPER !!!
/// C has no separate function: `loadparamnode` calls `ensurefeature`
/// inline. zshrs models PM_AUTOLOAD as a side-set rather than a node flag
/// (see [`MATERIALIZED_MODULE_PARAMS`]), so the load side effect needs its
/// own hook off the marking point. The `try_lock` and the re-entrancy guard
/// are also Rust-only: C serialises on `queue_signals`, whereas zshrs's
/// `MODULESTAB` is a real mutex that several callers of
/// `mark_module_param_used` already hold.
fn materialize_module_param(name: &str) {
    use std::cell::Cell;
    thread_local! {
        static LOADING: Cell<bool> = const { Cell::new(false) };
    }
    // c:Src/params.c:566 — only PM_AUTOLOAD stubs carry `pm->u.str` (the
    // owning module name); anything else falls straight through.
    let Some((_, modname)) = AUTOLOAD_PARAMS.iter().find(|(p, _)| *p == name) else {
        return;
    };
    if LOADING.with(|f| f.get()) {
        return;
    }
    // The whole load chain wants `&mut modulestab`. Every other caller takes
    // the same lock for a moment; if one of them is mid-flight (or is our own
    // caller), skip rather than deadlock — the mark itself already landed.
    let Ok(mut tab) = crate::ported::module::MODULESTAB.try_lock() else {
        return;
    };
    // c:Src/module.c:2352 — require_module short-circuits on an already
    // booted module, but check first so the common case never pays for the
    // find_module/alias walk.
    if tab
        .modules
        .get(*modname)
        .is_some_and(|m| (m.node.flags & crate::ported::zsh_h::MOD_INIT_B) != 0)
    {
        return;
    }
    LOADING.with(|f| f.set(true));
    // c:3419-3432 ensurefeature(mn, "p:", nam) — `silent` is 0 in C, but a
    // failure here is not user-visible in the autoload path (c:571-580 only
    // errors when the parameter is still undefined afterwards), and zshrs's
    // require_module warns on any module it cannot static-link.
    let _ = crate::ported::module::ensurefeature(&mut tab, modname, "p:", Some(name)); // c:3419
    LOADING.with(|f| f.set(false));
}

/// Undo [`mark_module_param_used`] — the `pd->pm = NULL` half of C's
/// `deleteparamdef` (`Src/module.c:1128-1179`), reached from
/// `setparamdefs` (`c:1176-1180`) whenever a module feature is turned OFF
/// (`zmodload -F zsh/parameter -p:functions`, or a single-feature load
/// leaving the siblings disabled).
///
/// !!! WARNING: RUST-ONLY HELPER !!!
/// C has no separate function: `deleteparamdef` removes the node from
/// `paramtab` outright. zshrs seeds every magic parameter eagerly and models
/// PM_AUTOLOAD as the [`MATERIALIZED_MODULE_PARAMS`] side-set, so "removed"
/// is "back to being an unmaterialized stub".
pub fn unmark_module_param_used(name: &str) {
    let set = MATERIALIZED_MODULE_PARAMS.get_or_init(|| Mutex::new(HashSet::new()));
    set.lock().remove(name);
}

/// True when `name` is still an untouched module-parameter stub — i.e. zsh
/// would report it as PM_AUTOLOAD ("undefined") when enumerating
/// `$parameters`. See [`MATERIALIZED_MODULE_PARAMS`].
pub fn module_param_is_autoload_stub(name: &str) -> bool {
    if !AUTOLOAD_PARAMS.iter().any(|(p, _)| *p == name) {
        return false;
    }
    MATERIALIZED_MODULE_PARAMS
        .get_or_init(|| Mutex::new(HashSet::new()))
        .lock()
        .contains(name)
        .eq(&false)
}

/// True when the magic special parameter `name` (a `partab[]` row from
/// `Src/Modules/parameter.c:2235-2298` — `options`, `functions`,
/// `commands`, `parameters`, `dirstack`, …) is currently SHADOWED by a
/// plain user parameter of the same name.
///
/// Rust-only helper with no C counterpart BY CONSTRUCTION: C zsh keeps
/// specials and user parameters in the ONE `paramtab` hash, so ordinary
/// hash lookup already implements this. `createparam`
/// (c:Src/params.c:1090-1115) finds the existing special node, stashes
/// it in `pm->old`, and inserts a fresh plain node under the same key;
/// every later `getvalue` / `fetchvalue` / `gethashparam` therefore hits
/// the plain node and the special's `gsu` callbacks are unreachable
/// until `endparamscope` restores `pm->old`. zshrs instead keeps the
/// magic rows in SEPARATE static tables (`PARTAB`, `PARTAB_ARRAY`) and
/// matches them BY NAME, so a name-only match resurrected the special
/// even while a local shadowed it. This predicate re-imposes C's
/// shadowing on the split-table layout; it is architecture glue, not a
/// port.
///
/// `init_partab_params` (below) seeds every magic row into `paramtab`
/// with `PM_SPECIAL` (C's `SPECIALPMDEF` macro), and `local`/`typeset`
/// replaces that node with one carrying no `PM_SPECIAL`, so the live
/// node's `PM_SPECIAL` bit is exactly C's "is the special still the
/// visible binding" test.
///
/// Returns false when a MODULE-GATED row (`sysparams`, `errnos`,
/// `mapfile`, `langinfo`) has no `paramtab` node and its module is not
/// loaded: those are seeded on
/// demand by `seed_partab_param`, and the PARTAB walk must still answer
/// for them (their own `module` gate decides).
///
/// For every other magic row an ABSENT node means the binding is gone —
/// `unset` removed it. C reaches the same answer through one gate:
/// `Src/params.c:2264-2266` `if (!pm || ((pm->node.flags & PM_UNSET) &&
/// !(pm->node.flags & PM_DECLARED))) return NULL;` in `fetchvalue`, the
/// single choke point every `${X}` / `${#X}` / `${(k)X}` / `${(t)X}` /
/// `${X[k]}` read passes through. Both of its arms show up here:
///  * `!pm` — `unset functions` at a point where the name is still the
///    `PM_AUTOLOAD` stub (`Src/module.c:1218-1223`) finds a PLAIN
///    `PM_SCALAR` node with neither `PM_SPECIAL` nor `PM_READONLY`, so
///    `unsetparam_pm`'s c:3851-3852 keep-the-node test
///    (`(flags & (PM_SPECIAL|PM_REMOVABLE)) == PM_SPECIAL`) is false and
///    c:3874 `paramtab->removenode` drops it outright.
///  * `PM_UNSET && !PM_DECLARED` — once the special HAS been
///    materialized, c:3851-3852 keeps the node and `stdunsetfn`
///    (c:3939) marking `PM_UNSET` is the entire record of the unset;
///    `setpmfunctions(pm, NULL)` returns immediately on `if (!ht)
///    return` (`Src/Modules/parameter.c:361-362`), so `shfunctab` — the
///    real table behind the row — survives untouched and `ff` still runs.
///
/// Both arms mean the same thing for a split-table port: the magic row
/// is no longer the visible binding for this name, exactly as when a
/// `local` shadows it. Answering that one question here is what lets
/// every PARTAB dispatch site keep a single guard.
///
/// Symptom this fixes: git's `git-completion.bash`
/// `__git_resolve_builtins` does `local options; eval
/// "options=\${$var-}"` (git 2.55.0
/// share/zsh/site-functions/git-completion.bash:500-501). `$options`
/// read back the zsh/parameter option table (`off on off …`) instead of
/// the local, so `git checkout --<TAB>` completed nothing.
pub fn magic_special_shadowed(name: &str) -> bool {
    // Only `partab[]` names can be shadowed in this sense — an ordinary
    // user assoc / array has no special behind it, and its own paramtab
    // node legitimately carries no PM_SPECIAL.
    if !PARTAB.iter().any(|e| e.name == name) && !PARTAB_ARRAY.iter().any(|e| e.name == name) {
        return false;
    }
    // A module-gated row (`errnos`, `sysparams`, `mapfile`, `langinfo`)
    // gets its paramtab node from the owning module's setparamdefs
    // (Src/module.c:1169-1196), so while that module is loaded an absent
    // node means its `p:` feature is off: deleteparamdef (c:1190) removed
    // it, or the module was loaded with other features only. Read the
    // module state before taking the paramtab lock.
    let gated_loaded = module_gated_partab_module(name)
        .map(|m| crate::ported::module::MODULESTAB.lock().unwrap().is_loaded(m));
    crate::ported::params::paramtab()
        .read()
        .map_or(false, |tab| {
            let Some(pm) = tab.get(name) else {
                // c:Src/params.c:2264 `if (!pm ...) return NULL` —
                // `unset` removed the node (see the doc comment). Only
                // a valid reading once the rows have been seeded. A
                // gated row whose module is not loaded is left to the
                // module gate in partab_get / partab_array_get.
                return match gated_loaded {
                    Some(loaded) => loaded,
                    None => PARTAB_SEEDED.load(std::sync::atomic::Ordering::Acquire),
                };
            };
            {
                // c:Src/params.c:2264-2266 — `(pm->node.flags & PM_UNSET)
                // && !(pm->node.flags & PM_DECLARED)`: the materialized
                // special was unset and the node kept (c:3851-3852).
                let f = pm.node.flags as u32;
                if (f & crate::ported::zsh_h::PM_UNSET) != 0
                    && (f & crate::ported::zsh_h::PM_DECLARED) == 0
                {
                    return true;
                }
            }
            {
                // c:Src/module.c:1029-1052 checkaddparam — `if (pm->level ||
                // !(pm->node.flags & PM_AUTOLOAD))` is C's OWN test for "is
                // this node a blocker or the module's own placeholder": a
                // GLOBAL PM_AUTOLOAD node is the autoload STUB
                // `add_autoparam` planted (c:1222-1223 `setsparam(pnam,
                // module); pm->node.flags |= PM_AUTOLOAD` — its VALUE is the
                // owning module's name), and C replaces it with the real
                // special via `unsetparam_pm` (c:1051) + `createspecialhash`
                // (c:1068) the moment the module loads. Reading the name is
                // what triggers that: c:Src/params.c:563-585 loadparamnode
                // runs `ensurefeature(mn, "p:", nam)` and re-fetches the node.
                // So a stub NEVER makes the special unreachable — treating it
                // as a shadow left `${options}` reading the stub's own scalar
                // value ("zsh/parameter") and killed every magic-assoc read
                // for that name for the rest of the session. A LOCAL stub
                // (pm->level != 0) still blocks, exactly as c:1032 says.
                let f = pm.node.flags as u32;
                if pm.level == 0 && (f & crate::ported::zsh_h::PM_AUTOLOAD) != 0 {
                    return false;
                }
                (f & crate::ported::zsh_h::PM_SPECIAL) == 0
            }
        })
}

/// [`magic_special_shadowed`] AND the shadow is not itself a hash.
///
/// "No longer the magic row" is not the same as "no longer a hash". C
/// decides the subscript dispatch — and every whole-map read — from the
/// TYPE of the node paramtab actually returned:
///   c:Src/params.c:2270 `if (PM_TYPE(pm->node.flags) & (PM_ARRAY|PM_HASHED))`
///   c:Src/params.c:1597-1606 getarg —
///       if (ishash) {
///           HashTable ht = v->pm->gsu.h->getfn(v->pm);
///           ...
///           if (!(v->pm = (Param) ht->getnode(ht, s))) ...
/// So a shadow that IS itself PM_HASHED (`local -A commands`, or
/// `local -A +h commands` as in Completion/Zsh/Type/_command_names:70)
/// owns a table of its own and must be SERVED FROM IT, while a scalar or
/// array shadow (`local options`, `local -a options`) must fall through
/// to the non-hash arms.
///
/// Bailing on every shadowed magic name made the hashed shadow invisible
/// to each reader in turn: the keyed read (`$commands[fake]`), then
/// `${#commands}`, `${(k)commands}`, `${(kv)commands}` and
/// `${commands[(I)pat]}`. The values were in `paramtab_hashed_storage`
/// the whole time — `${commands[@]}` found them — only these guards
/// refused to look. Every dispatch site that means "the magic row is not
/// the visible binding, and there is no hash behind it either" asks
/// through here so the qualification cannot drift between them.
pub fn magic_special_shadowed_by_nonhash(name: &str) -> bool {
    magic_special_shadowed(name)
        && crate::ported::params::paramtab()
            .read()
            .ok()
            .and_then(|t| t.get(name).map(|pm| pm.node.flags as u32))
            // c:2270 — PM_TYPE decides; absent node ⇒ nothing to serve; c:2264-2266 — nor
            // does an unset, undeclared node (`zmodload zsh/parameter; unset functions`).
            .map_or(true, |f| {
                use crate::ported::zsh_h::{PM_DECLARED, PM_TYPE, PM_UNSET};
                PM_TYPE(f) != PM_HASHED || (f & (PM_UNSET | PM_DECLARED)) == PM_UNSET
            })
}

pub fn partab_get(name: &str, key: &str) -> Option<String> {
    // C's paramtab lookup would already have found the shadowing local;
    // the split-table port needs the explicit check.
    if magic_special_shadowed(name) {
        return None;
    }
    mark_module_param_used(name);
    // c:Src/Modules/system.c:902,904 — `sysparams` and `errnos` are
    // bound by zsh/system's boot_/setup_ chain. Same for `mapfile`
    // from zsh/mapfile. Without explicit `zmodload`, these names
    // are unset in zsh; gate the PARTAB dispatch here so they
    // resolve via the empty-fallback path (matching ${sysparams[k]:-x}
    // taking the default). Bug #69 in docs/BUGS.md.
    if let Some(modname) = module_gated_partab_module(name) {
        if !crate::ported::module::MODULESTAB
            .lock()
            .unwrap()
            .is_loaded(modname)
        {
            return None;
        }
    }
    for entry in PARTAB.iter() {
        if entry.name == name {
            // c:Src/Modules/parameter.c — a row getfn (`getpmfunction`,
            // `getpmcommand`, `getpmoption`, …) answers a missing key with a
            // node carrying `PM_UNSET` (e.g. getfunction, parameter.c:449 `pm->node.flags |=
            // (PM_UNSET|PM_SPECIAL)`), which `IS_UNSET_VALUE` (params.c:479)
            // and `issetvar` (params.c:764-765) read as unset. Keep that
            // distinction: dropping the flag turned a miss into a set empty
            // value, so `[[ -v functions[nosuch] ]]` was true.
            return (entry.getfn)(std::ptr::null_mut(), key)
                .filter(|p| p.node.flags as u32 & crate::ported::zsh_h::PM_UNSET == 0)
                .and_then(|p| p.u_str);
        }
    }
    None
}

/// Returns the owning module name for partab entries that are
/// bound by an explicit zmodload — `sysparams`/`errnos` from
/// zsh/system, `mapfile` from zsh/mapfile. Other partab entries
/// (aliases/commands/functions/...) are part of zsh/main and
/// always available.
fn module_gated_partab_module(name: &str) -> Option<&'static str> {
    match name {
        "sysparams" | "errnos" => Some("zsh/system"),
        "mapfile" => Some("zsh/mapfile"),
        "langinfo" => Some("zsh/langinfo"),
        ".zle.esc" | ".zle.sgr" => Some("zsh/hlgroup"),
        ".sh.match" => Some("zsh/ksh93"),
        _ => None,
    }
}

/// Publish a value into a read-only special from shell-INTERNAL code.
///
/// C binds these params to C variables through a gsu vtable —
/// `compvarscalar_gsu` for `$QIPREFIX`/`$QISUFFIX`
/// (Src/Zle/complete.c:1308-1324), `keymap_gsu` for `$KEYMAP`
/// (Src/Zle/zle_params.c:151) — and the shell's own writes go straight
/// to that variable. PM_READONLY is only consulted on the ASSIGNMENT
/// path (`assignsparam`, Src/params.c), so the bit stops a user's
/// `QIPREFIX=x` without ever standing in the way of the completion
/// machinery's own publish.
///
/// zshrs keeps the value in the param itself, so the internal publish
/// has to step around the same gate explicitly: drop PM_READONLY,
/// assign through the canonical path, put the bit back.
pub fn set_readonly_special(name: &str, value: &str) {
    use crate::ported::zsh_h::PM_READONLY;
    let was_readonly = crate::ported::params::paramtab()
        .write()
        .ok()
        .and_then(|mut tab| {
            tab.get_mut(name).map(|pm| {
                let ro = (pm.node.flags & PM_READONLY as i32) != 0;
                pm.node.flags &= !(PM_READONLY as i32);
                ro
            })
        })
        .unwrap_or(false);
    let _ = crate::ported::params::setsparam(name, value);
    if was_readonly {
        if let Ok(mut tab) = crate::ported::params::paramtab().write() {
            if let Some(pm) = tab.get_mut(name) {
                pm.node.flags |= PM_READONLY as i32;
            }
        }
    }
}

/// PM_ARRAY lookup for `${name}` / `${name[N]}` — walks
/// PARTAB_ARRAY and dispatches the whole-array getfn (Src/Modules/
/// parameter.c:2239-2291 ports). Returns `None` if name isn't a
/// known PM_ARRAY magic-assoc.
pub fn partab_array_get(name: &str) -> Option<Vec<String>> {
    // c:Src/params.c:1090-1115 createparam — see `partab_get`.
    if magic_special_shadowed(name) {
        return None;
    }
    mark_module_param_used(name);
    // Bug #69 — gate module-bound PARTAB names on the owning
    // module's MOD_LINKED && !MOD_UNLOAD state.
    if let Some(modname) = module_gated_partab_module(name) {
        if !crate::ported::module::MODULESTAB
            .lock()
            .unwrap()
            .is_loaded(modname)
        {
            return None;
        }
    }
    for entry in PARTAB_ARRAY.iter() {
        if entry.name == name {
            return Some((entry.getfn)(std::ptr::null_mut()));
        }
    }
    None
}

/// Scan helper for `${(k)name}` — enumerates keys via canonical
/// scanfn, collected into Vec via SCAN_KEYS thread-local.
pub fn partab_scan_keys(name: &str) -> Option<Vec<String>> {
    // c:Src/params.c:1090-1115 createparam — see `partab_get`.
    if magic_special_shadowed(name) {
        return None;
    }
    mark_module_param_used(name);
    // Bug #69 — gate module-bound PARTAB names on the owning
    // module's MOD_LINKED && !MOD_UNLOAD state.
    if let Some(modname) = module_gated_partab_module(name) {
        if !crate::ported::module::MODULESTAB
            .lock()
            .unwrap()
            .is_loaded(modname)
        {
            return None;
        }
    }
    for entry in PARTAB.iter() {
        if entry.name == name {
            SCAN_KEYS.with(|k| k.borrow_mut().clear());
            // c:Src/Modules/parameter.c — a param-table ScanFunc receives
            // `&pm.node` of a fully populated `struct param`; the Rust side
            // models that as `ParamScanFunc = fn(&param, i32)`.
            fn cb(pm: &crate::ported::zsh_h::param, _flags: i32) {
                SCAN_KEYS.with(|k| k.borrow_mut().push(pm.node.nam.clone()));
            }
            // c:Src/params.c:3138 — `paramvalarr(…, SCANPM_WANTKEYS)`: keys
            // only, so a scanfn need not materialize the value side.
            (entry.scanfn)(
                std::ptr::null_mut(),
                Some(cb),
                crate::ported::zsh_h::SCANPM_WANTKEYS as i32,
            );
            return Some(SCAN_KEYS.with(|k| k.borrow().clone()));
        }
    }
    None
}
/// Populate paramtab with PM_SPECIAL placeholder Params for every
/// PARTAB / PARTAB_ARRAY entry — Rust-only init helper, no direct
/// C counterpart (closest is `handlefeatures` walking `partab[]`
/// in `Src/Modules/parameter.c:2341` boot/enables chain).
///
/// Each magic-assoc name gets a Param with `entry.flags | PM_SPECIAL`.
/// Value reads still route through `partab_get` / `partab_array_get`;
/// having the Param in paramtab makes `paramtab.get(name)` return
/// Some(Param) so `${+name}` / `${(t)name}` / `typeset -p name` see
/// the entry. Without this, those reads returned empty for every
/// magic-assoc (aliases, commands, functions, etc.).
///
/// Called from ShellExecutor::new() since zshrs's bin entry skips
/// the canonical module-bootstrap chain.
pub fn init_partab_params() {
    use crate::ported::modules::parameter::{PARTAB, PARTAB_ARRAY};
    use crate::ported::zsh_h::{
        hashnode, param, Param, PM_HIDE, PM_HIDEVAL, PM_READONLY, PM_SPECIAL,
    };
    let mut tab = match paramtab().write() {
        Ok(t) => t,
        Err(_) => return,
    };
    // c:Src/zsh.h SPECIALPMDEF macro: `flags | PM_SPECIAL | PM_HIDE |
    // PM_HIDEVAL`. All magic-assoc/array params get HIDE+HIDEVAL added
    // by the macro itself.
    //
    // PM_READONLY is preserved on the stub for params that legitimately
    // need user-write protection (reswords, dis_reswords, patchars,
    // dis_patchars — all compute via getfn and have no legitimate
    // internal-write path). Other specials that DO have internal-write
    // paths (e.g. funcstack from function-call tracking) get the bit
    // stripped so the runtime can mutate their u_arr. Bug #374.
    // `parameters` is computed entirely by getpmparameter and has no
    // internal-write path either (zsh: PM_READONLY_SPECIAL, c:2287), so it
    // keeps the bit — `${parameters[parameters]}` reads
    // `association-readonly-hide-hideval-special` in zsh.
    // The remaining names below are the rest of C's PM_READONLY_SPECIAL
    // rows whose `partab[]` entry has a NULL gsu (c:2237/2243/2255/2265/
    // :2272/2276-2280/2284/2296-2298 + Src/Zle/zleparameter.c:133): they
    // are computed purely by their getfn/scanfn, so there is nothing for
    // the runtime to write and the bit is safe to keep. Without them
    // `${(t)builtins}` and friends reported
    // `association-hide-hideval-special` where zsh reports
    // `association-readonly-hide-hideval-special`.
    let user_protected: &[&str] = &[
        "parameters",
        "reswords",
        "dis_reswords",
        "patchars",
        "dis_patchars",
        "historywords",
        "errnos",
        "keymaps",
        "builtins",             // c:2237
        "dis_builtins",         // c:2243
        "functions_source",     // c:2265
        "dis_functions_source", // c:2247
        "history",              // c:2272
        "jobdirs",              // c:2276
        "jobstates",            // c:2278
        "jobtexts",             // c:2280
        "modules",              // c:2284
        "userdirs",             // c:2296
        "usergroups",           // c:2297
        "widgets",              // c:Src/Zle/zleparameter.c:133
        // c:2279-2280 — `SPECIALPMDEF("funcstack", PM_ARRAY|
        // PM_READONLY_SPECIAL, &funcstack_gsu, NULL, NULL)`. The bit was
        // being stripped here on the theory that the runtime writes
        // `funcstack`'s `u_arr`; it does not — `funcstackgetfn`
        // (PARTAB_ARRAY, parameter.rs:4726-4732) computes the value from
        // the `FUNCSTACK` global on every read and the row's `setfn` is
        // `None`, so there is nothing to protect against. Without the bit
        // `${(t)funcstack}` read `array-hide-hideval-special` where zsh
        // reads `array-readonly-hide-hideval-special`, which put it in the
        // wrong `_parameters -g '^*(readonly|association)*'` bucket and
        // added one candidate zsh does not offer.
        "funcstack", // c:2279
        // Same argument as `funcstack` above, for the three sibling trace
        // arrays: `SPECIALPMDEF(..., PM_ARRAY|PM_READONLY_SPECIAL, ...)` in C
        // and `setfn: None` in PARTAB_ARRAY (parameter.rs:4717/4725/4741), so
        // they are getfn-computed with no internal-write path to protect.
        "funcfiletrace",   // c:2275
        "funcsourcetrace", // c:2277
        "functrace",       // c:2285
        // c:Src/Modules/termcap.c:312 / Src/Modules/terminfo.c:305 —
        // `SPECIALPMDEF("termcap", PM_READONLY, NULL, gettermcap, scantermcap)`
        // and the terminfo twin: NULL gsu, value produced entirely by the
        // getnode/scan fns, so the readonly bit has nothing to fight.
        "termcap",  // c:Src/Modules/termcap.c:312
        "terminfo", // c:Src/Modules/terminfo.c:305
        // c:Src/Builtins/sched.c:382 — `SPECIALPMDEF(
        // "zsh_scheduled_events", PM_ARRAY|PM_READONLY, &sched_gsu,
        // NULL, NULL)`. Same shape as `funcstack` above: `schedgetfn`
        // (sched.rs:582) walks the schedcmds list on every read and the
        // PARTAB_ARRAY row's `setfn` is `None`, so no internal write
        // needs the bit cleared. `sched`/`sched -N` mutate the list,
        // never the param.
        "zsh_scheduled_events", // c:Src/Builtins/sched.c:382
    ];
    let mk_pm = |name: &str, flags: i32| -> Param {
        let keep_readonly = user_protected.contains(&name);
        let pre_readonly_mask = if keep_readonly {
            !0i32
        } else {
            !(PM_READONLY as i32)
        };
        Box::new(param {
            node: hashnode {
                next: None,
                nam: name.to_string(),
                flags: (flags & pre_readonly_mask)
                    | PM_SPECIAL as i32
                    | PM_HIDE as i32
                    | PM_HIDEVAL as i32,
            },
            u_data: 0,
            u_tied: None,
            u_arr: None,
            u_str: None,
            u_val: 0,
            u_dval: 0.0,
            u_hash: None,
            gsu_s: None,
            gsu_i: None,
            gsu_f: None,
            gsu_a: None,
            gsu_h: None,
            base: 0,
            width: 0,
            env: None,
            ename: None,
            old: None,
            level: 0,
        })
    };
    // c:Src/Modules/system.c:902,904 + Src/Modules/mapfile.c — these
    // params are provided by modules that real zsh requires explicit
    // `zmodload` for. Seeding them unconditionally makes
    // `${+sysparams}` return 1 by default (bug #69 in docs/BUGS.md),
    // diverging from zsh which returns 0 until the user runs
    // `zmodload zsh/system`. Skip here; `seed_partab_param` below adds
    // them on demand from the module's load path.
    let module_gated: &[&str] = &[
        "sysparams", // zsh/system
        "errnos",    // zsh/system
        "mapfile",   // zsh/mapfile
        "langinfo",  // zsh/langinfo
        ".zle.esc",  // zsh/hlgroup
        ".zle.sgr",  // zsh/hlgroup
        ".sh.match", // zsh/ksh93
    ];
    // c:Src/module.c:1065 `addparamdef` — `checkaddparam` (c:1026) finds
    // the PM_AUTOLOAD stub `init_bltinmods` planted, calls
    // `unsetparam_pm(pm, 0, 1)` which UNLINKS the node (c:1052), and only
    // then does `createparam` re-add it — so the real param takes a FRESH
    // chain slot, it does not inherit the stub's. `hashtable_nodes::
    // insert` is `addhashnode2` (Src/hashtable.c:168), which replaces an
    // existing key IN PLACE (c:187-203) and would pin the special to the
    // stub's slot; remove first to reproduce C. Visible in
    // `${(k)parameters}`: without the remove, `dis_reswords` and
    // `usergroups` came out one position off from `zsh -f`.
    for entry in PARTAB.iter() {
        if module_gated.contains(&entry.name) {
            continue;
        }
        tab.remove(entry.name); // c:1052 unsetparam_pm
        tab.insert(entry.name.to_string(), mk_pm(entry.name, entry.flags));
    }
    for entry in PARTAB_ARRAY.iter() {
        if module_gated.contains(&entry.name) {
            continue;
        }
        tab.remove(entry.name); // c:1052 unsetparam_pm
        tab.insert(entry.name.to_string(), mk_pm(entry.name, entry.flags));
    }
    // See `PARTAB_SEEDED` — every magic row now has its paramtab node,
    // so from here on a MISSING node is a real "no binding" answer.
    PARTAB_SEEDED.store(true, std::sync::atomic::Ordering::Release);
}

/// !!! WARNING: RUST-ONLY HELPER !!!
///
/// True once [`init_partab_params`] has finished planting a paramtab
/// node for every `PARTAB` / `PARTAB_ARRAY` row.
///
/// No C counterpart BY CONSTRUCTION. In C the magic rows only ENTER
/// `paramtab` when `zsh/parameter` boots (`handlefeatures` →
/// `addparamdef` → `createspecialhash`, `Src/module.c:1065`), and before
/// that the name still resolves — to the `PM_AUTOLOAD` stub
/// `init_bltinmods` planted (`Src/module.c:1218-1223`). Either way C's
/// `paramtab->getnode(name)` answers, so C never has to distinguish
/// "not seeded yet" from "unset". zshrs seeds the rows from
/// `ShellExecutor::new` (vm_helper.rs:2566) and matches `PARTAB` BY NAME
/// out of a separate static table, so a magic read that runs BEFORE that
/// seeding would see an absent node. `magic_special_shadowed` reads
/// absence as "unset" (C: `getnode` → NULL → `fetchvalue` NULL,
/// `Src/params.c:2264-2266`), which is only a valid inference once the
/// seeding has run; this flag is that precondition.
static PARTAB_SEEDED: std::sync::atomic::AtomicBool = std::sync::atomic::AtomicBool::new(false);

/// Insert a single PARTAB / PARTAB_ARRAY entry into paramtab. Called
/// from `zmodload <module>` once the module's boot completes, so that
/// `${+sysparams}` (etc.) flip from 0 → 1 only after explicit load.
/// No direct C counterpart — the C path runs through the module's
/// `setup_/boot_` chain which adds the SPECIALPMDEF entry via the
/// general hashtable machinery. Bug #69 in docs/BUGS.md.
pub fn seed_partab_param(name: &str) {
    use crate::ported::modules::parameter::{PARTAB, PARTAB_ARRAY};
    use crate::ported::zsh_h::{hashnode, param, PM_HIDE, PM_HIDEVAL, PM_READONLY, PM_SPECIAL};
    let mut tab = match crate::ported::params::paramtab().write() {
        Ok(t) => t,
        Err(_) => return,
    };
    // c:Src/module.c:1026-1052 `checkaddparam` — the node already present may
    // be the PM_AUTOLOAD STUB that `add_autoparam` planted (c:1218-1223,
    // ported at src/ported/module.rs), not a seeded special: forcing
    // MODULESTAB registers `p:builtins` and friends as autoload scalars. C
    // does NOT treat that as "already added" — `unsetparam_pm(pm, 0, 1)`
    // UNLINKS the stub (c:1052) and only then does `createparam` install the
    // real special (c:1065). The bulk path here already models that
    // (`tab.remove(entry.name); // c:1052 unsetparam_pm`); the single-name
    // sibling omitted it, so `builtins` stayed PM_SCALAR and `gethkparam`'s
    // PM_TYPE == PM_HASHED test fell through to None.
    //
    // A genuine user parameter shadowing the name carries no PM_AUTOLOAD, so
    // it still short-circuits exactly as before.
    if tab
        .get(name)
        .is_some_and(|pm| (pm.node.flags as u32 & crate::ported::zsh_h::PM_AUTOLOAD) == 0)
    {
        return; // a real special is already seeded
    }
    let flags = PARTAB
        .iter()
        .find(|e| e.name == name)
        .map(|e| e.flags)
        .or_else(|| {
            PARTAB_ARRAY
                .iter()
                .find(|e| e.name == name)
                .map(|e| e.flags)
        });
    let Some(flags) = flags else {
        return;
    };
    // c:1052 `unsetparam_pm(pm, 0, 1)` — unlink the autoload stub, but only
    // once we know a real special is going in to replace it. Doing it before
    // the PARTAB lookup above would destroy an existing node for any name
    // that is NOT a known special and then return, which is strictly worse
    // than the early-return it replaced.
    tab.remove(name);
    let pm = Box::new(param {
        node: hashnode {
            next: None,
            nam: name.to_string(),
            // Keep C's PM_READONLY. `init_partab_params` strips it from
            // rows the RUNTIME writes internally (funcstack pushes and
            // friends) and keeps it on the getfn/scanfn-computed rows —
            // see its `user_protected` list. Every name reaching THIS
            // seeder is a zmodload-gated row
            // (`module_gated_params_for`), and all of them are the
            // computed kind: `SPECIALPMDEF("sysparams", PM_READONLY,
            // NULL, getpmsysparams, scanpmsysparams)`
            // (Src/Modules/system.c:906), `errnos` (c:904), `langinfo`
            // (Src/Modules/langinfo.c:455); `mapfile` carries flags 0 in
            // C so it is unaffected either way. Stripping the bit made
            // `${(t)sysparams}` read `association-hide-hideval-special`
            // against zsh's `association-readonly-hide-hideval-special`,
            // and let `unset sysparams` succeed where zsh rejects with
            // `read-only variable: sysparams`.
            flags: flags | PM_SPECIAL as i32 | PM_HIDE as i32 | PM_HIDEVAL as i32,
        },
        u_data: 0,
        u_tied: None,
        u_arr: None,
        u_str: None,
        u_val: 0,
        u_dval: 0.0,
        u_hash: None,
        gsu_s: None,
        gsu_i: None,
        gsu_f: None,
        gsu_a: None,
        gsu_h: None,
        base: 0,
        width: 0,
        env: None,
        ename: None,
        old: None,
        level: 0,
    });
    tab.insert(name.to_string(), pm);
}

/// Default autoloadable parameters: name → owning module. Port of the
/// `autofeatures` `p:` rows in Src/Modules/parameter.mdd, watch.mdd,
/// termcap.mdd, terminfo.mdd, Src/Zle/zleparameter.mdd and
/// Src/Builtins/sched.mdd, registered at startup through
/// `setautofeatures` → `add_autoparam` (Src/module.c:1198-1229): each
/// name becomes a scalar paramtab stub whose VALUE is the module name,
/// flagged PM_AUTOLOAD (module.c:1218-1219). Matches `zmodload -ap`
/// output of the reference zsh build.
pub const AUTOLOAD_PARAMS: &[(&str, &str)] = &[
    // Src/Modules/watch.mdd:5 autofeatures
    ("WATCH", "zsh/watch"),
    ("watch", "zsh/watch"),
    // Src/Modules/parameter.mdd:5 autofeatures
    ("aliases", "zsh/parameter"),
    ("builtins", "zsh/parameter"),
    ("commands", "zsh/parameter"),
    ("dirstack", "zsh/parameter"),
    ("dis_aliases", "zsh/parameter"),
    ("dis_builtins", "zsh/parameter"),
    ("dis_functions", "zsh/parameter"),
    ("dis_functions_source", "zsh/parameter"),
    ("dis_galiases", "zsh/parameter"),
    ("dis_patchars", "zsh/parameter"),
    ("dis_reswords", "zsh/parameter"),
    ("dis_saliases", "zsh/parameter"),
    ("funcfiletrace", "zsh/parameter"),
    ("funcsourcetrace", "zsh/parameter"),
    ("funcstack", "zsh/parameter"),
    ("functions", "zsh/parameter"),
    ("functions_source", "zsh/parameter"),
    ("functrace", "zsh/parameter"),
    ("galiases", "zsh/parameter"),
    ("history", "zsh/parameter"),
    ("historywords", "zsh/parameter"),
    ("jobdirs", "zsh/parameter"),
    ("jobstates", "zsh/parameter"),
    ("jobtexts", "zsh/parameter"),
    ("modules", "zsh/parameter"),
    ("nameddirs", "zsh/parameter"),
    ("options", "zsh/parameter"),
    ("parameters", "zsh/parameter"),
    ("patchars", "zsh/parameter"),
    ("reswords", "zsh/parameter"),
    ("saliases", "zsh/parameter"),
    ("userdirs", "zsh/parameter"),
    ("usergroups", "zsh/parameter"),
    // Src/Zle/zleparameter.mdd:5 autofeatures
    ("keymaps", "zsh/zleparameter"),
    ("widgets", "zsh/zleparameter"),
    // Src/Modules/termcap.mdd:5 / terminfo.mdd:5 autofeatures
    ("termcap", "zsh/termcap"),
    ("terminfo", "zsh/terminfo"),
    // Src/Builtins/sched.mdd:5 autofeatures
    ("zsh_scheduled_events", "zsh/sched"),
];

/// Autoload stubs whose owning module is NOT loaded — the rows zsh's
/// `typeset` listings print as `undefined NAME` (printparamnode's
/// PM_AUTOLOAD pmtypes row, Src/params.c:6011 + the PM_AUTOLOAD
/// NAMEONLY arm at Src/params.c:6146-6155). Once a module loads, its
/// stubs drop out and the real params list instead.
pub fn autoload_param_stubs() -> Vec<(&'static str, &'static str)> {
    use crate::ported::zsh_h::{MOD_INIT_B, MOD_UNLOAD};
    let tab = crate::ported::module::MODULESTAB.lock().unwrap();
    AUTOLOAD_PARAMS
        .iter()
        .copied()
        .filter(|(_, m)| {
            // "Boot ran" is MOD_INIT_B && !MOD_UNLOAD (the criterion
            // printmodulenode uses, src/ported/module.rs:246 — C's
            // `m->u.handle` union check at Src/module.c:218-241).
            // modulestab::is_loaded checks MOD_LINKED which
            // register_builtin_modules pre-seeds for EVERY compiled-in
            // module, so it would report zsh/parameter "loaded" in a
            // fresh `zsh -f` where real zsh still shows the stubs.
            !tab.modules.get(*m).is_some_and(|md| {
                (md.node.flags & MOD_INIT_B) != 0 && (md.node.flags & MOD_UNLOAD) == 0
            })
        })
        .collect()
}

/// Names provided by `zsh/system` / `zsh/mapfile` etc. that are
/// gated on explicit `zmodload`. Used by the bin_zmodload path to
/// re-seed paramtab after the module's boot completes.
pub fn module_gated_params_for(module: &str) -> &'static [&'static str] {
    match module {
        "zsh/system" => &["sysparams", "errnos"],
        "zsh/mapfile" => &["mapfile"],
        "zsh/langinfo" => &["langinfo"],
        "zsh/hlgroup" => &[".zle.esc", ".zle.sgr"],
        "zsh/ksh93" => &[".sh.match"],
        _ => &[],
    }
}
impl ShellExecutor {
    /// `enter_posix_mode` — see implementation.
    pub fn enter_posix_mode(&mut self) {
        self.posix_mode = true;
        self.plugin_cache = None;
        self.compsys_cache = std::cell::OnceCell::new();
        self.compinit_pending = None;
        self.worker_pool = std::sync::Arc::new(crate::worker::WorkerPool::new(1));
        // Direct call to the canonical `emulate()` port
        // (Src/options.c:533) — `-R` semantics = fully=true.
        // bin_emulate goes through dispatch_builtin which needs an
        // ExecutorContext that isn't set up yet at apply_cli_flags
        // time; the underlying emulate() doesn't need one.
        crate::ported::options::emulate("sh", true);
    }
    /// `enter_ksh_mode` — see implementation.
    pub fn enter_ksh_mode(&mut self) {
        self.plugin_cache = None;
        self.compsys_cache = std::cell::OnceCell::new();
        self.compinit_pending = None;
        self.worker_pool = std::sync::Arc::new(crate::worker::WorkerPool::new(1));
        crate::ported::options::emulate("ksh", true);
    }
    /// `enter_dash_mode` — strict-dash (Debian Almquist Shell) runtime.
    /// Same executor setup as [`enter_posix_mode`] (dash IS `sh` for every
    /// option), but calls `emulate("dash")` so the Rust-only DASH_STRICT
    /// flag is raised (and NOT cleared, as `emulate("sh")` would). See
    /// `src/extensions/dash_mode.rs`.
    pub fn enter_dash_mode(&mut self) {
        self.posix_mode = true;
        self.plugin_cache = None;
        self.compsys_cache = std::cell::OnceCell::new();
        self.compinit_pending = None;
        self.worker_pool = std::sync::Arc::new(crate::worker::WorkerPool::new(1));
        crate::ported::options::emulate("dash", true);
    }
}

/// Thin (text, pattern) → bool wrapper over the canonical
/// `patcompile()` + `pattry()` pair from `Src/pattern.c`. Argument
/// order is flipped so callers read naturally. Lives in vm_helper.rs
/// (non-port file) as the public convenience entry for extensions
/// and the VM bridge; `src/ported/*` files inline the compile+match
/// idiom directly to preserve PORT.md Rule 1 faithfulness.
pub fn glob_match_static(s: &str, pattern: &str) -> bool {
    let Some(prog) = patcompile(
        &{
            let mut __pat_tok = (pattern).to_string();
            crate::ported::glob::tokenize(&mut __pat_tok);
            __pat_tok
        },
        PAT_HEAPDUP as i32,
        None,
    ) else {
        return false;
    };
    // c:Src/pattern.c:2570-2621 — `else if (prog->patnpar && !(patflags &
    // PAT_FILE))`: when the caller passes NO nump/begp/endp, `pattryrefs`
    // ITSELF publishes $match / $mbegin / $mend. That arm is ported in
    // pattern.rs, so this layer must not re-derive them from begp/endp.
    //
    // Re-deriving required compensating for the EXCLUSIVE end index
    // `pattryrefs` used to return, and the compensation was wrong twice over:
    //   * it would double-correct the c:2562-2564 `- 1` now applied there, and
    //     collide with the `endp[i] < 0` unset-group sentinel — an empty
    //     capture at offset 0 reports (0, -1) and was misread as an UNMATCHED
    //     alternation branch;
    //   * `saturating_sub(1)` clamped at 0, so under KSHARRAYS an empty capture
    //     at offset 0 gave `mend=0` where C computes `0 + 0 + 0 - 1` = -1.
    //     Measured: `setopt ksharrays; [[ abc = (#b)(x#)abc ]]` → zsh mend=-1,
    //     zshrs mend=0, while the substitution path (which already uses the
    //     c:2570-2621 arm) printed -1 correctly.
    let matched = pattry(&prog, s);
    // $MATCH / $MBEGIN / $MEND are set by the MATCHER (pattern.rs, c:2526),
    // which is where C decides it — gated on the GLOBAL patglobflags so a later
    // `(#M)` can turn GF_MATCHREF back off (c:1099-1100).
    //
    // This layer used to re-do it with `pattern.contains("(#m)")`, which can
    // only ever answer "on": it re-set $MATCH after the matcher had correctly
    // declined to, so `(#m)(#M)a*` reported a match string where zsh leaves it
    // unset. Wrong mechanism (a substring test cannot see which flag came last)
    // and wrong layer (the matcher already has the compiled flags).
    matched
}

pub use crate::ported::lex::untokenize_ztokens;

pub use crate::ported::utils::unmetafy_str;

pub use crate::ported::utils::zsh_errno_msg;

// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
// PM_NAMEREF bridge helpers (typeset -n / named references).
//
// Rust-only adapters around the canonical C nameref machinery in
// Src/params.c (resolve_nameref_rec c:6332, setscope c:6382,
// upscope c:6455) and Src/builtin.c (bin_typeset nameref arm
// c:3117-3150). zshrs's paramtab is a name-keyed HashMap handing
// out clones, so the chain walk operates by NAME against the live
// table instead of by Param pointer — same hop rule, same loop
// detection, same upscope old-chain walk. The ported fns in
// params.rs/builtin.rs call into these at the exact C deref points
// (getparamnode c:570-575, getvalue/fetchvalue c:2247-2270,
// assignsparam c:3252/3258, assignaparam c:3392-3398, bin_unset
// c:3939-3951, typeset_single c:2032-2050).
// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

pub use crate::ported::params::*;

/// True for an `fpath` entry that is a host zsh **distribution's own**
/// function tree — the copy of `Completion/**` + `Functions/**` that
/// `make install` flattens into the zsh package.
///
/// c:Src/init.c:1132-1143 — zsh's `setupvals` seeds `fpath` with
/// `FIXED_FPATH_DIR`, `SITEFPATH_DIR`, then
/// `<prefix>/share/zsh/<version>/functions`. zshrs keeps the first two and
/// drops the last, from the compiled-in default and from an inherited
/// `FPATH` alike. This is startup construction only: like zsh, a later
/// shell-level `fpath=( … )` stores exactly what was assigned.
///
/// The distribution tree goes because zshrs ships its own: `vendor/zsh` is
/// packed into the binary by `build.rs` and materialised into
/// `~/.zshrs/functions`, which takes the host tree's index on `fpath`. A host tree is not a
/// fallback for that — it is a second, differently-versioned copy of the
/// same `compinit`, `_git` and `_describe`, and letting it linger means a
/// Homebrew zsh upgrade can change how zshrs completes.
///
/// `share/zsh/site-functions` STAYS. Nothing in it comes from zsh: it is
/// where third-party formulae install their completions (`_brew`,
/// `_docker`, `_kubectl`, `_gh` …), the bundle has no copy of them, and
/// dropping the directory would silently disable completion for every
/// tool installed through a package manager.
///
/// The two shapes to reject differ in depth — Homebrew's Cellar layout has
/// no version component under `share/zsh` — so the test is a `share`
/// component followed by `zsh`, plus a final component of exactly
/// `functions`:
///     /usr/share/zsh/5.9/functions                          drop
///     /opt/homebrew/Cellar/zsh/5.9.2/share/zsh/functions    drop
///     /opt/homebrew/share/zsh/site-functions                keep
///     ~/.zinit/plugins/…/src                                keep
pub(crate) fn is_host_zsh_function_tree(p: &Path) -> bool {
    if p.file_name() != Some(OsStr::new("functions")) {
        return false;
    }
    let mut comps = p.components().map(|c| c.as_os_str());
    while let Some(c) = comps.next() {
        if c == "share" && comps.clone().next() == Some(OsStr::new("zsh")) {
            return true;
        }
    }
    false
}

/// Default `fpath` when `FPATH` is absent from the environment.
///
/// c:Src/init.c:1143 — `SITEFPATH_DIR`, listed by zsh even when it does
/// not exist on disk. zshrs adds the same directory under whichever
/// prefixes are actually present, because that is where package managers
/// put third-party completions and the bundled tree has none of them.
///
/// The versioned `<prefix>/share/zsh/<version>/functions` that C also
/// seeds here is deliberately NOT included — see
/// [`is_host_zsh_function_tree`]. `~/.zshrs/functions` supplies it, and is
/// appended by both constructors.
///
/// The prefix list is the set of places a package manager puts
/// `share/zsh/site-functions` on the platforms zshrs targets. `/usr/local`
/// and `/usr` cover Linux distributions and a from-source install;
/// `/opt/homebrew` is Homebrew on Apple silicon, `/usr/local` doubles as
/// Homebrew on Intel macOS, and `/home/linuxbrew/.linuxbrew` is
/// Homebrew's Linux prefix — which is NOT `/opt/homebrew`, so a Linux box
/// with brew-installed completions found none of them before it was
/// listed. Only directories that exist are added, so naming a prefix
/// costs nothing on a machine that lacks it.
fn default_fpath() -> Vec<PathBuf> {
    let mut out: Vec<PathBuf> = vec![PathBuf::from("/usr/local/share/zsh/site-functions")];
    for pfx in [
        "/usr/local",
        "/opt/homebrew",
        "/home/linuxbrew/.linuxbrew",
        "/usr",
    ] {
        let site = PathBuf::from(format!("{pfx}/share/zsh/site-functions"));
        if site.is_dir() && !out.contains(&site) {
            out.push(site);
        }
    }
    out
}