kaish_kernel/

kernel.rs

//! The Kernel (核) — the heart of kaish.
//!
//! The Kernel owns and coordinates all core components:
//! - Interpreter state (scope, $?)
//! - Tool registry (builtins, user tools)
//! - VFS router (mount points)
//! - Job manager (background jobs)
//!
//! # Architecture
//!
//! ```text
//! ┌────────────────────────────────────────────────────────────┐
//! │                         Kernel (核)                         │
//! │  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐  │
//! │  │   Scope      │  │ ToolRegistry │  │  VfsRouter       │  │
//! │  │  (variables) │  │  (builtins,  │  │  (mount points)  │  │
//! │  │              │  │   user tools)│  │                  │  │
//! │  └──────────────┘  └──────────────┘  └──────────────────┘  │
//! │  ┌──────────────────────────────┐  ┌──────────────────┐    │
//! │  │  JobManager (background)     │  │  ExecResult ($?) │    │
//! │  └──────────────────────────────┘  └──────────────────┘    │
//! └────────────────────────────────────────────────────────────┘
//! ```

use std::collections::HashMap;
use std::path::PathBuf;
use std::sync::Arc;
use std::sync::atomic::{AtomicU64, AtomicUsize, Ordering};
use std::time::Duration;

use anyhow::{Context, Result};
use tokio::sync::RwLock;

/// Monotonic counter assigned to each Kernel at construction time, exposed
/// via `$$` / `${$}`. Starts at 1; each new Kernel gets the next value.
/// `Kernel::fork()` inherits the parent's value (matching bash's "subshell
/// keeps parent's $$" semantics) because forks clone the parent's Scope
/// rather than calling `set_pid` again.
///
/// Deliberately *not* the OS PID — kaish runs as a long-lived MCP server
/// or embedded inside other binaries (kaijutsu), where the host PID is
/// meaningless to the script. See
/// `~/.claude/projects/-home-atobey-src-kaish/memory/lang_dollar_dollar_identifier.md`
/// for the design rationale.
static KERNEL_COUNTER: AtomicU64 = AtomicU64::new(1);

/// Maximum depth of dynamic statement-engine re-entry — command substitution
/// (`$(…)`), shell-function calls, and `.kai` script sourcing — before a
/// **loud** error is returned instead of letting the native call stack
/// overflow (a `SIGSEGV`/abort with no diagnostic). Mirrors the intent of the
/// alias re-entry cap (10) and the lexer's `MAX_PAREN_DEPTH` (256): a runaway
/// or mutually recursive script hits a catchable ceiling, not a signal.
///
/// Each level stacks the dispatch chain between re-entries. After the GH #48
/// allocation pass this measures ~50 KB (release) / ~57 KB (debug at the default
/// `opt-level = 1` dev profile — see the root `Cargo.toml`) / ~193 KB (a fully
/// unoptimized debug build) of native stack per level, down from ~80 / ~380 KB
/// before; the `recursion_stack_cost_tests` probe reports the live figure.
///
/// This cap and [`RECOMMENDED_STACK_SIZE`] are a **matched pair**: the cap must
/// trip *before* `cap × (worst-case per-level stack)` can exceed the floor, so a
/// runaway is caught, not a `SIGSEGV`. The worst case is the ~193 KB unoptimized
/// figure — the `opt-level = 1` dev profile above is local to this workspace and
/// does **not** propagate to embedders, whose own debug builds of the kernel pay
/// the full unoptimized cost. `48 × 193 KB ≈ 9.3 MB` under the 12 MiB floor
/// keeps the same ~1.3× margin the pre-#48 pair had (`32 × 380 KB ≈ 12 MB` under
/// 16 MiB); #48's smaller frames are what let the cap rise 32→48 and the floor
/// drop 16→12 MiB together. **The guard only fires *before* the stack overflows
/// on a thread that meets that floor** — this is why the REPL sizes its threads
/// to it and embedders must too (see `docs/EMBEDDING.md`). Forks (background
/// jobs, scatter workers, pipeline stages) run on fresh stacks and get a fresh
/// counter, bounding each chain independently. GH #46 / #47 / #48.
pub const MAX_RECURSION_DEPTH: usize = 48;

/// Recommended native stack size (12 MiB) for any thread that drives kaish
/// execution — the REPL sizes its `block_on` thread and tokio worker threads
/// to this, and embedders that call `Kernel::execute` (directly or via a tokio
/// runtime) should do the same (`runtime::Builder::thread_stack_size`, and a
/// `std::thread` stack for a non-worker driver).
///
/// The kernel recurses on the native stack (command substitution, shell
/// functions, `.kai` scripts). [`MAX_RECURSION_DEPTH`] converts a runaway into
/// a loud error, but only *if the stack is at least this large* — on the
/// default ~2 MB tokio worker stack the recursion overflows (SIGSEGV) before
/// reaching the cap. This floor is the companion to that cap (see its docs for
/// the `cap × per-level < floor` relationship): 12 MiB holds the depth-48 cap
/// with margin even for an unoptimized embedder build (~193 KB/level), and #48
/// shrank the per-level cost enough to drop it from 16 MiB. kaish can't set this
/// itself (it doesn't own the runtime), so it exposes the floor for owners to
/// apply. See GH #47 / #48.
pub const RECOMMENDED_STACK_SIZE: usize = 12 * 1024 * 1024;

use async_trait::async_trait;

use crate::ast::{
    spread_non_list_message, Arg, BinaryOp, Command, Expr, FileTestOp, ListElem, RecordKey, Stmt,
    StringPart, TestExpr, ToolDef, Value,
};
pub use kaish_types::{CommandKind, ExecuteOptions};
use crate::backend::{BackendError, KernelBackend};
use kaish_glob::glob_match;
use crate::dispatch::{CommandDispatcher, PipelinePosition};
use crate::error::{classify_execute_error, KernelError};
use crate::interpreter::{apply_output_format, eval_expr, expand_tilde, json_to_value_no_envelope, value_to_bool, value_to_string, value_to_text_sink, ControlFlow, ExecResult, PathError, Scope};
use crate::parser::parse;
use crate::scheduler::{is_bool_type, schema_param_lookup, select_leaf, stderr_stream, JobManager, PipelineRunner, StderrReceiver};
use crate::tools::{
    external_commands_unavailable_error, global_flag_value_is_truthy, register_builtins,
    ExecContext, ExternalCommandOutcome, ExternalCommandsUnavailable, GlobalFlags, ToolArgs,
    ToolRegistry,
};
#[cfg(feature = "subprocess")]
use crate::tools::{resolve_in_path, virtual_cwd_error};
use crate::validator::{Severity, Validator};
#[cfg(feature = "localfs")]
use crate::vfs::LocalFs;
use crate::vfs::{BuiltinFs, DevFs, JobFs, MemoryFs, VfsRouter};
use kaish_vfs::ByteBudget;
#[cfg(all(feature = "localfs", feature = "overlay"))]
use kaish_vfs::OverlayFs;

/// VFS mount mode determines how the local filesystem is exposed.
///
/// Different modes trade off convenience vs. security:
/// - `Passthrough` gives native path access (best for human REPL use)
/// - `Sandboxed` restricts access to a subtree (safer for agents)
/// - `NoLocal` provides complete isolation (tests, pure memory mode)
#[derive(Debug, Clone)]
#[non_exhaustive]
pub enum VfsMountMode {
    /// LocalFs at "/" — native paths work directly.
    ///
    /// Full filesystem access. Use for human-operated REPL sessions where
    /// native paths like `/home/user/project` should just work.
    ///
    /// Mounts:
    /// - `/` → LocalFs("/")
    /// - `/v` → MemoryFs (blob storage)
    #[cfg(feature = "localfs")]
    Passthrough,

    /// Transparent sandbox — paths look native but access is restricted.
    ///
    /// The local filesystem is mounted at its real path (e.g., `/home/user`),
    /// so `/home/user/src/project` just works. But paths outside the sandbox
    /// root are not accessible.
    ///
    /// **Note:** This only restricts VFS (builtin) operations. External commands
    /// bypass the sandbox entirely — see [`KernelConfig::allow_external_commands`].
    ///
    /// Mounts:
    /// - `/` → MemoryFs (catches paths outside sandbox)
    /// - `{root}` → LocalFs(root)  (e.g., `/home/user` → LocalFs)
    /// - `/tmp` → LocalFs("/tmp")
    /// - `/dev` → DevFs (synthetic /dev/null, /dev/zero)
    /// - `/v` → MemoryFs (blob storage)
    #[cfg(feature = "localfs")]
    Sandboxed {
        /// Root path for local filesystem. Defaults to `$HOME`.
        /// Can be restricted further, e.g., `~/src`.
        root: Option<PathBuf>,
    },

    /// No local filesystem. Memory only.
    ///
    /// Complete isolation — no access to the host filesystem.
    /// Useful for tests or pure sandboxed execution.
    ///
    /// Output spill is forced to [`SpillMode::Memory`](crate::output_limit::SpillMode::Memory)
    /// for this mode at kernel construction: with no host filesystem mounted,
    /// large output must not write a host spill file (`paths::spill_dir()`
    /// bypasses the VFS). This overrides any explicit `SpillMode::Disk`.
    ///
    /// Mounts:
    /// - `/` → MemoryFs
    /// - `/tmp` → MemoryFs
    /// - `/v` → MemoryFs
    /// - `/dev` → DevFs (synthetic /dev/null, /dev/zero)
    NoLocal,
}

#[allow(clippy::derivable_impls)] // native has multiple variants; not derivable cross-feature
impl Default for VfsMountMode {
    fn default() -> Self {
        #[cfg(feature = "localfs")]
        { VfsMountMode::Sandboxed { root: None } }
        #[cfg(not(feature = "localfs"))]
        { VfsMountMode::NoLocal }
    }
}

/// Configuration for kernel initialization.
#[derive(Clone)]
pub struct KernelConfig {
    /// Name of this kernel (for identification).
    pub name: String,

    /// VFS mount mode — controls how local filesystem is exposed.
    pub vfs_mode: VfsMountMode,

    /// Initial working directory (VFS path).
    pub cwd: PathBuf,

    /// Whether to skip pre-execution validation.
    ///
    /// When false (default), scripts are validated before execution to catch
    /// errors early. Set to true to skip validation for performance or to
    /// allow dynamic/external commands.
    pub skip_validation: bool,

    /// When true, standalone external commands inherit stdio for real-time output.
    ///
    /// Set by script runner and REPL for human-visible output.
    /// Not set by MCP server (output must be captured for structured responses).
    pub interactive: bool,

    /// Ignore file configuration for file-walking tools.
    pub ignore_config: crate::ignore_config::IgnoreConfig,

    /// Output size limit configuration for agent safety.
    pub output_limit: crate::output_limit::OutputLimitConfig,

    /// Whether external command execution (PATH lookup, `exec`, `spawn`) is allowed.
    ///
    /// When `true` (default), commands not found as builtins are resolved via PATH
    /// and executed as child processes. When `false`, only kaish builtins and
    /// backend-registered tools are available.
    ///
    /// **Security:** External commands bypass the VFS sandbox entirely — they see
    /// the real filesystem, network, and environment. Set to `false` when running
    /// untrusted input.
    pub allow_external_commands: bool,


    /// Enable trash-on-delete for rm (set -o trash).
    ///
    /// When enabled, small files are moved to freedesktop.org Trash instead of
    /// being permanently deleted. Can also be enabled at runtime with `set -o trash`
    /// or via `KAISH_TRASH=1`.
    pub trash_enabled: bool,

    /// Enable errexit (`set -e`) at kernel construction (set -o errexit default).
    ///
    /// When enabled, a script aborts at the first statement that exits
    /// nonzero instead of continuing to the next one. **Off by default** —
    /// standard shell behavior, so an embedder upgrading kaish sees no
    /// change. There is one piece of state behind this
    /// (`Scope::error_exit_enabled`), seeded from this field and mutated at
    /// runtime by `set -e`/`set +e`: this only picks the *starting* value,
    /// a script's own `set -e`/`set +e` still applies afterward regardless
    /// of what this was, and `set -o` always reports the true, single
    /// answer no matter which one set it. `ExecuteOptions::errexit`
    /// overrides this for one call.
    pub errexit_enabled: bool,

    /// Variables to populate the root scope with at construction, all marked
    /// for export to child processes.
    ///
    /// The kernel itself is hermetic — it never reads `std::env::vars()` —
    /// so frontends that want OS-env passthrough (REPL, MCP) populate this
    /// from `std::env::vars()`. Embedders that want isolation pass nothing
    /// (or only the keys they curate).
    pub initial_vars: HashMap<String, Value>,

    /// Default per-request timeout. When `Some`, every `execute_with_options`
    /// call without an explicit `ExecuteOptions::timeout` uses this duration.
    /// When elapsed, the kernel cancels the request, kills any external
    /// children with the configured grace, and returns exit code 124.
    ///
    /// `None` means no default timeout — only explicit per-call timeouts apply.
    pub request_timeout: Option<Duration>,

    /// Grace period between SIGTERM and SIGKILL when killing an external
    /// child on cancellation or timeout.
    ///
    /// Defaults to 2 seconds. Set to `Duration::ZERO` to escalate immediately
    /// to SIGKILL. Long-shutdown processes (databases, etc.) may need more.
    pub kill_grace: Duration,

    /// Cap on memory-resident bytes across all kernel-owned `MemoryFs` mounts.
    ///
    /// One shared `ByteBudget` (labeled `"vfs-memory"`) is created at kernel
    /// construction and handed to every `MemoryFs` the kernel builds in
    /// `setup_vfs` (Passthrough `/v`; Sandboxed `/` and `/v`; NoLocal `/`,
    /// `/tmp`, `/v`). Writes that would exceed the cap fail loudly with
    /// `StorageFull` — an in-band error a model reads and adapts to; fail
    /// loud over quietly eating RAM.
    ///
    /// **Why the agent preset is bounded by default:** an agent embedder
    /// typically creates a fresh kernel per `execute()` call, so the 64 MiB cap
    /// is per-call, not per-session. Embedders that know their workload needs
    /// more opt out with `without_vfs_budget()` or raise the cap with
    /// `with_vfs_budget(bytes)` — protection on by default, opt out knowingly.
    /// All other profiles default to `None` (unbounded).
    ///
    /// Follows the same pattern as `OutputLimitConfig`: agent preset bounded, rest unbounded.
    pub vfs_budget_bytes: Option<u64>,

    /// Enable copy-on-write overlay mode (opt-in).
    ///
    /// When `true`, the primary local filesystem mount is wrapped in an
    /// `OverlayFs` so writes are virtual — the lower layer is never touched.
    /// Use `kaish-vfs status/diff/commit/reset` to inspect and manage the
    /// overlay transaction.
    ///
    /// **Passthrough:** `/` becomes `OverlayFs over LocalFs::read_only("/")`.
    /// **Sandboxed{root}:** the `{root}` mount becomes
    /// `OverlayFs over LocalFs::read_only(root)`; the `/tmp` and XDG runtime
    /// mounts stay as real `LocalFs` (real writes escape the transaction —
    /// see `docs/kaish-overlayfs.md` for the escape-hatch inventory).
    /// **NoLocal:** incompatible — construction fails loudly (everything is
    /// already virtual; an overlay adds no value and no lower layer to wrap).
    /// **with_backend:** incompatible — the embedder controls the VFS; the
    /// kernel cannot wrap it without bypassing the embedder's semantics.
    ///
    /// **Not default-on for the agent preset:** each `execute()` call gets a fresh kernel,
    /// making the overlay a per-call transaction — `kaish-vfs commit` must run
    /// in the same call as the writes, or the transaction is discarded on drop.
    /// Frontends (REPL, MCP) expose `--overlay` as an explicit opt-in flag.
    pub overlay: bool,

    /// The [`JobManager`] this kernel adopts. `None` — the default — builds a
    /// fresh one, so every kernel owns its own job table.
    ///
    /// Supply one to share a single job table across kernels. An embedder that
    /// builds a kernel per request (kaijutsu builds one per tool call) has no
    /// other way to keep a `cmd &` job reachable: ids, status, and output
    /// streams all live on the manager, so a per-kernel manager takes them
    /// down with the kernel that made it. One manager held by the embedder and
    /// handed to every kernel keeps `&` usable across calls, and keeps job ids
    /// unique because they are minted from the manager's own counter.
    ///
    /// **A shared manager carries shared settings.** `kill_grace` and
    /// `persist_output_files` are stamped onto the manager at kernel
    /// construction, so the last kernel built wins for both: a hermetic kernel
    /// (`NoLocal`, or any `with_backend` kernel) turns `persist_output_files`
    /// off for every kernel on that manager, and each kernel's
    /// [`Self::kill_grace`] overwrites the previous one's. Share a manager
    /// between kernels configured alike, or accept the last writer.
    ///
    /// Set through [`Self::with_job_manager`].
    pub job_manager: Option<Arc<JobManager>>,

    /// Arm `PR_SET_PDEATHSIG(SIGKILL)` on every external command this kernel
    /// spawns, so the OS kills the child the instant this process dies —
    /// **for any reason, including `kill -9`, a segfault, or an OOM kill.**
    ///
    /// Off by default; on for [`Self::agent`] and [`Self::agent_with_root`],
    /// the same "protection on by default for the agent preset, opt in
    /// elsewhere" split [`Self::vfs_budget_bytes`] uses.
    ///
    /// **Why not unconditional.** kaish already puts every child in its own
    /// process group and kills through a pidfd on cancel, and drops it with
    /// `kill_on_drop`. All three need this process to still be running code,
    /// so none of them survive a hard kill — that is the gap this closes. But
    /// closing it costs something a human at a REPL may not want: an armed
    /// child cannot outlive its shell, at all, and the child has no way to
    /// opt out from inside (unlike SIGHUP, which `nohup`/`disown` exist to
    /// escape). A REPL user who backgrounds a long download and exits expects
    /// it to keep going. An agent embedder expects the opposite — an
    /// invisible orphaned `cargo build` is the failure — so the presets
    /// differ rather than one behavior being forced on both.
    ///
    /// **Linux only.** macOS has no `PR_SET_PDEATHSIG` and no equivalent that
    /// works without a live parent (`kqueue`'s `NOTE_EXIT` needs a watcher
    /// process). This flag is accepted and has no effect there, rather than
    /// being faked with something weaker.
    ///
    /// Set through [`Self::with_kill_children_on_parent_death`].
    pub kill_children_on_parent_death: bool,
}

/// Get the default sandbox root ($HOME).
#[cfg(feature = "localfs")]
fn default_sandbox_root() -> PathBuf {
    std::env::var("HOME")
        .map(PathBuf::from)
        .unwrap_or_else(|_| PathBuf::from("/"))
}

impl Default for KernelConfig {
    fn default() -> Self {
        #[cfg(feature = "localfs")]
        {
            let home = default_sandbox_root();
            Self {
                name: "default".to_string(),
                vfs_mode: VfsMountMode::Sandboxed { root: None },
                cwd: home,
                skip_validation: false,
                interactive: false,
                ignore_config: crate::ignore_config::IgnoreConfig::none(),
                output_limit: crate::output_limit::OutputLimitConfig::none(),
                allow_external_commands: cfg!(feature = "subprocess"),
                trash_enabled: std::env::var("KAISH_TRASH").is_ok_and(|v| v == "1"),
                errexit_enabled: false,
                initial_vars: HashMap::new(),
                request_timeout: None,
                kill_grace: Duration::from_secs(2),
                vfs_budget_bytes: None,
                overlay: false,
                job_manager: None,
                kill_children_on_parent_death: false,
            }
        }
        #[cfg(not(feature = "localfs"))]
        {
            Self {
                name: "default".to_string(),
                vfs_mode: VfsMountMode::NoLocal,
                cwd: PathBuf::from("/"),
                skip_validation: false,
                interactive: false,
                ignore_config: crate::ignore_config::IgnoreConfig::none(),
                output_limit: crate::output_limit::OutputLimitConfig::none(),
                allow_external_commands: false,
                trash_enabled: false,
                errexit_enabled: false,
                initial_vars: HashMap::new(),
                request_timeout: None,
                kill_grace: Duration::from_secs(2),
                vfs_budget_bytes: None,
                overlay: false,
                job_manager: None,
                kill_children_on_parent_death: false,
            }
        }
    }
}

impl KernelConfig {
    /// Create a transient kernel config (sandboxed, for temporary use).
    #[cfg(feature = "localfs")]
    pub fn transient() -> Self {
        let home = default_sandbox_root();
        Self {
            name: "transient".to_string(),
            vfs_mode: VfsMountMode::Sandboxed { root: None },
            cwd: home,
            skip_validation: false,
            interactive: false,
            ignore_config: crate::ignore_config::IgnoreConfig::none(),
            output_limit: crate::output_limit::OutputLimitConfig::none(),
            allow_external_commands: cfg!(feature = "subprocess"),
            trash_enabled: false,
            errexit_enabled: false,
            initial_vars: HashMap::new(),
            request_timeout: None,
            kill_grace: Duration::from_secs(2),
            vfs_budget_bytes: None,
            overlay: false,
            job_manager: None,
            kill_children_on_parent_death: false,
        }
    }

    /// Create a transient kernel config (isolated, no-default-features).
    #[cfg(not(feature = "localfs"))]
    pub fn transient() -> Self {
        Self::isolated()
    }

    /// Create a kernel config with the given name (sandboxed by default).
    #[cfg(feature = "localfs")]
    pub fn named(name: &str) -> Self {
        let home = default_sandbox_root();
        Self {
            name: name.to_string(),
            vfs_mode: VfsMountMode::Sandboxed { root: None },
            cwd: home,
            skip_validation: false,
            interactive: false,
            ignore_config: crate::ignore_config::IgnoreConfig::none(),
            output_limit: crate::output_limit::OutputLimitConfig::none(),
            allow_external_commands: cfg!(feature = "subprocess"),
            trash_enabled: false,
            errexit_enabled: false,
            initial_vars: HashMap::new(),
            request_timeout: None,
            kill_grace: Duration::from_secs(2),
            vfs_budget_bytes: None,
            overlay: false,
            job_manager: None,
            kill_children_on_parent_death: false,
        }
    }

    /// Create a kernel config with the given name (isolated, no-default-features).
    #[cfg(not(feature = "localfs"))]
    pub fn named(name: &str) -> Self {
        Self {
            name: name.to_string(),
            ..Self::isolated()
        }
    }

    /// Create a REPL config with passthrough filesystem access.
    ///
    /// Native paths like `/home/user/project` work directly.
    /// The cwd is set to the actual current working directory.
    #[cfg(feature = "localfs")]
    pub fn repl() -> Self {
        let cwd = std::env::current_dir().unwrap_or_else(|_| PathBuf::from("/"));
        Self {
            name: "repl".to_string(),
            vfs_mode: VfsMountMode::Passthrough,
            cwd,
            skip_validation: false,
            interactive: false,
            // Ignore-aware by default (GH #134): .gitignore + default ignores
            // at Advisory scope — `--no-ignore` / `kaish-ignore clear` recover.
            ignore_config: crate::ignore_config::IgnoreConfig::interactive(),
            output_limit: crate::output_limit::OutputLimitConfig::none(),
            allow_external_commands: cfg!(feature = "subprocess"),
            trash_enabled: std::env::var("KAISH_TRASH").is_ok_and(|v| v == "1"),
            errexit_enabled: false,
            initial_vars: HashMap::new(),
            request_timeout: None,
            kill_grace: Duration::from_secs(2),
            vfs_budget_bytes: None,
            overlay: false,
            job_manager: None,
            kill_children_on_parent_death: false,
        }
    }

    /// Create a sandboxed-agent config with sandboxed filesystem access.
    ///
    /// The preset for embedding kaish as an untrusted agent's shell (e.g. an MCP
    /// server like kaibo/kaijutsu): sandboxed VFS, non-interactive, bounded
    /// memory and output. Local filesystem is accessible at its real path (e.g.,
    /// `/home/user`), but sandboxed to `$HOME`. Paths outside the sandbox are not
    /// accessible through builtins. External commands still access the real
    /// filesystem — use `.with_allow_external_commands(false)` to block them.
    ///
    /// VFS memory is bounded at 64 MiB per `execute()` call by default (an agent
    /// embedder typically creates a fresh kernel per call). Raise or remove with
    /// `with_vfs_budget` / `without_vfs_budget`.
    #[cfg(feature = "localfs")]
    pub fn agent() -> Self {
        let home = default_sandbox_root();
        Self {
            name: "agent".to_string(),
            vfs_mode: VfsMountMode::Sandboxed { root: None },
            cwd: home,
            skip_validation: false,
            interactive: false,
            ignore_config: crate::ignore_config::IgnoreConfig::agent(),
            output_limit: crate::output_limit::OutputLimitConfig::agent(),
            allow_external_commands: cfg!(feature = "subprocess"),
            trash_enabled: std::env::var("KAISH_TRASH").is_ok_and(|v| v == "1"),
            errexit_enabled: false,
            initial_vars: HashMap::new(),
            request_timeout: None,
            kill_grace: Duration::from_secs(2),
            vfs_budget_bytes: Some(64 * 1024 * 1024),
            overlay: false,
            job_manager: None,
            // An agent embedder must never leave an invisible `cargo build` running
            // after its process is hard-killed; see the field doc for why this is
            // not the default everywhere.
            kill_children_on_parent_death: true,
        }
    }

    /// Create a sandboxed-agent config with a custom sandbox root.
    ///
    /// Use this to restrict access to a subdirectory like `~/src`.
    ///
    /// VFS memory is bounded at 64 MiB per `execute()` call by default.
    /// Raise or remove with `with_vfs_budget` / `without_vfs_budget`.
    #[cfg(feature = "localfs")]
    pub fn agent_with_root(root: PathBuf) -> Self {
        Self {
            name: "agent".to_string(),
            vfs_mode: VfsMountMode::Sandboxed { root: Some(root.clone()) },
            cwd: root,
            skip_validation: false,
            interactive: false,
            ignore_config: crate::ignore_config::IgnoreConfig::agent(),
            output_limit: crate::output_limit::OutputLimitConfig::agent(),
            allow_external_commands: cfg!(feature = "subprocess"),
            trash_enabled: std::env::var("KAISH_TRASH").is_ok_and(|v| v == "1"),
            errexit_enabled: false,
            initial_vars: HashMap::new(),
            request_timeout: None,
            kill_grace: Duration::from_secs(2),
            vfs_budget_bytes: Some(64 * 1024 * 1024),
            overlay: false,
            job_manager: None,
            // Same reasoning as `agent()`.
            kill_children_on_parent_death: true,
        }
    }

    /// Create a config with no local filesystem (memory only).
    ///
    /// Complete isolation: no local filesystem and external commands are disabled.
    /// Useful for tests or pure sandboxed execution.
    pub fn isolated() -> Self {
        Self {
            name: "isolated".to_string(),
            vfs_mode: VfsMountMode::NoLocal,
            cwd: PathBuf::from("/"),
            skip_validation: false,
            interactive: false,
            ignore_config: crate::ignore_config::IgnoreConfig::none(),
            output_limit: crate::output_limit::OutputLimitConfig::none(),
            allow_external_commands: false,
            trash_enabled: false,
            errexit_enabled: false,
            initial_vars: HashMap::new(),
            request_timeout: None,
            kill_grace: Duration::from_secs(2),
            vfs_budget_bytes: None,
            overlay: false,
            job_manager: None,
            kill_children_on_parent_death: false,
        }
    }

    /// Set the VFS mount mode.
    pub fn with_vfs_mode(mut self, mode: VfsMountMode) -> Self {
        self.vfs_mode = mode;
        self
    }

    /// Set the initial working directory.
    pub fn with_cwd(mut self, cwd: PathBuf) -> Self {
        self.cwd = cwd;
        self
    }

    /// Skip pre-execution validation.
    pub fn with_skip_validation(mut self, skip: bool) -> Self {
        self.skip_validation = skip;
        self
    }

    /// Enable interactive mode (external commands inherit stdio).
    pub fn with_interactive(mut self, interactive: bool) -> Self {
        self.interactive = interactive;
        self
    }

    /// Set the ignore file configuration.
    pub fn with_ignore_config(mut self, config: crate::ignore_config::IgnoreConfig) -> Self {
        self.ignore_config = config;
        self
    }

    /// Set the output limit configuration.
    pub fn with_output_limit(mut self, config: crate::output_limit::OutputLimitConfig) -> Self {
        self.output_limit = config;
        self
    }

    /// Set whether external command execution is allowed.
    ///
    /// When `false`, commands not found as builtins report that external
    /// commands are disabled on this shell — distinct from "command not
    /// found", which stays reserved for a name that genuinely isn't
    /// resolvable — instead of searching PATH. Backend-registered tools
    /// (MCP, an embedder's own registry) are unaffected and still resolve.
    /// The `exec` and `spawn` builtins also refuse, with the same wording.
    /// Use this to prevent VFS sandbox bypass via external binaries.
    pub fn with_allow_external_commands(mut self, allow: bool) -> Self {
        self.allow_external_commands = allow;
        self
    }

    /// Enable or disable trash-on-delete at startup.
    pub fn with_trash(mut self, enabled: bool) -> Self {
        self.trash_enabled = enabled;
        self
    }

    /// Enable or disable errexit (`set -e`) at startup. See `errexit_enabled`
    /// for precedence against `ExecuteOptions::errexit` and runtime `set -e`.
    pub fn with_errexit(mut self, enabled: bool) -> Self {
        self.errexit_enabled = enabled;
        self
    }

    /// Add a single initial variable; marked exported when the kernel boots.
    ///
    /// Repeated calls add (last write wins on key collision).
    pub fn with_var(mut self, name: impl Into<String>, value: Value) -> Self {
        self.initial_vars.insert(name.into(), value);
        self
    }

    /// Replace the entire initial-vars map. All entries are marked exported.
    pub fn with_initial_vars(mut self, vars: HashMap<String, Value>) -> Self {
        self.initial_vars = vars;
        self
    }

    /// Extend the initial-vars map with the given entries (last write wins).
    pub fn with_vars(mut self, vars: HashMap<String, Value>) -> Self {
        self.initial_vars.extend(vars);
        self
    }

    /// Set the default per-request timeout (kernel-wide).
    ///
    /// Each `execute_with_options` call without an explicit timeout uses
    /// this. On elapsed, the kernel cancels and returns exit code 124.
    pub fn with_request_timeout(mut self, timeout: Duration) -> Self {
        self.request_timeout = Some(timeout);
        self
    }

    /// Set the SIGTERM-to-SIGKILL grace period for child kills.
    pub fn with_kill_grace(mut self, grace: Duration) -> Self {
        self.kill_grace = grace;
        self
    }

    /// Arm `PR_SET_PDEATHSIG(SIGKILL)` on external commands so a hard-killed
    /// kaish process cannot orphan them (Linux only — read
    /// [`Self::kill_children_on_parent_death`] for the tradeoff and the macOS
    /// gap).
    pub fn with_kill_children_on_parent_death(mut self, on: bool) -> Self {
        self.kill_children_on_parent_death = on;
        self
    }

    /// Adopt an embedder-owned [`JobManager`] instead of building a fresh one,
    /// so background jobs outlive the kernel that started them. Read
    /// [`Self::job_manager`] before sharing one manager between kernels that
    /// are configured differently.
    pub fn with_job_manager(mut self, jobs: Arc<JobManager>) -> Self {
        self.job_manager = Some(jobs);
        self
    }

    /// Cap VFS memory-resident bytes at `bytes` across all kernel-owned
    /// `MemoryFs` mounts. A shared `ByteBudget` labeled `"vfs-memory"` is
    /// created at kernel construction and passed to every `MemoryFs` the
    /// kernel builds (see `setup_vfs` and `with_backend`).
    ///
    /// Writes that would exceed the cap fail loudly with `StorageFull` — an
    /// in-band error a model reads and adapts to; fail loud over quietly eating
    /// RAM. Use `without_vfs_budget` to remove the cap entirely.
    pub fn with_vfs_budget(mut self, bytes: u64) -> Self {
        self.vfs_budget_bytes = Some(bytes);
        self
    }

    /// Remove the VFS memory budget — all `MemoryFs` mounts are unbounded.
    ///
    /// Use when the caller knows the workload and the default 64 MiB cap
    /// (set by `KernelConfig::agent`) is too conservative.
    pub fn without_vfs_budget(mut self) -> Self {
        self.vfs_budget_bytes = None;
        self
    }

    /// Enable or disable copy-on-write overlay mode.
    ///
    /// When `true`, the primary local filesystem mount is wrapped in an
    /// `OverlayFs` so writes are virtual — the lower layer is never touched.
    /// Incompatible with `VfsMountMode::NoLocal` (fails loudly at construction)
    /// and `with_backend` kernels (same — the embedder controls the VFS).
    pub fn with_overlay(mut self, overlay: bool) -> Self {
        self.overlay = overlay;
        self
    }

}


/// Handle to an active overlay session, kept on the kernel and shared to
/// `ExecContext` so the `kaish-vfs` builtin can reach the `OverlayFs`.
///
/// The `mount_path` is the VFS prefix the overlay was mounted under (e.g.
/// `/home/user`); `commit_root` is the real filesystem path the overlay's
/// lower is backed by (used as the target for `kaish-vfs commit`).
#[cfg(all(feature = "localfs", feature = "overlay"))]
#[derive(Clone)]
pub struct OverlayHandle {
    /// The mounted `OverlayFs`, Arc-shared so the builtin can call inspection
    /// methods without holding a VfsRouter lock.
    pub fs: Arc<OverlayFs>,
    /// VFS path this overlay is mounted at (e.g. `/home/user`).
    pub mount_path: PathBuf,
    /// Real filesystem root to commit into. Same as the lower's root.
    pub commit_root: PathBuf,
}

/// The Kernel (核) — executes kaish code.
///
/// This is the primary interface for running kaish commands. It owns all
/// the runtime state: variables, tools, VFS, jobs, and persistence.
pub struct Kernel {
    /// Kernel name.
    name: String,
    /// Variable scope.
    scope: RwLock<Scope>,
    /// Tool registry.
    tools: Arc<ToolRegistry>,
    /// User-defined tools (from `tool name { body }` statements).
    user_tools: RwLock<HashMap<String, ToolDef>>,
    /// Virtual filesystem router.
    vfs: Arc<VfsRouter>,
    /// Background job manager.
    jobs: Arc<JobManager>,
    /// Pipeline runner.
    runner: PipelineRunner,
    /// Execution context (cwd, stdin, etc.).
    exec_ctx: RwLock<ExecContext>,
    /// Frontend-seeded variables (HOME/PATH/etc, from `KernelConfig::initial_vars`),
    /// retained past construction so `reset()` can re-seed them into the fresh
    /// scope instead of silently dropping them.
    initial_vars: HashMap<String, Value>,
    /// Whether to skip pre-execution validation.
    skip_validation: bool,
    /// When true, standalone external commands inherit stdio for real-time output.
    interactive: bool,
    /// Whether external command execution is allowed.
    allow_external_commands: bool,
    /// Shared memory budget for all kernel-owned `MemoryFs` mounts.
    ///
    /// `None` when `KernelConfig::vfs_budget_bytes` was `None` (unbounded).
    /// `Some` is Arc-cloned into forks so all concurrent execution draws from
    /// the same pool — a background job's writes reduce the same cap as
    /// foreground writes, which is the correct behaviour.
    vfs_budget: Option<Arc<kaish_vfs::ByteBudget>>,
    /// Active overlay session handle, if this kernel was constructed with
    /// `overlay: true`. Arc-shared so `ExecContext` (and thus the
    /// `kaish-vfs` builtin) can inspect and mutate the overlay without
    /// holding a kernel write lock. Propagated to forks via `fork_inner`
    /// and `child_for_pipeline` so `kaish-vfs` works inside background
    /// jobs, scatter workers, and pipeline stages.
    #[cfg(all(feature = "localfs", feature = "overlay"))]
    overlay_handle: Option<Arc<OverlayHandle>>,
    /// Default per-request timeout (None = no default).
    request_timeout: Option<Duration>,
    /// Receiver for the kernel stderr stream.
    ///
    /// Pipeline stages write to the corresponding `StderrStream` (set on ExecContext).
    /// The kernel drains this after each statement in `execute_streaming`.
    stderr_receiver: tokio::sync::Mutex<StderrReceiver>,
    /// Cancellation token for interrupting execution (Ctrl-C).
    ///
    /// Protected by `std::sync::Mutex` (not tokio) because the SIGINT handler
    /// needs sync access. Each `execute()` call gets a fresh child token;
    /// `cancel()` cancels the current token and replaces it.
    cancel_token: std::sync::Mutex<tokio_util::sync::CancellationToken>,
    /// Per-call polled interrupt check (`ExecuteOptions::interrupt`),
    /// installed for the duration of an `execute_with_options` call and
    /// cleared on exit. Consulted by `is_cancelled()` so every existing
    /// cancellation checkpoint gains interrupt awareness without new wiring.
    /// std Mutex for the same sync-access reason as `cancel_token`.
    interrupt: std::sync::Mutex<Option<std::sync::Arc<dyn Fn() -> bool + Send + Sync>>>,
    /// Terminal state for job control (interactive mode only, Unix only).
    #[cfg(all(unix, feature = "subprocess"))]
    terminal_state: Option<Arc<crate::terminal::TerminalState>>,
    /// Weak self-reference for handing out `Arc<dyn CommandDispatcher>`.
    ///
    /// Set by `into_arc()`. Allows builtins to re-dispatch inner commands
    /// through the full Kernel resolution chain.
    self_weak: std::sync::OnceLock<std::sync::Weak<Self>>,
    /// Serializes concurrent `execute()` / `execute_streaming()` callers on
    /// this Kernel instance. Tokio's Mutex is fair (FIFO) and acts as the
    /// queue. Background jobs, scatter workers, and concurrent pipeline
    /// stages do NOT take this lock — they run against a *forked* Kernel
    /// (see [`Kernel::fork`]) so they never contend with the foreground.
    execute_lock: tokio::sync::Mutex<()>,
    /// Current dynamic statement-engine re-entry depth — incremented on entry
    /// to command substitution, a shell-function call, or a `.kai` source, and
    /// decremented (via an RAII guard, so cancellation stays balanced) on exit.
    /// Checked against [`MAX_RECURSION_DEPTH`] to turn a stack overflow into a
    /// loud error (GH #46). Per-Kernel: a fork starts fresh at 0 because it
    /// runs on its own stack. Atomic only for `Send`/`Sync`; within one Kernel
    /// the recursion chain is single-threaded (top-level `execute` is
    /// serialized by `execute_lock`; concurrency happens on forks).
    recursion_depth: AtomicUsize,
}

/// RAII balance for [`Kernel::recursion_depth`]: increments on construction
/// (in `enter_recursion`) and decrements on drop, so a cancelled or
/// error-unwound re-entry can never leave the counter inflated (which would
/// spuriously trip later, unrelated recursions).
struct RecursionGuard<'a> {
    counter: &'a AtomicUsize,
}

impl Drop for RecursionGuard<'_> {
    fn drop(&mut self) {
        self.counter.fetch_sub(1, Ordering::Relaxed);
    }
}

/// Internal result of [`Kernel::setup_vfs`].
struct VfsSetupResult {
    vfs: VfsRouter,
    budget: Option<Arc<ByteBudget>>,
    #[cfg(all(feature = "localfs", feature = "overlay"))]
    overlay_handle: Option<Arc<OverlayHandle>>,
}

impl Kernel {
    /// Create a new kernel with the given configuration.
    pub fn new(config: KernelConfig) -> Result<Self> {
        let mut setup = Self::setup_vfs(&config)?;
        // An embedder-supplied manager keeps `cmd &` jobs alive across kernels
        // (see `KernelConfig::job_manager`); with none, this kernel owns its
        // own job table exactly as before.
        let jobs = config.job_manager.clone().unwrap_or_else(|| Arc::new(JobManager::new()));
        // Mirror the cascade's SIGTERM->SIGKILL grace onto the manager so the
        // kill builtin bounds its wait-for-death on the same number (GH #244).
        jobs.set_kill_grace(config.kill_grace);

        // Mount JobFs for job observability at /v/jobs
        setup.vfs.mount("/v/jobs", JobFs::new(jobs.clone()));

        #[cfg(all(feature = "localfs", feature = "overlay"))]
        let overlay_handle = setup.overlay_handle.take();

        // Mode-based construction: the kernel owns its host mounts, so whether
        // host side channels are allowed is decided by the VFS mode inside
        // `assemble` (NoLocal forbids them).
        let kernel = Self::assemble(config, setup.vfs, jobs, false, setup.budget, |_| {}, |vfs_ref, tools| {
            ExecContext::with_vfs_and_tools(vfs_ref.clone(), tools.clone())
        })?;

        #[cfg(all(feature = "localfs", feature = "overlay"))]
        {
            let mut kernel = kernel;
            kernel.overlay_handle = overlay_handle;
            // Also set it on the ExecContext so builtins can access it.
            if let Some(ref handle) = kernel.overlay_handle {
                kernel.exec_ctx.get_mut().overlay_handle = Some(Arc::clone(handle));
            }
            return Ok(kernel);
        }

        #[allow(unreachable_code)]
        Ok(kernel)
    }

    /// Set up VFS based on mount mode.
    ///
    /// Returns the router, the budget handle (if bounded), and an optional
    /// overlay handle when `config.overlay` is true. The budget is Arc-shared:
    /// every `MemoryFs` the kernel creates here holds a clone of the same
    /// `Arc<ByteBudget>`, so the total charged against it is the sum of all
    /// in-memory content across all kernel-owned memory mounts.
    ///
    /// # Errors
    /// Returns `Err` if `config.overlay` is true and the mode is `NoLocal`
    /// (overlay is meaningless when everything is already virtual — there is
    /// no real lower layer to wrap). The caller (`Kernel::new`) propagates
    /// this as an `anyhow::Error`.
    fn setup_vfs(config: &KernelConfig) -> Result<VfsSetupResult> {
        let mut vfs = VfsRouter::new();

        // One budget for all memory mounts this kernel owns — labeled so the
        // error message tells the user exactly which knob to raise.
        let budget: Option<Arc<ByteBudget>> = config
            .vfs_budget_bytes
            .map(|bytes| Arc::new(ByteBudget::labeled(bytes, "vfs-memory")));

        /// Helper: construct a `MemoryFs` wired to `budget` if present.
        fn mem(budget: &Option<Arc<ByteBudget>>) -> MemoryFs {
            match budget {
                Some(b) => MemoryFs::with_budget(Arc::clone(b)),
                None => MemoryFs::new(),
            }
        }

        // Overlay handle — populated below if config.overlay is true.
        #[cfg(all(feature = "localfs", feature = "overlay"))]
        let mut overlay_handle: Option<Arc<OverlayHandle>> = None;

        match &config.vfs_mode {
            #[cfg(feature = "localfs")]
            VfsMountMode::Passthrough => {
                #[cfg(feature = "overlay")]
                if config.overlay {
                    // Wrap "/" in an OverlayFs so writes are virtual.
                    let lower = Arc::new(LocalFs::read_only(PathBuf::from("/")));
                    let overlay_fs = Arc::new(match &budget {
                        Some(b) => OverlayFs::over_with_budget(lower, Arc::clone(b)),
                        None => OverlayFs::over(lower),
                    });
                    let handle = Arc::new(OverlayHandle {
                        fs: Arc::clone(&overlay_fs),
                        mount_path: PathBuf::from("/"),
                        commit_root: PathBuf::from("/"),
                    });
                    vfs.mount_arc("/", overlay_fs as Arc<dyn kaish_vfs::Filesystem>);
                    overlay_handle = Some(handle);
                } else {
                    // LocalFs at "/" — native paths work directly
                    vfs.mount("/", LocalFs::new(PathBuf::from("/")));
                }
                #[cfg(not(feature = "overlay"))]
                {
                    if config.overlay {
                        return Err(anyhow::anyhow!(
                            "overlay=true requires the `overlay` feature, but this build \
                             was compiled without it. Recompile with --features overlay \
                             (or the default feature set) to enable overlay mode."
                        ));
                    }
                    // LocalFs at "/" — native paths work directly
                    vfs.mount("/", LocalFs::new(PathBuf::from("/")));
                }
                // Memory for blobs
                vfs.mount("/v", mem(&budget));
            }
            #[cfg(feature = "localfs")]
            VfsMountMode::Sandboxed { root } => {
                // Memory at root for safety (catches paths outside sandbox).
                // Note: /tmp and the XDG runtime dir are LocalFs — writes
                // there escape the VFS budget and are NOT virtual. This is
                // intentional: /tmp interop with other processes matters more
                // than accounting for scratch files there.
                vfs.mount("/", mem(&budget));
                vfs.mount("/v", mem(&budget));

                // Synthetic /dev: the host's real /dev isn't reachable here, so
                // /dev/null and /dev/zero are software-backed (see DevFs).
                vfs.mount("/dev", DevFs::new());

                // Real /tmp for interop with other processes
                vfs.mount("/tmp", LocalFs::new(PathBuf::from("/tmp")));

                // Mount XDG runtime dir for spill files and socket access
                let runtime = crate::paths::xdg_runtime_dir();
                if runtime.exists() {
                    let runtime_str = runtime.to_string_lossy().to_string();
                    vfs.mount(&runtime_str, LocalFs::new(runtime));
                }

                // Resolve the sandbox root (defaults to $HOME)
                let local_root = root.clone().unwrap_or_else(|| {
                    std::env::var("HOME")
                        .map(PathBuf::from)
                        .unwrap_or_else(|_| PathBuf::from("/"))
                });

                let mount_point = local_root.to_string_lossy().to_string();

                #[cfg(feature = "overlay")]
                if config.overlay {
                    // Wrap the sandbox root in an OverlayFs.
                    let lower = Arc::new(LocalFs::read_only(local_root.clone()));
                    let overlay_fs = Arc::new(match &budget {
                        Some(b) => OverlayFs::over_with_budget(lower, Arc::clone(b)),
                        None => OverlayFs::over(lower),
                    });
                    let handle = Arc::new(OverlayHandle {
                        fs: Arc::clone(&overlay_fs),
                        mount_path: PathBuf::from(&mount_point),
                        commit_root: local_root,
                    });
                    vfs.mount_arc(&mount_point, overlay_fs as Arc<dyn kaish_vfs::Filesystem>);
                    overlay_handle = Some(handle);
                } else {
                    // Mount at the real path for transparent access
                    // e.g., /home/atobey → LocalFs("/home/atobey")
                    // so /home/atobey/src/kaish just works
                    vfs.mount(&mount_point, LocalFs::new(local_root));
                }
                #[cfg(not(feature = "overlay"))]
                {
                    if config.overlay {
                        return Err(anyhow::anyhow!(
                            "overlay=true requires the `overlay` feature, but this build \
                             was compiled without it. Recompile with --features overlay \
                             (or the default feature set) to enable overlay mode."
                        ));
                    }
                    // Mount at the real path for transparent access
                    vfs.mount(&mount_point, LocalFs::new(local_root));
                }
            }
            VfsMountMode::NoLocal => {
                if config.overlay {
                    return Err(anyhow::anyhow!(
                        "overlay=true is incompatible with VfsMountMode::NoLocal: \
                         everything is already virtual, there is no real lower layer \
                         to wrap. Use with_overlay(false) or switch to a Passthrough \
                         or Sandboxed VFS mode."
                    ));
                }
                // Pure memory mode — no local filesystem
                vfs.mount("/", mem(&budget));
                vfs.mount("/tmp", mem(&budget));
                vfs.mount("/v", mem(&budget));
                // Synthetic /dev so /dev/null and /dev/zero work hermetically.
                vfs.mount("/dev", DevFs::new());
            }
        }

        Ok(VfsSetupResult {
            vfs,
            budget,
            #[cfg(all(feature = "localfs", feature = "overlay"))]
            overlay_handle,
        })
    }

    /// Create a transient kernel (no persistence).
    pub fn transient() -> Result<Self> {
        Self::new(KernelConfig::transient())
    }

    /// Create a kernel with a custom backend and `/v/*` virtual path support.
    ///
    /// This is the constructor for embedding kaish in other systems that provide
    /// their own storage backend (e.g., CRDT-backed storage in kaijutsu).
    ///
    /// A `VirtualOverlayBackend` routes paths automatically:
    /// - `/v/*` → Internal VFS (JobFs at `/v/jobs`, MemoryFs at `/v/blobs`)
    /// - `/dev` → DevFs (synthetic `/dev/null`, `/dev/zero`, `/dev/random`,
    ///   `/dev/urandom`) — kernel-owned so it works even when your backend is
    ///   read-only
    /// - Everything else → Your custom backend
    ///
    /// The optional `configure_vfs` closure lets you add additional virtual mounts
    /// (e.g., `/v/docs` for CRDT blocks) after the built-in mounts are set up.
    ///
    /// **Note:** The config's `vfs_mode` is ignored — all non-`/v/*` path routing
    /// is handled by your custom backend. The config is only used for `name`, `cwd`,
    /// `skip_validation`, and `interactive`.
    ///
    /// # Example
    ///
    /// ```ignore
    /// // Simple: default /v/* mounts only
    /// let kernel = Kernel::with_backend(backend, config, |_| {}, |_| {})?;
    ///
    /// // With custom mounts
    /// let kernel = Kernel::with_backend(backend, config, |vfs| {
    ///     vfs.mount_arc("/v/docs", docs_fs);
    ///     vfs.mount_arc("/v/g", git_fs);
    /// }, |_| {})?;
    ///
    /// // With custom tools
    /// let kernel = Kernel::with_backend(backend, config, |_| {}, |tools| {
    ///     tools.register(MyCustomTool::new());
    /// })?;
    /// ```
    pub fn with_backend(
        backend: Arc<dyn KernelBackend>,
        config: KernelConfig,
        configure_vfs: impl FnOnce(&mut VfsRouter),
        configure_tools: impl FnOnce(&mut ToolRegistry),
    ) -> Result<Self> {
        use crate::backend::VirtualOverlayBackend;

        // overlay=true is incompatible with with_backend: the embedder controls
        // the VFS and the kernel cannot wrap it without bypassing the embedder's
        // semantics. Fail loudly rather than silently ignoring the flag.
        if config.overlay {
            return Err(anyhow::anyhow!(
                "overlay=true is incompatible with Kernel::with_backend: the embedder \
                 controls the VFS; the kernel cannot wrap it with an OverlayFs without \
                 bypassing the embedder's storage semantics. Use KernelConfig::with_overlay(false)."
            ));
        }

        let mut vfs = VfsRouter::new();
        // See `Kernel::new` — the embedder's manager wins here too.
        let jobs = config.job_manager.clone().unwrap_or_else(|| Arc::new(JobManager::new()));
        // Mirror the cascade's SIGTERM->SIGKILL grace onto the manager so the
        // kill builtin bounds its wait-for-death on the same number (GH #244).
        jobs.set_kill_grace(config.kill_grace);

        // Create the budget from config so `with_vfs_budget` / `without_vfs_budget`
        // work for `with_backend` callers too. The /v/blobs MemoryFs is the only
        // kernel-owned memory mount here — embedders own the rest of the VFS.
        let vfs_budget: Option<Arc<ByteBudget>> = config
            .vfs_budget_bytes
            .map(|bytes| Arc::new(ByteBudget::labeled(bytes, "vfs-memory")));

        vfs.mount("/v/jobs", JobFs::new(jobs.clone()));
        let blobs_fs = match &vfs_budget {
            Some(b) => MemoryFs::with_budget(Arc::clone(b)),
            None => MemoryFs::new(),
        };
        vfs.mount("/v/blobs", blobs_fs);

        // /dev/null and friends are software-backed (see DevFs) and must not
        // depend on the embedder's backend — a read-only embedder backend
        // (e.g. kaijutsu's read-only host root) would otherwise reject writes
        // to /dev/null as a filesystem error instead of discarding them.
        vfs.mount("/dev", DevFs::new());

        // Let caller add custom mounts (e.g., /v/docs, /v/g)
        configure_vfs(&mut vfs);

        // A custom-backend kernel owns no host mounts — the embedder supplies
        // the entire VFS — so any kernel write to a host filesystem via
        // `std::fs` (output spill, job output files) bypasses that VFS and its
        // read-only guarantees. Forbid host side channels unconditionally.
        Self::assemble(config, vfs, jobs, true, vfs_budget, configure_tools, |vfs_arc: &Arc<VfsRouter>, _: &Arc<ToolRegistry>| {
            let overlay: Arc<dyn KernelBackend> =
                Arc::new(VirtualOverlayBackend::new(backend, vfs_arc.clone()));
            ExecContext::with_backend(overlay)
        })
    }

    /// Shared assembly: wires up tools, runner, scope, and ExecContext.
    ///
    /// The `make_ctx` closure receives the VFS and tools so backends that need
    /// them (like `LocalBackend::with_tools`) can capture them. Custom backends
    /// that already have their own storage can ignore these parameters.
    fn assemble(
        config: KernelConfig,
        mut vfs: VfsRouter,
        jobs: Arc<JobManager>,
        no_host_filesystem: bool,
        vfs_budget: Option<Arc<ByteBudget>>,
        configure_tools: impl FnOnce(&mut ToolRegistry),
        make_ctx: impl FnOnce(&Arc<VfsRouter>, &Arc<ToolRegistry>) -> ExecContext,
    ) -> Result<Self> {
        // A kernel with no host filesystem of its own must never write to one
        // through a side channel. Two paths bypass the VFS by going straight to
        // `std::fs`: output spill (`paths::spill_dir()` → host temp/cache) and
        // background-job output files (`Job::write_output_file` → host temp).
        // Both would punch through the isolation, so force them off:
        // in-memory truncation for spill, no host file for job output.
        //
        // This is true for a `NoLocal` kernel (mounts nothing) and for any
        // `with_backend` kernel (`no_host_filesystem` — the embedder owns the
        // VFS, so the kernel controls no host mounts and any host write is a
        // bypass). Overrides an explicit `SpillMode::Disk`, which is nonsensical
        // when there is no kernel-owned host filesystem to spill to.
        let no_host_side_channel =
            no_host_filesystem || matches!(config.vfs_mode, VfsMountMode::NoLocal);

        let KernelConfig { name, cwd, skip_validation, interactive, ignore_config, mut output_limit, allow_external_commands, trash_enabled, errexit_enabled, initial_vars, request_timeout, kill_grace, kill_children_on_parent_death, .. } = config;

        if no_host_side_channel {
            output_limit.set_spill_mode(crate::output_limit::SpillMode::Memory);
            jobs.set_persist_output_files(false);
        }

        let mut tools = ToolRegistry::new();
        register_builtins(&mut tools);
        configure_tools(&mut tools);
        let tools = Arc::new(tools);

        // Mount BuiltinFs so `ls /v/bin` lists builtins
        vfs.mount("/v/bin", BuiltinFs::new(tools.clone()));

        let vfs = Arc::new(vfs);

        let runner = PipelineRunner::new(tools.clone());

        let (stderr_writer, stderr_receiver) = stderr_stream();

        let mut exec_ctx = make_ctx(&vfs, &tools);
        let initial_cwd = cwd.clone();
        exec_ctx.set_cwd(cwd);
        exec_ctx.kill_children_on_parent_death = kill_children_on_parent_death;
        exec_ctx.kill_grace = kill_grace;
        exec_ctx.set_job_manager(jobs.clone());
        exec_ctx.set_tool_schemas(tools.schemas());
        exec_ctx.set_tools(tools.clone());
        #[cfg(feature = "os-integration")]
        exec_ctx.set_trash_backend(Arc::new(crate::trash_system::SystemTrash));
        exec_ctx.stderr = Some(stderr_writer);
        exec_ctx.ignore_config = ignore_config;
        exec_ctx.output_limit = output_limit;
        exec_ctx.allow_external_commands = allow_external_commands;
        exec_ctx.vfs_budget = vfs_budget.clone();

        Ok(Self {
            name,
            scope: RwLock::new({
                let mut scope = Scope::new();
                scope.set_pid(KERNEL_COUNTER.fetch_add(1, Ordering::Relaxed));
                // HOME is NOT read from the host env here — the kernel is
                // hermetic. Frontends (REPL, MCP) seed it via `initial_vars`
                // below (from `std::env::vars()`); a hermetic embedder leaves
                // `initial_vars` empty and gets no HOME (tilde stays literal).
                // Apply caller-supplied initial variables, all marked exported.
                // Frontends (REPL, MCP) populate this from std::env::vars()
                // for shell-like UX; embedders that want hermetic behavior
                // simply leave it empty.
                for (name, value) in initial_vars.clone() {
                    scope.set_exported(name, value);
                }
                scope.set_trash_enabled(trash_enabled);
                scope.set_error_exit(errexit_enabled);
                // `$PWD` before any `cd`. Seeded HERE, not just on `exec_ctx`:
                // this is the scope execution reads, and `exec_ctx.scope` is
                // overwritten from it at every dispatch, so a value written
                // only there never survives to be read.
                scope.set_global(
                    "PWD",
                    Value::String(initial_cwd.to_string_lossy().into_owned()),
                );
                // `$OLDPWD` is DROPPED rather than seeded. There is no previous
                // directory yet, and an inherited one describes the invoking
                // shell's history, not this session's — `cd -` already refuses
                // with "OLDPWD not set", and the variable must not contradict
                // it by naming a directory `cd -` will not go to.
                scope.remove("OLDPWD");
                scope
            }),
            initial_vars,
            tools,
            user_tools: RwLock::new(HashMap::new()),
            vfs,
            jobs,
            runner,
            exec_ctx: RwLock::new(exec_ctx),
            skip_validation,
            interactive,
            allow_external_commands,
            vfs_budget,
            request_timeout,
            stderr_receiver: tokio::sync::Mutex::new(stderr_receiver),
            cancel_token: std::sync::Mutex::new(tokio_util::sync::CancellationToken::new()),
            interrupt: std::sync::Mutex::new(None),
            #[cfg(all(unix, feature = "subprocess"))]
            terminal_state: None,
            self_weak: std::sync::OnceLock::new(),
            execute_lock: tokio::sync::Mutex::new(()),
            recursion_depth: AtomicUsize::new(0),
            // Overlay handle is set by Kernel::new after assemble returns;
            // assemble itself doesn't know the handle (it's constructed in setup_vfs).
            // with_backend always has None (overlay=true is rejected above).
            #[cfg(all(feature = "localfs", feature = "overlay"))]
            overlay_handle: None,
        })
    }

    /// Plan every statement of `source` without executing anything —
    /// [`plan_program`](crate::ast::plan::plan_program) as a method, so an
    /// embedder holding a kernel can pair the plans with `get_var` lookups
    /// against this kernel's live state.
    ///
    /// # Errors
    ///
    /// Returns the parse errors when `source` does not parse.
    pub fn plan_program(
        &self,
        source: &str,
    ) -> Result<Vec<crate::ast::plan::PlannedStatement>, Vec<crate::parser::ParseError>> {
        crate::ast::plan::plan_program(source)
    }

    /// Expand one heredoc body against a scope the caller supplies —
    /// [`expand_fragment`](crate::fragment::expand_fragment) as a method.
    ///
    /// The scope is the caller's, not this kernel's: pair it with `get_var`
    /// when the session's values are the ones to judge against, and supply
    /// different values when they are not. Nothing executes, and a `$(…)` in
    /// the body comes back as a [`Hole`](kaish_types::plan::Hole) rather than
    /// running here.
    ///
    /// # Errors
    ///
    /// Returns a [`FragmentError`](crate::fragment::FragmentError) when the
    /// source does not parse, the address names no heredoc, or the body reads
    /// something the supplied scope does not carry.
    pub fn expand_fragment(
        &self,
        source: &str,
        addr: kaish_types::plan::FragmentAddr,
        scope: &[(String, Value)],
    ) -> Result<kaish_types::plan::Expansion, crate::fragment::FragmentError> {
        crate::fragment::expand_fragment(source, addr, scope)
    }

    /// Get the kernel name.
    pub fn name(&self) -> &str {
        &self.name
    }

    /// Wrap this Kernel in an Arc and initialize its self-reference.
    ///
    /// This enables the Kernel to hand out `Arc<dyn CommandDispatcher>` references
    /// to child contexts, allowing builtins like `timeout` to dispatch inner
    /// commands through the full resolution chain (user tools → builtins →
    /// .kai scripts → external commands).
    pub fn into_arc(self) -> Arc<Self> {
        let arc = Arc::new(self);
        let _ = arc.self_weak.set(Arc::downgrade(&arc));
        arc
    }

    /// Fork a subsidiary kernel for concurrent execution.
    ///
    /// The fork is a fully-functional `Kernel` that:
    /// - **Snapshots** per-session state from the parent: scope (COW — cheap),
    ///   user-defined tools, cwd, aliases, ignore config, etc. Mutations on
    ///   the fork do NOT propagate back to the parent — matching bash
    ///   subshell / background-job semantics.
    /// - **Shares** read-mostly resources with the parent via `Arc`: the tool
    ///   registry, the VFS router, and the job manager. A job registered by
    ///   the fork is visible to the parent's `jobs` builtin, and the fork
    ///   sees the same VFS mounts.
    /// - **Owns** its own `stderr_receiver`, `cancel_token`, and
    ///   `execute_lock`. It is never the TTY owner, so `interactive` is
    ///   `false` and `terminal_state` is `None`.
    ///
    /// The returned Arc has its `self_weak` populated (via `into_arc`), so
    /// nested dispatch through `ctx.dispatcher` (e.g. the `timeout` builtin)
    /// routes through the fork itself, not the parent — which is essential
    /// for concurrency safety.
    ///
    /// Use this for **detached** background concurrency where the fork should
    /// survive parent cancellation: the `&` background-job operator and any
    /// other "fire and forget" worker. The fork gets a fresh, independent
    /// cancellation token.
    ///
    /// For foreground concurrency (scatter workers, concurrent pipeline
    /// stages, `$(...)` cmdsubs) where parent timeout/cancel must cascade
    /// into the fork's external children, use [`Self::fork_attached`].
    pub async fn fork(&self) -> Arc<Self> {
        let background_job = self.exec_ctx.read().await.background_job;
        self.fork_inner(tokio_util::sync::CancellationToken::new(), background_job)
            .await
    }

    /// Fork attached to the parent's cancellation.
    ///
    /// Same as [`Self::fork`] but the fork's `cancel_token` is a child of
    /// the parent's. When the parent cancels (request timeout, embedder
    /// `Kernel::cancel`, etc.), the fork's token also cancels, which in
    /// turn kills any external children spawned in the fork via the
    /// `wait_or_kill` / SIGTERM-grace-SIGKILL path.
    pub async fn fork_attached(&self) -> Arc<Self> {
        let child_token = {
            #[allow(clippy::expect_used)]
            let parent = self.cancel_token.lock().expect("cancel_token poisoned");
            parent.child_token()
        };
        let background_job = self.exec_ctx.read().await.background_job;
        self.fork_inner(child_token, background_job).await
    }

    /// Fork for a background job, stamping the job id so external commands
    /// spawned anywhere beneath it record their process groups on that job
    /// (for `kill -<sig> %N`). The caller owns `cancel` so it can also drive
    /// `JobManager::cancel`.
    pub async fn fork_for_background(
        &self,
        cancel: tokio_util::sync::CancellationToken,
        job_id: crate::scheduler::JobId,
    ) -> Arc<Self> {
        self.fork_inner(cancel, Some(job_id)).await
    }

    /// Shared fork implementation. Caller decides the cancellation token and
    /// which background job (if any) this fork runs on behalf of.
    async fn fork_inner(
        &self,
        cancel: tokio_util::sync::CancellationToken,
        background_job: Option<crate::scheduler::JobId>,
    ) -> Arc<Self> {
        let scope_snapshot = self.scope.read().await.clone();
        let user_tools_snapshot = self.user_tools.read().await.clone();

        // Snapshot exec_ctx by cloning the cloneable fields, then override
        // the ones that should not carry over (stderr channel, dispatcher,
        // interactive flag, terminal state, cancel — set from `cancel` arg).
        let mut fork_ctx = {
            let parent_ctx = self.exec_ctx.read().await;
            parent_ctx.child_for_pipeline()
        };
        let (stderr_writer, stderr_receiver) = stderr_stream();
        fork_ctx.stderr = Some(stderr_writer);
        // Clear dispatcher; dispatch_command will repopulate it to point at
        // the fork on the first dispatch call.
        fork_ctx.dispatcher = None;
        fork_ctx.interactive = false;
        fork_ctx.cancel = cancel.clone();
        fork_ctx.background_job = background_job;
        #[cfg(all(unix, feature = "subprocess"))]
        {
            fork_ctx.terminal_state = None;
        }

        let fork = Self {
            name: format!("{}:fork", self.name),
            scope: RwLock::new(scope_snapshot),
            initial_vars: self.initial_vars.clone(),
            tools: Arc::clone(&self.tools),
            user_tools: RwLock::new(user_tools_snapshot),
            vfs: Arc::clone(&self.vfs),
            jobs: Arc::clone(&self.jobs),
            runner: self.runner.clone(),
            exec_ctx: RwLock::new(fork_ctx),
            skip_validation: self.skip_validation,
            // Forks are never the TTY owner — they run in the background.
            interactive: false,
            allow_external_commands: self.allow_external_commands,
            // Arc-clone the budget so the fork draws from the same pool as the
            // parent — background jobs and scatter workers count against the same
            // cap as foreground writes.
            vfs_budget: self.vfs_budget.clone(),
            request_timeout: self.request_timeout,
            stderr_receiver: tokio::sync::Mutex::new(stderr_receiver),
            cancel_token: std::sync::Mutex::new(cancel),
            interrupt: std::sync::Mutex::new(None),
            #[cfg(all(unix, feature = "subprocess"))]
            terminal_state: None,
            self_weak: std::sync::OnceLock::new(),
            execute_lock: tokio::sync::Mutex::new(()),
            // A fork runs on a fresh stack (spawned task) — its recursion
            // budget is independent of the parent's current depth (GH #46).
            recursion_depth: AtomicUsize::new(0),
            // Arc-clone the overlay handle so forks (background jobs, scatter
            // workers, pipeline stages) can reach the same overlay transaction
            // via `kaish-vfs status/diff/commit/reset`.
            #[cfg(all(feature = "localfs", feature = "overlay"))]
            overlay_handle: self.overlay_handle.clone(),
        };

        fork.into_arc()
    }

    /// Get an `Arc<dyn CommandDispatcher>` to this Kernel, if wrapped via `into_arc()`.
    ///
    /// Returns `None` if the Kernel was not wrapped, or if all strong references
    /// have been dropped (the `Weak` can no longer upgrade).
    pub fn dispatcher(&self) -> Option<Arc<dyn CommandDispatcher>> {
        self.self_weak
            .get()
            .and_then(|weak| weak.upgrade())
            .map(|arc| arc as Arc<dyn CommandDispatcher>)
    }

    /// Initialize terminal state for interactive job control.
    ///
    /// Call this after kernel creation when running as an interactive REPL
    /// and stdin is a TTY. Sets up process groups and signal handling.
    #[cfg(all(unix, feature = "subprocess"))]
    pub fn init_terminal(&mut self) {
        if !self.interactive {
            return;
        }
        match crate::terminal::TerminalState::init() {
            Ok(state) => {
                let state = Arc::new(state);
                self.terminal_state = Some(state.clone());
                // Set on exec_ctx so builtins (fg, bg, kill) can access it
                self.exec_ctx.get_mut().terminal_state = Some(state);
                tracing::debug!("terminal job control initialized");
            }
            Err(e) => {
                tracing::warn!("failed to initialize terminal job control: {}", e);
            }
        }
    }

    /// Replace or remove the trash backend used by `rm` and `kaish-trash`.
    ///
    /// The kernel installs the OS trash (`SystemTrash`) automatically when
    /// built with the `os-integration` feature. Embedders and tests can swap
    /// in a custom [`crate::trash::TrashBackend`], or pass `None` to remove
    /// it — with trash enabled but no backend present, `rm` fails loud
    /// rather than falling through to permanent delete.
    pub fn set_trash_backend(&mut self, backend: Option<Arc<dyn crate::trash::TrashBackend>>) {
        self.exec_ctx.get_mut().trash_backend = backend;
    }

    /// Cancel the current execution.
    ///
    /// This cancels the current cancellation token, causing any execution
    /// loop to exit at the next checkpoint with exit code 130 (SIGINT).
    /// A fresh token is installed for the next `execute()` call.
    pub fn cancel(&self) {
        #[allow(clippy::expect_used)]
        let token = self.cancel_token.lock().expect("cancel_token poisoned");
        token.cancel();
    }

    /// Check if the current execution has been cancelled.
    ///
    /// Also the polling point for `ExecuteOptions::interrupt`: when the
    /// embedder's check reports true, the internal token fires here, so every
    /// call site of this method is an interrupt checkpoint for free.
    pub fn is_cancelled(&self) -> bool {
        let interrupted = {
            #[allow(clippy::expect_used)]
            let check = self.interrupt.lock().expect("interrupt poisoned");
            check.as_ref().is_some_and(|f| f())
        };
        if interrupted {
            self.cancel();
        }
        #[allow(clippy::expect_used)]
        let token = self.cancel_token.lock().expect("cancel_token poisoned");
        token.is_cancelled()
    }

    /// Reset the cancellation token (called at the start of each execute).
    ///
    /// A `Kernel::cancel()` that arrives while nothing is running is dropped
    /// here: the next `execute()` replaces the cancelled token and runs
    /// normally, and nothing in that call's result reports a cancel was
    /// discarded. An embedder can see the pending cancel before it is dropped —
    /// `is_cancelled()` reports true until the next `execute()` clears it — but
    /// a call that must start already cancelled has to supply its own
    /// `ExecuteOptions::cancel_token`, which is a read-only input and is never
    /// reset; a pre-cancelled one stops the call at its first checkpoint.
    fn reset_cancel(&self) -> tokio_util::sync::CancellationToken {
        #[allow(clippy::expect_used)]
        let mut token = self.cancel_token.lock().expect("cancel_token poisoned");
        if token.is_cancelled() {
            *token = tokio_util::sync::CancellationToken::new();
        }
        token.clone()
    }

    /// Acquire the per-Kernel execute lock, warning on contention.
    ///
    /// Tokio's Mutex is fair (FIFO) so callers queue in arrival order. When
    /// the lock is already held, emit a warning so the silent serialization
    /// is observable in logs — if you need real parallelism, fork the kernel.
    async fn acquire_execute_lock(&self) -> tokio::sync::MutexGuard<'_, ()> {
        match self.execute_lock.try_lock() {
            Ok(guard) => guard,
            Err(_) => {
                tracing::warn!(
                    target: "kaish::kernel::concurrency",
                    kernel = %self.name,
                    "execute() contended — serializing concurrent caller; \
                     use Kernel::fork() for parallelism instead of sharing"
                );
                self.execute_lock.lock().await
            }
        }
    }

    /// Execute kaish source code with default options.
    ///
    /// Equivalent to `execute_with_options(input, ExecuteOptions::default())`.
    /// Returns the result of the last statement executed.
    ///
    /// # Errors
    ///
    /// Returns [`KernelError`] when the program was rejected before running
    /// (a lex/parse failure or a validator rejection) or faulted while
    /// running. See [`KernelError::is_rejected`] to route on that
    /// distinction. A nonzero exit from the *script itself* — a failed
    /// command, `set -e` — is not an `Err`; it comes back as `Ok` with the
    /// exit code folded into the returned [`ExecResult`].
    pub async fn execute(&self, input: &str) -> Result<ExecResult, KernelError> {
        self.run_inner(input, ExecuteOptions::default(), None, None)
            .await
            .map_err(classify_execute_error)
    }

    /// Argv-native peer of [`Self::execute`] — run one command whose arguments
    /// are **already tokenized**.
    ///
    /// `execute(&str)` is string-native: it lexes and parses its input. A caller
    /// that already holds OS/structured argv (a busybox-style multicall binary, a
    /// structured embedder like kaijutsu) would otherwise have to re-quote argv
    /// into a string just to have the lexer split it apart again — a round-trip
    /// that is lossy for typed values, since `to_argv()` stringifies
    /// [`Value::Bytes`]/[`Value::Json`]. `execute_argv` skips it.
    ///
    /// **Tokens are literal.** No glob expansion, no `$VAR` interpolation, no
    /// command substitution, no word splitting — the "single-quoted word"
    /// semantics taken to its end. `execute_argv("echo", &[Value::String("*.txt"
    /// .into())])` emits `*.txt`; it does not glob. (One shared-binder expansion
    /// does still apply, for consistency with the string door: a leading `~` is
    /// expanded against the session `HOME` — kaish expands `~` uniformly, so the
    /// two doors agree. Pass a pre-resolved path if you need it byte-literal.) A
    /// non-string `Value`
    /// (`Bytes`/`Json`/`Int`) lands directly in `ToolArgs.positional`, so typed
    /// data survives without a `to_argv()` round-trip. (Caveat: the two-layer
    /// clap arg model means a builtin that re-parses its own `to_argv()` still
    /// sees a stringified value; the typed-passthrough win fully lands only for
    /// builtins that read `args.positional` directly — the documented pattern.)
    ///
    /// This is a *peer*, not a subset: a command string can carry pipelines,
    /// `&&`/`||`, control flow and `$()` that have no argv encoding, so the two
    /// doors converge **late** (at the shared dispatch chain) rather than one
    /// wrapping the other. From argv classification onward `execute_argv` reuses
    /// the exact path a `Stmt::Command` takes — command resolution (aliases, user
    /// tools, `.kai` scripts, externals, backend tools), arg binding, and the
    /// `--json` transform — so an `ls --json` still applies output formatting. The kernel's
    /// pre-execution *syntax* validator does not run: argv has no shell syntax to
    /// validate (a tool's own `validate()`/clap parse still runs at dispatch).
    ///
    /// Concurrent callers serialize on the same execute lock as [`Self::execute`],
    /// and the kernel's configured `request_timeout` applies (a hung builtin or
    /// external is interrupted at the deadline with exit code 124, the same as the
    /// string door). There is no per-call options surface yet — a future
    /// `execute_argv_with_options` would carry per-call timeout/cancel/vars/cwd.
    ///
    /// # Errors
    ///
    /// Returns [`KernelError`], always [`KernelError::Execution`] — argv has
    /// no shell syntax to reject, so `execute_argv` never returns
    /// [`KernelError::Parse`] or [`KernelError::Validation`] (a tool's own
    /// `validate()`/clap parse at dispatch still surfaces here, as an
    /// execution failure).
    #[tracing::instrument(level = "info", skip(self, argv), fields(cmd = name, argc = argv.len()))]
    pub async fn execute_argv(&self, name: &str, argv: &[Value]) -> Result<ExecResult, KernelError> {
        let _guard = self.acquire_execute_lock().await;
        self.execute_argv_locked(name, argv).await.map_err(classify_execute_error)
    }

    /// [`Self::execute_argv`]'s body, with the execute lock assumed **held**.
    async fn execute_argv_locked(&self, name: &str, argv: &[Value]) -> Result<ExecResult> {
        // Fresh cancel surface for this call: `execute_pipeline` reads
        // `self.cancel_token`, so a stale cancelled token from a prior call must be
        // replaced first. The returned clone is the token the watchdog cancels on
        // an elapsed deadline (it shares state with what `execute_pipeline` reads),
        // cascading SIGTERM/SIGKILL to any external child.
        let cancel = self.reset_cancel();

        // Honor the kernel-configured request timeout for parity with `execute`.
        let timeout = self.request_timeout;
        if timeout == Some(Duration::ZERO) {
            return Ok(ExecResult::failure(124, "timeout: timed out after 0s".to_string()));
        }

        let command = crate::ast::Command {
            name: name.to_string(),
            args: argv_to_args(argv),
            redirects: Vec::new(),
        };

        let pipeline = crate::ast::Pipeline {
            stages: vec![crate::ast::PipelineStage::Command(command)],
            background: false,
        };
        let work = async {
            let result = self.execute_pipeline(&pipeline).await?;
            // A gate raised while evaluating inside the dispatched tool — a
            // user tool body's `$(…)` — surfaces as this call's own held
            // result, and must not strand in the slot for the next serialized
            // call to mis-take.
            Ok(result)
        };
        let result = self.run_under_watchdog(timeout, &cancel, work).await?;
        self.update_last_result(&result).await;
        Ok(result)
    }

    /// Run `work` under the movable-deadline watchdog for `timeout`, shared by the
    /// string door ([`Self::execute_with_options`]) and the argv door
    /// ([`Self::execute_argv`]).
    ///
    /// Mirrors the watchdog into `exec_ctx` (so a builtin can suspend the script
    /// clock via `ctx.patient`), and when a timeout is set, spawns the watchdog
    /// racing `cancel` — on an elapsed deadline `cancel` fires (cascading
    /// SIGTERM/SIGKILL to external children via `wait_or_kill`) and the result's
    /// code becomes 124. With `timeout == None`, runs `work` directly. Clears the
    /// watchdog handle from `exec_ctx` on the way out (a patient hold against a
    /// stale handle would silently suspend nothing). Callers must short-circuit a
    /// `Some(Duration::ZERO)` timeout (return 124 without spawning) before calling.
    async fn run_under_watchdog<F>(
        &self,
        timeout: Option<Duration>,
        cancel: &tokio_util::sync::CancellationToken,
        work: F,
    ) -> Result<ExecResult>
    where
        F: std::future::Future<Output = Result<ExecResult>>,
    {
        // Assigned unconditionally (clearing any stale handle); None without a timeout.
        let watchdog = timeout.map(|d| Arc::new(crate::watchdog::Watchdog::new(d)));
        {
            let mut ec = self.exec_ctx.write().await;
            ec.watchdog = watchdog.clone();
        }

        let result = if let Some(d) = timeout {
            #[allow(clippy::expect_used)]
            let watchdog = watchdog.clone().expect("watchdog constructed when timeout is set");
            let elapsed = Arc::new(std::sync::atomic::AtomicBool::new(false));
            let timer = tokio::spawn(watchdog.run(elapsed.clone(), cancel.clone()));
            let r = work.await;
            timer.abort();
            match r {
                Ok(mut res) => {
                    if elapsed.load(std::sync::atomic::Ordering::SeqCst) {
                        res.code = 124;
                        if res.err.is_empty() {
                            res.err =
                                ExecResult::terminate_diagnostic(format!("timeout: timed out after {:?}", d));
                        }
                    }
                    Ok(res)
                }
                Err(e) => Err(e),
            }
        } else {
            work.await
        };

        // The timer task is gone (fired or aborted); drop the stale handle.
        {
            let mut ec = self.exec_ctx.write().await;
            ec.watchdog = None;
        }
        result
    }

    /// Execute with per-call options. The primary entry point for embedders
    /// that don't need per-statement output streaming.
    ///
    /// `opts` carries timeout, transient vars overlay, optional cwd override,
    /// and optional embedder-owned cancellation token. See [`ExecuteOptions`]
    /// for semantics. For streaming, use [`Self::execute_with_options_streaming`].
    ///
    /// **Cancellation:** if `opts.cancel_token` is `Some`, it is *raced*
    /// against the kernel's internal token. Either firing cancels and kills
    /// external children. The embedder's token is read-only — kernel
    /// timeouts do NOT propagate into it. Distinguish via the returned
    /// `code`: 124 = timeout, 130 = cancellation.
    ///
    /// **Timeout:** `opts.timeout` overrides `KernelConfig::request_timeout`.
    /// `Some(Duration::ZERO)` returns 124 immediately without spawning.
    ///
    /// Concurrent callers on the same Kernel serialize on the kernel-wide
    /// execute lock. For true parallelism, call [`Kernel::fork`] (detached)
    /// or [`Kernel::fork_attached`] (cancellation cascades from this kernel).
    ///
    /// # Errors
    ///
    /// Returns [`KernelError`] when the program was rejected before running
    /// or faulted while running — see [`KernelError::is_rejected`].
    pub async fn execute_with_options(
        &self,
        input: &str,
        opts: ExecuteOptions,
    ) -> Result<ExecResult, KernelError> {
        self.run_inner(input, opts, None, None).await.map_err(classify_execute_error)
    }

    /// Same as [`Self::execute_with_options`] but with a per-statement output
    /// callback. The callback fires after each top-level statement so the
    /// embedder (REPL, MCP streaming) can flush output incrementally.
    ///
    /// # Errors
    ///
    /// See [`Self::execute_with_options`].
    pub async fn execute_with_options_streaming(
        &self,
        input: &str,
        opts: ExecuteOptions,
        on_output: &mut (dyn FnMut(&ExecResult) + Send),
    ) -> Result<ExecResult, KernelError> {
        self.run_inner(input, opts, None, Some(on_output)).await.map_err(classify_execute_error)
    }

    /// Execute with a **lazy** standard input fed as a [`PipeReader`](crate::PipeReader).
    ///
    /// Unlike [`ExecuteOptions::with_stdin`] (a pre-read buffer), this never
    /// forces the input to be drained before execution: the reader seeds the
    /// first top-level command's `pipe_stdin`, and a command that does not read
    /// stdin (`echo`) returns without touching it. This is the seam a
    /// non-interactive frontend uses to forward an *open* process stdin without
    /// hanging on a pipe that never sends EOF (`sleep 10 | kaish -c 'echo hi'`).
    ///
    /// Embedders that already hold a complete buffer (text or binary) should
    /// prefer the simpler [`ExecuteOptions::with_stdin`] path instead.
    ///
    /// # Errors
    ///
    /// See [`Self::execute_with_options`].
    pub async fn execute_with_pipe_stdin(
        &self,
        input: &str,
        opts: ExecuteOptions,
        pipe_stdin: crate::scheduler::PipeReader,
    ) -> Result<ExecResult, KernelError> {
        self.run_inner(input, opts, Some(pipe_stdin), None).await.map_err(classify_execute_error)
    }

    /// Streaming counterpart to [`Self::execute_with_pipe_stdin`] — the REPL
    /// `-c`/script frontend uses this to print output incrementally while
    /// feeding a lazy process-stdin pipe.
    ///
    /// # Errors
    ///
    /// See [`Self::execute_with_options`].
    pub async fn execute_with_pipe_stdin_streaming(
        &self,
        input: &str,
        opts: ExecuteOptions,
        pipe_stdin: crate::scheduler::PipeReader,
        on_output: &mut (dyn FnMut(&ExecResult) + Send),
    ) -> Result<ExecResult, KernelError> {
        self.run_inner(input, opts, Some(pipe_stdin), Some(on_output))
            .await
            .map_err(classify_execute_error)
    }

    /// Execute kaish source code with a transient overlay of exported variables.
    ///
    /// Deprecated thin wrapper over [`Self::execute_with_options`]. New code
    /// should use that method directly:
    /// `execute_with_options(input, ExecuteOptions::new().with_vars(vars))`.
    #[deprecated(note = "use Kernel::execute_with_options with ExecuteOptions::with_vars")]
    pub async fn execute_with_vars(
        &self,
        input: &str,
        vars: HashMap<String, Value>,
    ) -> Result<ExecResult, KernelError> {
        self.run_inner(input, ExecuteOptions::new().with_vars(vars), None, None)
            .await
            .map_err(classify_execute_error)
    }

    /// Execute kaish source code with a per-statement callback.
    ///
    /// Deprecated thin wrapper. New code should use
    /// [`Self::execute_with_options_streaming`].
    #[deprecated(note = "use Kernel::execute_with_options_streaming")]
    pub async fn execute_streaming(
        &self,
        input: &str,
        on_output: &mut (dyn FnMut(&ExecResult) + Send),
    ) -> Result<ExecResult, KernelError> {
        self.run_inner(input, ExecuteOptions::default(), None, Some(on_output))
            .await
            .map_err(classify_execute_error)
    }

    /// Link embedder trace context, then run [`Self::execute_with_options_inner`].
    ///
    /// The `#[instrument]` execution span resolves its parent from the *current*
    /// OpenTelemetry context (see `tracing-opentelemetry`'s `parent_context`),
    /// captured when the span is first entered — not when the future is
    /// constructed. So a thread-local `attach()` scoped to construction is too
    /// early to be seen (the integration test confirms this). `with_context`
    /// re-attaches the embedder's context on *every* poll of the inner future,
    /// so the context is current at first-enter and survives runtime thread
    /// hops. With no embedder trace context, the future runs unwrapped.
    async fn run_inner(
        &self,
        input: &str,
        opts: ExecuteOptions,
        pipe_stdin: Option<crate::scheduler::PipeReader>,
        on_output: Option<&mut (dyn FnMut(&ExecResult) + Send)>,
    ) -> Result<ExecResult> {
        use opentelemetry::context::FutureExt;

        // Capture the embedder's baggage before `opts` is consumed so it can be
        // echoed back onto the result on egress (see `merge_egress_baggage`).
        let embedder_baggage = opts.baggage.clone();

        let result = match crate::telemetry::extract_parent(&opts) {
            Some(parent) => self
                .execute_with_options_inner(input, opts, pipe_stdin, on_output)
                .with_context(parent)
                .await,
            None => self.execute_with_options_inner(input, opts, pipe_stdin, on_output).await,
        };

        result.map(|mut r| {
            crate::telemetry::merge_egress_baggage(&mut r, embedder_baggage);
            r
        })
    }

    /// Shared body for `execute`, `execute_with_options(_streaming)`, and
    /// the deprecated wrappers. Owns the per-call cancel token, vars overlay,
    /// cwd override, and timeout race.
    #[tracing::instrument(level = "info", skip(self, opts, pipe_stdin, on_output), fields(input_len = input.len()))]
    async fn execute_with_options_inner(
        &self,
        input: &str,
        opts: ExecuteOptions,
        pipe_stdin: Option<crate::scheduler::PipeReader>,
        on_output: Option<&mut (dyn FnMut(&ExecResult) + Send)>,
    ) -> Result<ExecResult> {
        let _guard = self.acquire_execute_lock().await;

        // Always reset to a fresh internal token; this is the kernel's own
        // cancel surface for embedders calling `Kernel::cancel()`. The
        // embedder-supplied `opts.cancel_token` is a *read-only input* — it
        // is NOT written into `self.cancel_token`, because doing so would
        // (a) leak the embedder's token past this call's lifetime,
        // (b) re-route a later `Kernel::cancel()` into the embedder's token,
        // (c) extend the token's lifetime via the kernel's strong clone.
        let internal = self.reset_cancel();

        // Install the per-call polled interrupt for `is_cancelled()` to
        // consult. The guard clears it on every exit path — a stale check
        // must not outlive its call and fire into a later one.
        struct ClearInterrupt<'a>(&'a Kernel);
        impl Drop for ClearInterrupt<'_> {
            fn drop(&mut self) {
                if let Ok(mut slot) = self.0.interrupt.lock() {
                    *slot = None;
                }
            }
        }
        {
            #[allow(clippy::expect_used)]
            let mut slot = self.interrupt.lock().expect("interrupt poisoned");
            *slot = opts.interrupt.clone();
        }
        let _interrupt_guard = ClearInterrupt(self);

        // Race the embedder token against the kernel's internal token via a
        // tracked watcher task. We hold the JoinHandle so we can abort the
        // task at function exit — otherwise it would wait forever for either
        // token to fire and leak per call.
        let (effective_cancel, watcher_handle): (
            tokio_util::sync::CancellationToken,
            Option<tokio::task::JoinHandle<()>>,
        ) = if let Some(ext) = opts.cancel_token {
            let combined = tokio_util::sync::CancellationToken::new();
            let combined_writer = combined.clone();
            let i = internal.clone();
            let handle = tokio::spawn(async move {
                tokio::select! {
                    _ = i.cancelled() => combined_writer.cancel(),
                    _ = ext.cancelled() => combined_writer.cancel(),
                }
            });
            (combined, Some(handle))
        } else {
            (internal, None)
        };

        // Effective timeout: per-call wins over kernel-config default.
        let timeout = opts.timeout.or(self.request_timeout);

        // ZERO timeout: return 124 immediately without spawning anything.
        if timeout == Some(Duration::ZERO) {
            if let Some(h) = watcher_handle {
                h.abort();
            }
            return Ok(ExecResult::failure(124, "timeout: timed out after 0s".to_string()));
        }

        // Apply per-call vars overlay (push frame + set_exported), wrapped in
        // an RAII guard so a panic inside `execute_streaming_inner` still
        // pops the frame and unexports the temporarily-exported names.
        struct VarsFrameGuard<'a> {
            kernel: &'a Kernel,
            newly_exported: Vec<String>,
        }
        impl Drop for VarsFrameGuard<'_> {
            fn drop(&mut self) {
                // Best-effort cleanup using try_write. The execute_lock held
                // throughout execute_with_options means there is no concurrent
                // foreground caller; forks have their own scope and won't
                // block this. blocking_write would deadlock the runtime when
                // called from a tokio worker thread, so we explicitly do NOT
                // fall back to it — if try_write fails (which we've never
                // seen in practice), log loudly and accept the leak rather
                // than deadlock the entire kernel.
                let Ok(mut scope) = self.kernel.scope.try_write() else {
                    tracing::error!(
                        "vars frame guard: scope lock unexpectedly busy; \
                         skipping pop_frame to avoid runtime deadlock — \
                         transient vars may leak"
                    );
                    return;
                };
                scope.pop_frame();
                for name in self.newly_exported.drain(..) {
                    scope.unexport(&name);
                }
            }
        }

        // Per-call cwd override: save current cwd, set the new one, restore
        // on Drop so the kernel's persistent cwd doesn't leak between calls.
        // Same RAII pattern as VarsFrameGuard, same blocking_write trade-off.
        struct CwdGuard<'a> {
            kernel: &'a Kernel,
            saved: PathBuf,
        }
        impl Drop for CwdGuard<'_> {
            fn drop(&mut self) {
                let Ok(mut ec) = self.kernel.exec_ctx.try_write() else {
                    tracing::error!(
                        "cwd guard: exec_ctx lock unexpectedly busy; \
                         skipping cwd restore — kernel cwd may be wrong for next call"
                    );
                    return;
                };
                ec.cwd = std::mem::take(&mut self.saved);
            }
        }
        let _cwd_guard: Option<CwdGuard<'_>> = if let Some(new_cwd) = opts.cwd {
            let mut ec = self.exec_ctx.write().await;
            let saved = std::mem::replace(&mut ec.cwd, new_cwd);
            drop(ec);
            Some(CwdGuard { kernel: self, saved })
        } else {
            None
        };

        // Per-call stdin: seed the persistent exec_ctx so the first top-level
        // command that reads stdin consumes it (it's `take()`n at dispatch).
        // Restore the prior value on Drop — normally `None`, so this also drops
        // any residual seed an stdin-less program never consumed, keeping it
        // from bleeding into the next call. Same RAII pattern as CwdGuard.
        struct StdinGuard<'a> {
            kernel: &'a Kernel,
            saved: Option<Vec<u8>>,
        }
        impl Drop for StdinGuard<'_> {
            fn drop(&mut self) {
                let Ok(mut ec) = self.kernel.exec_ctx.try_write() else {
                    tracing::error!(
                        "stdin guard: exec_ctx lock unexpectedly busy; \
                         skipping stdin restore — stale stdin may leak to next call"
                    );
                    return;
                };
                ec.stdin = self.saved.take();
            }
        }
        let _stdin_guard: Option<StdinGuard<'_>> = if let Some(stdin) = opts.stdin {
            let mut ec = self.exec_ctx.write().await;
            let saved = ec.stdin.replace(stdin);
            drop(ec);
            Some(StdinGuard { kernel: self, saved })
        } else {
            None
        };

        // Per-call *lazy* stdin: a frontend-supplied `PipeReader` seeds the
        // persistent exec_ctx so the first stdin-reading command drains it (it's
        // `take()`n at pipeline build). The RAII guard restores the prior value
        // on Drop (normally `None`), so an unread reader doesn't bleed into the
        // next call. Mirrors `StdinGuard`; the reader is non-Clone, so it moves.
        struct PipeStdinGuard<'a> {
            kernel: &'a Kernel,
            saved: Option<crate::scheduler::PipeReader>,
        }
        impl Drop for PipeStdinGuard<'_> {
            fn drop(&mut self) {
                let Ok(mut ec) = self.kernel.exec_ctx.try_write() else {
                    tracing::error!(
                        "pipe stdin guard: exec_ctx lock unexpectedly busy; \
                         skipping restore — stale pipe stdin may leak to next call"
                    );
                    return;
                };
                ec.pipe_stdin = self.saved.take();
            }
        }
        let _pipe_stdin_guard: Option<PipeStdinGuard<'_>> = if let Some(reader) = pipe_stdin {
            let mut ec = self.exec_ctx.write().await;
            let saved = ec.pipe_stdin.replace(reader);
            drop(ec);
            Some(PipeStdinGuard { kernel: self, saved })
        } else {
            None
        };

        let _vars_guard: Option<VarsFrameGuard<'_>> = if !opts.vars.is_empty() {
            let mut scope = self.scope.write().await;
            scope.push_frame();
            let mut newly = Vec::with_capacity(opts.vars.len());
            for (name, value) in opts.vars {
                if !scope.is_exported(&name) {
                    newly.push(name.clone());
                }
                scope.set_exported(name, value);
            }
            drop(scope);
            Some(VarsFrameGuard { kernel: self, newly_exported: newly })
        } else {
            None
        };

        // Per-call errexit override (`ExecuteOptions::errexit`): save the
        // kernel's current errexit state, apply the override, restore the
        // saved value on Drop so it doesn't leak into the next call. `None`
        // leaves errexit exactly as the kernel already has it — no save, no
        // restore. Same RAII pattern as CwdGuard/StdinGuard.
        struct ErrexitGuard<'a> {
            kernel: &'a Kernel,
            saved: bool,
        }
        impl Drop for ErrexitGuard<'_> {
            fn drop(&mut self) {
                let Ok(mut scope) = self.kernel.scope.try_write() else {
                    tracing::error!(
                        "errexit guard: scope lock unexpectedly busy; \
                         skipping errexit restore — override may leak to next call"
                    );
                    return;
                };
                scope.set_error_exit(self.saved);
            }
        }
        let _errexit_guard: Option<ErrexitGuard<'_>> = if let Some(enabled) = opts.errexit {
            let mut scope = self.scope.write().await;
            // The RAW flag, not `error_exit_enabled()`: that one is false
            // while errexit is suppressed inside a `&&`/`||` left side, and
            // restoring from it would turn `set -e` off for good.
            let saved = scope.error_exit_flag();
            scope.set_error_exit(enabled);
            drop(scope);
            Some(ErrexitGuard { kernel: self, saved })
        } else {
            None
        };

        // Sync the effective cancel into self.exec_ctx so try_execute_external
        // (which reads via self.cancel_token) sees cancellation. We also need
        // builtins to see it via ctx.cancel — handled in execute_command.
        // For simplicity here we mirror effective_cancel into self.cancel_token
        // for the duration of this call, then restore the internal token at
        // the end (so a later Kernel::cancel still hits our internal surface).
        {
            #[allow(clippy::expect_used)]
            let mut cur = self.cancel_token.lock().expect("cancel_token poisoned");
            *cur = effective_cancel.clone();
        }

        // Run the script under the movable-deadline watchdog (shared with the
        // argv door). The watchdog task cancels `effective_cancel` on an elapsed
        // deadline; the cascade fires SIGTERM/SIGKILL on any external children via
        // the wait_or_kill discipline in try_execute_external. `Some(ZERO)` was
        // already handled by the early return above.
        let mut noop_cb: Box<dyn FnMut(&ExecResult) + Send> = Box::new(|_| {});
        let cb_ref: &mut (dyn FnMut(&ExecResult) + Send) = match on_output {
            Some(cb) => cb,
            None => &mut *noop_cb,
        };

        let result = self
            .run_under_watchdog(timeout, &effective_cancel, self.execute_streaming_inner(input, cb_ref))
            .await;

        // Restore self.cancel_token to a fresh, uncancelled token so the
        // embedder's view of `Kernel::cancel()` stays predictable on the
        // next call (it cancels the kernel's own token, not whatever was
        // left over from this call's combined token).
        {
            #[allow(clippy::expect_used)]
            let mut cur = self.cancel_token.lock().expect("cancel_token poisoned");
            *cur = tokio_util::sync::CancellationToken::new();
        }

        // Tear down the embedder-token race watcher (if any). Leaving it
        // alive would idle forever waiting for tokens that may never fire.
        if let Some(h) = watcher_handle {
            h.abort();
        }

        // VarsFrameGuard drops here on the success path and on early-return
        // paths above (error path included). Panic safety preserved.
        result
    }

    /// The actual body of `execute_streaming`, run while holding the execute lock.
    ///
    /// Split out so internal kernel paths that are already under the lock can
    /// call this without deadlocking on re-entry. External callers must go
    /// through [`Self::execute_streaming`] so they acquire the lock.
    async fn execute_streaming_inner(
        &self,
        input: &str,
        on_output: &mut (dyn FnMut(&ExecResult) + Send),
    ) -> Result<ExecResult> {
        let program = parse(input).map_err(|errors| {
            let msg = errors
                .iter()
                .map(|e| e.format(input))
                .collect::<Vec<_>>()
                .join("\n");
            let message = format!("parse error:\n{}", msg);
            // Tagged so `classify_execute_error` can recover the structured
            // rejection at the public execute-surface boundary; every other
            // `?` in this function propagates a plain, untagged `anyhow::Error`.
            anyhow::Error::from(KernelError::Parse { errors, message })
        })?;

        // AST display mode: show AST instead of executing
        {
            let scope = self.scope.read().await;
            if scope.show_ast() {
                let output = format!("{:#?}\n", program);
                return Ok(ExecResult::with_output(crate::interpreter::OutputData::text(output)));
            }
        }

        // Pre-execution validation. Most warnings stay trace-only (every
        // external command fires an `UndefinedCommand` warning), but a warning
        // whose code opts into agent surfacing is collected here and prepended
        // to the result's stderr at each return point below.
        let mut surfaced_warnings = String::new();
        if !self.skip_validation {
            // Catalog first: neither guard should ride the other's await, and
            // `validate()` is synchronous, so neither rides one after this.
            let catalog = { self.exec_ctx.read().await.tool_schemas.clone() };
            let user_tools = self.user_tools.read().await;
            let validator = Validator::new(&self.tools, &user_tools, &catalog);
            let issues = validator.validate(&program);

            // Collect errors (warnings are logged but don't prevent execution)
            let errors: Vec<_> = issues
                .iter()
                .filter(|i| i.severity == Severity::Error)
                .collect();

            if !errors.is_empty() {
                let error_msg = errors
                    .iter()
                    .map(|e| e.format(input))
                    .collect::<Vec<_>>()
                    .join("\n");
                let message = format!("validation failed:\n{}", error_msg);
                let issues: Vec<crate::validator::ValidationIssue> =
                    errors.into_iter().cloned().collect();
                // Tagged the same way as the parse rejection above.
                return Err(anyhow::Error::from(KernelError::Validation { issues, message }));
            }

            // Log warnings via tracing (trace level to avoid noise); surface the
            // opted-in ones to the agent so the guidance is actually seen.
            for warning in issues.iter().filter(|i| i.severity == Severity::Warning) {
                tracing::trace!("validation: {}", warning.format(input));
                if warning.code.surfaces_to_agent() {
                    surfaced_warnings.push_str(&warning.format(input));
                    surfaced_warnings.push('\n');
                }
            }
        }

        // Surface opted-in validation warnings to the streaming frontend once,
        // before any command output. The streaming consumer (`-c`, REPL) prints
        // per `on_output` and ignores the returned aggregate err; non-streaming
        // callers (`kernel.execute`) use a noop callback and read the aggregate
        // `result.err` (prepended at each return below). The two paths are
        // disjoint, so this prints the advisory exactly once on each.
        if !surfaced_warnings.is_empty() {
            let mut advisory = ExecResult::success("");
            advisory.err = surfaced_warnings.clone();
            on_output(&advisory);
        }

        let mut result = ExecResult::success("");

        // Reset cancellation token for this execution.
        let cancel = self.reset_cancel();

        for stmt in program.statements.into_iter() {
            if matches!(stmt, Stmt::Empty) {
                continue;
            }

            // Cancellation checkpoint
            if cancel.is_cancelled() {
                result.code = 130;
                return Ok(result);
            }

            // The statement tap and gate (spec §C.6) — one of exactly two
            // sites. It runs before `execute_stmt_flow`, so a held statement
            // has run *nothing*: no substitution, no redirect opened, no
            let flow_result = self.execute_stmt_flow(&stmt).await;
            let flow = flow_result?;

            // Drain any stderr written by pipeline stages during this statement.
            // This captures stderr from intermediate pipeline stages that would
            // otherwise be lost (only the last stage's result is returned).
            let drained_stderr = {
                let mut receiver = self.stderr_receiver.lock().await;
                receiver.drain_lossy()
            };

            match flow {
                ControlFlow::Normal(mut r) => {
                    if !drained_stderr.is_empty() {
                        if !r.err.is_empty() && !r.err.ends_with('\n') {
                            r.err.push('\n');
                        }
                        // Prepend pipeline stderr before the last stage's stderr
                        let combined = format!("{}{}", drained_stderr, r.err);
                        r.err = combined;
                    }
                    on_output(&r);
                    // Carry the last statement's structured output for MCP TOON encoding.
                    // Must be done here (not in accumulate_result) because accumulate_result
                    // is also used in loops where per-iteration output would be wrong.
                    let last_output = r.output().cloned();
                    accumulate_result(&mut result, &r);
                    result.set_output(last_output);
                }
                ControlFlow::Exit { code, result: carried } => {
                    if !drained_stderr.is_empty() {
                        result.err.push_str(&drained_stderr);
                    }
                    // Output produced before the exit — e.g. by the loop the
                    // `exit` ran inside — arrives on the signal. Emit it like
                    // any other statement's, then let `code` decide the status.
                    on_output(&carried);
                    accumulate_result(&mut result, &carried);
                    result.code = code;
                    if !surfaced_warnings.is_empty() {
                        result.err = format!("{surfaced_warnings}{}", result.err);
                    }
                    return Ok(result);
                }
                ControlFlow::Return { mut value } => {
                    if !drained_stderr.is_empty() {
                        value.err = format!("{}{}", drained_stderr, value.err);
                    }
                    on_output(&value);
                    // A top-level `return` stops the script, like `exit` —
                    // it must not discard prior statements' accumulated
                    // output nor let execution continue past it.
                    accumulate_result(&mut result, &value);
                    if !surfaced_warnings.is_empty() {
                        result.err = format!("{surfaced_warnings}{}", result.err);
                    }
                    return Ok(result);
                }
                ControlFlow::Break { result: mut r, .. } | ControlFlow::Continue { result: mut r, .. } => {
                    if !drained_stderr.is_empty() {
                        r.err = format!("{}{}", drained_stderr, r.err);
                    }
                    on_output(&r);
                    accumulate_result(&mut result, &r);
                }
            }
        }

        if !surfaced_warnings.is_empty() {
            result.err = format!("{surfaced_warnings}{}", result.err);
        }
        Ok(result)
    }

    /// Execute a single statement, returning control flow information.
    fn execute_stmt_flow<'a>(
        &'a self,
        stmt: &'a Stmt,
    ) -> std::pin::Pin<Box<dyn std::future::Future<Output = Result<ControlFlow>> + Send + 'a>> {
        // No per-statement span here: `execute_stmt_flow` is the largest future
        // on the recursion ring, and wrapping it in `Instrumented<Span>` carries
        // the span's state through every `.await` at every level, costing native
        // stack per level (GH #48). Coarser spans on the outer execute entries
        // remain. See item 3 of the #48 burndown.
        Box::pin(async move {
        match stmt {
            Stmt::Assignment(assign) => {
                // An assignment with no command name takes the exit status of
                // the last command substitution in its value, or 0 if there
                // was none (bash's rule, re-probed). Clear the note first so
                // a substitution from an earlier statement cannot leak in —
                // `false; x=5` must be 0, not stale.
                {
                    let mut scope = self.scope.write().await;
                    scope.clear_cmdsubst_code();
                }
                // Use async evaluator to support command substitution
                let value = self.eval_expr_async(&assign.value).await
                    .context("failed to evaluate assignment")?;
                let mut scope = self.scope.write().await;
                if assign.path.segments.len() == 1 {
                    // Plain `NAME=value` — no subscript, so `local` applies.
                    if assign.local {
                        // local: set in innermost (current function) frame
                        scope.set(assign.name(), value.clone());
                    } else {
                        // non-local: update existing or create in root frame
                        scope.set_global(assign.name(), value.clone());
                    }
                } else {
                    // Subscripted lvalue (`xs[0]=v`, `user[email]=v`, …): always
                    // mutates the existing root wherever it lives, so `local`
                    // has nothing to declare. See docs/LANGUAGE.md,
                    // "Assignment — bracket-path lvalues".
                    scope.walk_write(&assign.path, value.clone()).map_err(|e| match e {
                        PathError::UndefinedRoot(name) => anyhow::anyhow!(
                            "{name}: undefined — create it first, e.g. `{name}={{}}` or `{name}=[]`"
                        ),
                        PathError::Absence(msg) | PathError::Shape(msg) => anyhow::anyhow!(msg),
                    })?;
                }
                drop(scope);

                // Assignments don't produce output (like sh), but they are a
                // command: they write `$?` and honor `set -e` (bash: `set -e;
                // x=$(false)` exits). The code is the last substitution's, or
                // 0 — this is what lets `x="$(cmd)" || x="FALLBACK"` fire.
                let subst_code = {
                    let mut scope = self.scope.write().await;
                    scope.take_cmdsubst_code()
                };
                let result = match subst_code {
                    None | Some(0) => ExecResult::success(""),
                    Some(code) => ExecResult::failure(code, ""),
                };
                self.update_last_result(&result).await;
                if !result.ok() {
                    let scope = self.scope.read().await;
                    if scope.error_exit_enabled() {
                        // `-e` aborts the statement list, but the reason the
                        // command died must survive with it — carry `result`
                        // (its `out`/`err`/`data`) into the Exit signal instead
                        // of `ControlFlow::exit_code`'s empty placeholder.
                        let code = result.code;
                        return Ok(ControlFlow::Exit { code, result });
                    }
                }
                Ok(ControlFlow::ok(result))
            }
            Stmt::Command(cmd) => {
                // Route single commands through execute_pipeline for a unified path.
                // This ensures all commands go through the dispatcher chain.
                let pipeline = crate::ast::Pipeline {
                    stages: vec![crate::ast::PipelineStage::Command(cmd.clone())],
                    background: false,
                };
                let result = Box::pin(self.execute_pipeline(&pipeline)).await?;
                self.update_last_result(&result).await;

                // Check for error exit mode (set -e)
                if !result.ok() {
                    let scope = self.scope.read().await;
                    if scope.error_exit_enabled() {
                        // `-e` aborts the statement list, but the reason the
                        // command died must survive with it — carry `result`
                        // (its `out`/`err`/`data`) into the Exit signal instead
                        // of `ControlFlow::exit_code`'s empty placeholder.
                        let code = result.code;
                        return Ok(ControlFlow::Exit { code, result });
                    }
                }

                Ok(ControlFlow::ok(result))
            }
            Stmt::Pipeline(pipeline) => {
                let result = Box::pin(self.execute_pipeline(pipeline)).await?;
                self.update_last_result(&result).await;

                // Check for error exit mode (set -e)
                if !result.ok() {
                    let scope = self.scope.read().await;
                    if scope.error_exit_enabled() {
                        // `-e` aborts the statement list, but the reason the
                        // command died must survive with it — carry `result`
                        // (its `out`/`err`/`data`) into the Exit signal instead
                        // of `ControlFlow::exit_code`'s empty placeholder.
                        let code = result.code;
                        return Ok(ControlFlow::Exit { code, result });
                    }
                }

                Ok(ControlFlow::ok(result))
            }
            Stmt::If(if_stmt) => {
                // The statement's result is built BEFORE the condition runs,
                // because a condition's own stdout is the first thing in it —
                // see `eval_condition_async`. (An `elif` is a nested `Stmt::If`
                // in `else_branch`, so it takes this same path.)
                let mut result = ExecResult::success("");
                let cond_value = self
                    .eval_condition_async(&if_stmt.condition, &mut result)
                    .await?;

                let branch = if is_truthy(&cond_value) {
                    &if_stmt.then_branch
                } else {
                    if_stmt.else_branch.as_deref().unwrap_or(&[])
                };

                for stmt in branch {
                    let flow = self.execute_stmt_flow(stmt).await?;
                    match flow {
                        ControlFlow::Normal(r) => {
                            // Drain BEFORE accumulating, as the `while` arm
                            // does: the stream holds the condition's stderr,
                            // which was written first and must read first.
                            // Appending `r.err` ahead of the drain put the
                            // branch's diagnostic before the condition's.
                            self.drain_stderr_into(&mut result).await;
                            accumulate_result(&mut result, &r);
                        }
                        mut other => {
                            self.drain_stderr_into(&mut result).await;
                            fold_block_output_into_flow(std::mem::take(&mut result), &mut other);
                            return Ok(other);
                        }
                    }
                }
                // A compound statement is a command: it writes `$?` whether or
                // not a body statement ran. Without this, `if false; then …; fi`
                // leaves the PREVIOUS statement's status visible to `$?` — a
                // failure that did not happen. Idempotent when a body did run:
                // the body's own arm already wrote the same code.
                self.update_last_result(&result).await;
                Ok(ControlFlow::ok(result))
            }
            Stmt::For(for_loop) => {
                // Evaluate all items and collect values for iteration
                // Use async evaluator to support command substitution like $(seq 1 5)
                let mut items: Vec<Value> = Vec::new();
                for item_expr in &for_loop.items {
                    // Glob expansion in for-loop items: `for f in *.txt`
                    if let Expr::GlobPattern(pattern) = item_expr {
                        let glob_enabled = {
                            let scope = self.scope.read().await;
                            scope.glob_enabled()
                        };
                        if glob_enabled {
                            let (paths, cwd) = {
                                let ctx = self.exec_ctx.read().await;
                                let paths = ctx.expand_glob(pattern).await
                                    .map_err(|e| anyhow::anyhow!("glob: {}", e))?;
                                let cwd = ctx.resolve_path(".");
                                (paths, cwd)
                            };
                            if paths.is_empty() {
                                return Err(anyhow::anyhow!("no matches: {}", pattern));
                            }
                            for path in paths {
                                let display = if !pattern.starts_with('/') {
                                    path.strip_prefix(&cwd)
                                        .unwrap_or(&path)
                                        .to_string_lossy().into_owned()
                                } else {
                                    path.to_string_lossy().into_owned()
                                };
                                items.push(Value::String(display));
                            }
                            continue;
                        }
                    }
                    // Track whether this item came from $(cmd); that's the
                    // only position where multi-line stdout auto-splits per
                    // line. Arrays still spread element-by-element; bare
                    // $VAR is rejected upstream by validator E012. See
                    // docs/LANGUAGE.md.
                    let from_command_subst = matches!(item_expr, Expr::CommandSubst(_));
                    let item = self.eval_expr_async(item_expr).await?;
                    match item {
                        // JSON arrays iterate over elements (preferred path
                        // when builtins emit .data — seq, jq, cut, find, …)
                        Value::Json(serde_json::Value::Array(arr)) => {
                            for elem in arr {
                                // Envelope-free: an element that happens to be
                                // envelope-shaped (e.g. from `fromjson`) is
                                // external data, not an internal bytes round-trip,
                                // so it must NOT be re-decoded to Value::Bytes.
                                items.push(json_to_value_no_envelope(elem));
                            }
                        }
                        // Strings from $(cmd): empty → 0 iterations,
                        // multi-line → split per line (trimming trailing
                        // newlines and per-line trailing \r), single-line
                        // → one iteration. Whitespace within a line is
                        // NOT split — the "$VAR with spaces just works"
                        // promise is preserved because this only fires
                        // in CommandSubst position.
                        Value::String(s) if from_command_subst => {
                            let trimmed = s.trim_end_matches(['\n', '\r']);
                            if trimmed.is_empty() {
                                continue;
                            }
                            if trimmed.contains('\n') {
                                for line in trimmed.split('\n') {
                                    let line = line.trim_end_matches('\r');
                                    items.push(Value::String(line.to_string()));
                                }
                            } else {
                                items.push(Value::String(trimmed.to_string()));
                            }
                        }
                        // Binary isn't iterable — fail loud rather than loop
                        // once over an opaque byte blob.
                        Value::Bytes(_) => {
                            anyhow::bail!(
                                "for: cannot iterate over binary data — decode it \
                                 (base64/xxd) first"
                            );
                        }
                        // Strings not from $(cmd) stay as one value.
                        other => items.push(other),
                    }
                }

                let mut result = ExecResult::success("");
                {
                    let mut scope = self.scope.write().await;
                    scope.push_frame();
                }

                'outer: for item in items {
                    // Cancellation checkpoint per iteration
                    if self.is_cancelled() {
                        {
                            let mut scope = self.scope.write().await;
                            scope.pop_frame();
                        }
                        result.code = 130;
                        self.update_last_result(&result).await;
                        return Ok(ControlFlow::ok(result));
                    }
                    {
                        let mut scope = self.scope.write().await;
                        scope.set(&for_loop.variable, item);
                    }
                    for stmt in &for_loop.body {
                        let mut flow = match self.execute_stmt_flow(stmt).await {
                            Ok(f) => f,
                            Err(e) => {
                                let mut scope = self.scope.write().await;
                                scope.pop_frame();
                                return Err(e);
                            }
                        };
                        self.drain_stderr_into(&mut result).await;
                        match &mut flow {
                            ControlFlow::Normal(r) => {
                                accumulate_result(&mut result, r);
                                if !r.ok() {
                                    let scope = self.scope.read().await;
                                    if scope.error_exit_enabled() {
                                        drop(scope);
                                        let mut scope = self.scope.write().await;
                                        scope.pop_frame();
                                        // `result` already carries `r`'s out/err
                                        // via accumulate_result above — hand it to
                                        // the Exit signal so `-e` still aborts the
                                        // loop but the reason survives.
                                        let code = r.code;
                                        return Ok(ControlFlow::Exit {
                                            code,
                                            result: std::mem::take(&mut result),
                                        });
                                    }
                                }
                            }
                            ControlFlow::Break { .. } => {
                                if flow.decrement_level() {
                                    accumulate_flow_output(&mut result, &flow);
                                    break 'outer;
                                }
                                fold_block_output_into_flow(std::mem::take(&mut result), &mut flow);
                                let mut scope = self.scope.write().await;
                                scope.pop_frame();
                                return Ok(flow);
                            }
                            ControlFlow::Continue { .. } => {
                                if flow.decrement_level() {
                                    accumulate_flow_output(&mut result, &flow);
                                    continue 'outer;
                                }
                                fold_block_output_into_flow(std::mem::take(&mut result), &mut flow);
                                let mut scope = self.scope.write().await;
                                scope.pop_frame();
                                return Ok(flow);
                            }
                            ControlFlow::Return { .. } | ControlFlow::Exit { .. } => {
                                fold_block_output_into_flow(
                                    std::mem::take(&mut result),
                                    &mut flow,
                                );
                                let mut scope = self.scope.write().await;
                                scope.pop_frame();
                                return Ok(flow);
                            }
                        }
                    }
                }

                {
                    let mut scope = self.scope.write().await;
                    scope.pop_frame();
                }
                // Zero iterations still writes `$?` — see the `Stmt::If` arm.
                // `for x in $(grep …)` with no matches must not leave grep's 1
                // standing as the loop's status.
                self.update_last_result(&result).await;
                Ok(ControlFlow::ok(result))
            }
            Stmt::While(while_loop) => {
                let mut result = ExecResult::success("");

                'outer: loop {
                    // Evaluate condition - use async to support command substitution
                    // Cancellation checkpoint per iteration
                    if self.is_cancelled() {
                        result.code = 130;
                        self.update_last_result(&result).await;
                        return Ok(ControlFlow::ok(result));
                    }

                    // Per iteration, so the condition's stdout interleaves with
                    // the body's rather than arriving in one block up front.
                    let cond_value = self
                        .eval_condition_async(&while_loop.condition, &mut result)
                        .await?;

                    if !is_truthy(&cond_value) {
                        break;
                    }

                    // Execute body
                    for stmt in &while_loop.body {
                        let mut flow = self.execute_stmt_flow(stmt).await?;
                        self.drain_stderr_into(&mut result).await;
                        match &mut flow {
                            ControlFlow::Normal(r) => {
                                accumulate_result(&mut result, r);
                                if !r.ok() {
                                    let scope = self.scope.read().await;
                                    if scope.error_exit_enabled() {
                                        // `result` already carries `r`'s out/err
                                        // via accumulate_result above — hand it to
                                        // the Exit signal so `-e` still aborts the
                                        // loop but the reason survives.
                                        let code = r.code;
                                        return Ok(ControlFlow::Exit {
                                            code,
                                            result: std::mem::take(&mut result),
                                        });
                                    }
                                }
                            }
                            ControlFlow::Break { .. } => {
                                if flow.decrement_level() {
                                    accumulate_flow_output(&mut result, &flow);
                                    break 'outer;
                                }
                                fold_block_output_into_flow(std::mem::take(&mut result), &mut flow);
                                return Ok(flow);
                            }
                            ControlFlow::Continue { .. } => {
                                if flow.decrement_level() {
                                    accumulate_flow_output(&mut result, &flow);
                                    continue 'outer;
                                }
                                fold_block_output_into_flow(std::mem::take(&mut result), &mut flow);
                                return Ok(flow);
                            }
                            ControlFlow::Return { .. } | ControlFlow::Exit { .. } => {
                                fold_block_output_into_flow(
                                    std::mem::take(&mut result),
                                    &mut flow,
                                );
                                return Ok(flow);
                            }
                        }
                    }
                }

                // A condition that is false on the first evaluation runs no
                // body — see the `Stmt::If` arm.
                self.update_last_result(&result).await;
                Ok(ControlFlow::ok(result))
            }
            Stmt::Case(case_stmt) => {
                // Evaluate the expression to match against. Text sink: a
                // `case $bin in ...)` pattern match on binary goes loud
                // rather than glob-matching against the `[binary: N bytes]`
                // placeholder (Decision E — same class as `==`/`in`).
                let match_value = {
                    let value = self.eval_expr_async(&case_stmt.expr).await?;
                    value_to_text_sink(&value).map_err(|e| anyhow::anyhow!("{e}"))?
                };

                // Try each branch until we find a match
                for branch in &case_stmt.branches {
                    let matched = branch.patterns.iter().any(|pattern| {
                        glob_match(pattern, &match_value)
                    });

                    if matched {
                        // Execute the branch body
                        let mut result = ExecResult::success("");
                        for stmt in &branch.body {
                            let flow = self.execute_stmt_flow(stmt).await?;
                            match flow {
                                ControlFlow::Normal(r) => {
                                    accumulate_result(&mut result, &r);
                                    self.drain_stderr_into(&mut result).await;
                                }
                                mut other => {
                                    self.drain_stderr_into(&mut result).await;
                                    fold_block_output_into_flow(
                                        std::mem::take(&mut result),
                                        &mut other,
                                    );
                                    return Ok(other);
                                }
                            }
                        }
                        self.update_last_result(&result).await;
                        return Ok(ControlFlow::ok(result));
                    }
                }

                // No match - return success with empty output (like sh), and
                // write it to `$?` — see the `Stmt::If` arm.
                let result = ExecResult::success("");
                self.update_last_result(&result).await;
                Ok(ControlFlow::ok(result))
            }
            Stmt::Break(levels) => {
                Ok(ControlFlow::break_n(levels.unwrap_or(1)))
            }
            Stmt::Continue(levels) => {
                Ok(ControlFlow::continue_n(levels.unwrap_or(1)))
            }
            Stmt::Return(expr) => {
                // return [N] - N becomes the exit code, NOT stdout
                // Shell semantics: return sets exit code, doesn't produce output
                let result = if let Some(e) = expr {
                    let val = self.eval_expr_async(e).await?;
                    let code = crate::interpreter::value_to_exit_code(&val)
                        .map_err(|e| anyhow::anyhow!("return: {}", e))?;
                    ExecResult::from_parts(code, String::new(), String::new(), None)
                } else {
                    ExecResult::success("")
                };
                Ok(ControlFlow::return_value(result))
            }
            Stmt::Exit(expr) => {
                let code = if let Some(e) = expr {
                    let val = self.eval_expr_async(e).await?;
                    crate::interpreter::value_to_exit_code(&val)
                        .map_err(|e| anyhow::anyhow!("exit: {}", e))?
                } else {
                    0
                };
                Ok(ControlFlow::exit_code(code))
            }
            Stmt::ToolDef(tool_def) => {
                let mut user_tools = self.user_tools.write().await;
                user_tools.insert(tool_def.name.clone(), tool_def.clone());
                Ok(ControlFlow::ok(ExecResult::success("")))
            }
            Stmt::AndChain { left, right } => {
                // cmd1 && cmd2 - run cmd2 only if cmd1 succeeds (exit code 0)
                // Suppress errexit for the left side — && handles failure itself.
                {
                    let mut scope = self.scope.write().await;
                    scope.suppress_errexit();
                }
                let left_flow = match self.execute_stmt_flow(left).await {
                    Ok(f) => f,
                    Err(e) => {
                        let mut scope = self.scope.write().await;
                        scope.unsuppress_errexit();
                        return Err(e);
                    }
                };
                {
                    let mut scope = self.scope.write().await;
                    scope.unsuppress_errexit();
                }
                match left_flow {
                    ControlFlow::Normal(mut left_result) => {
                        self.drain_stderr_into(&mut left_result).await;
                        self.update_last_result(&left_result).await;
                        // The left operand is consumed as a boolean to
                        // decide whether the right one runs, and a fault has
                        // no boolean to give. Abort instead of reading it as
                        // failure — a fallback chosen from a comparison that
                        // never happened is a wrong conclusion, not a
                        // recovery. The RIGHT operand is not guarded: its
                        // value becomes the chain's value, so nothing
                        // consumes it as a boolean and it reports exit 2.
                        if left_result.fault {
                            return Err(anyhow::anyhow!("{}", left_result.err.trim_end()));
                        }
                        // Pending is not failure (spec §I.5) — see the
                        // `OrChain` twin. The stash check matters here for a
                        // hold swallowed into an apparent success below.
                        if left_result.ok() {
                            let right_flow = self.execute_stmt_flow(right).await?;
                            match right_flow {
                                ControlFlow::Normal(mut right_result) => {
                                    self.drain_stderr_into(&mut right_result).await;
                                    self.update_last_result(&right_result).await;
                                    let mut combined = left_result;
                                    accumulate_result(&mut combined, &right_result);
                                    Ok(ControlFlow::ok(combined))
                                }
                                mut other => {
                                    // The left side already ran and printed;
                                    // a signal out of the right side must not
                                    // unprint it.
                                    fold_block_output_into_flow(left_result, &mut other);
                                    Ok(other)
                                }
                            }
                        } else {
                            Ok(ControlFlow::ok(left_result))
                        }
                    }
                    _ => Ok(left_flow),
                }
            }
            Stmt::OrChain { left, right } => {
                // cmd1 || cmd2 - run cmd2 only if cmd1 fails (non-zero exit code)
                // Suppress errexit for the left side — || handles failure itself.
                {
                    let mut scope = self.scope.write().await;
                    scope.suppress_errexit();
                }
                let left_flow = match self.execute_stmt_flow(left).await {
                    Ok(f) => f,
                    Err(e) => {
                        let mut scope = self.scope.write().await;
                        scope.unsuppress_errexit();
                        return Err(e);
                    }
                };
                {
                    let mut scope = self.scope.write().await;
                    scope.unsuppress_errexit();
                }
                match left_flow {
                    ControlFlow::Normal(mut left_result) => {
                        self.drain_stderr_into(&mut left_result).await;
                        self.update_last_result(&left_result).await;
                        // The left operand is consumed as a boolean to
                        // decide whether the right one runs, and a fault has
                        // no boolean to give. Abort instead of reading it as
                        // failure — a fallback chosen from a comparison that
                        // never happened is a wrong conclusion, not a
                        // recovery. The RIGHT operand is not guarded: its
                        // value becomes the chain's value, so nothing
                        // consumes it as a boolean and it reports exit 2.
                        if left_result.fault {
                            return Err(anyhow::anyhow!("{}", left_result.err.trim_end()));
                        }
                        // Pending is not failure (spec §I.5): a fallback
                        // written for failure must not run on a decision
                        // nobody has made yet — and running it would also
                        // overwrite the request in the accumulated result.
                        // The stash check covers a hold whose typed error a
                        // layer below already stringified out of the result.
                        // On a stash-based hold the returned `left_result` is
                        // that stringified failure, not the held result — the
                        // statement boundary discards it and surfaces the
                        // slot's result instead. Do not "fix" this by taking
                        // the slot here: only statement boundaries take it.
                        if !left_result.ok() {
                            let right_flow = self.execute_stmt_flow(right).await?;
                            match right_flow {
                                ControlFlow::Normal(mut right_result) => {
                                    self.drain_stderr_into(&mut right_result).await;
                                    self.update_last_result(&right_result).await;
                                    let mut combined = left_result;
                                    accumulate_result(&mut combined, &right_result);
                                    Ok(ControlFlow::ok(combined))
                                }
                                mut other => {
                                    // The left side already ran and printed;
                                    // a signal out of the right side must not
                                    // unprint it.
                                    fold_block_output_into_flow(left_result, &mut other);
                                    Ok(other)
                                }
                            }
                        } else {
                            Ok(ControlFlow::ok(left_result))
                        }
                    }
                    _ => Ok(left_flow), // Propagate non-normal flow
                }
            }
            Stmt::Test(test_expr) => {
                // A type error is a RESULT here, not an escape: exit 2 with
                // the message, matching `(( ))` below and the `test` builtin.
                // Escaping as `Err` collapsed the code to 1, which made a bad
                // operand indistinguishable from a false comparison.
                let result = match self.eval_test_async(test_expr).await {
                    Ok(true) => ExecResult::success(""),
                    Ok(false) => ExecResult::failure(1, ""),
                    Err(e) => ExecResult::failure(2, format!("{e:#}")).into_fault(),
                };
                // A bare test writes `$?` and honors `set -e` like any command
                // (bash: `[[ 1 = 2 ]]; echo $?` → 1). `&&`/`||` operands stay
                // safe: the chain arms suppress errexit around their left side,
                // and `if`/`while` conditions evaluate as expressions, never
                // through this statement arm — so a fault in a CONDITION still
                // aborts, where it has no exit-code channel to report through.
                self.update_last_result(&result).await;
                if !result.ok() {
                    let scope = self.scope.read().await;
                    if scope.error_exit_enabled() {
                        // `-e` aborts the statement list, but the reason the
                        // command died must survive with it — carry `result`
                        // (its `out`/`err`/`data`) into the Exit signal instead
                        // of `ControlFlow::exit_code`'s empty placeholder.
                        let code = result.code;
                        return Ok(ControlFlow::Exit { code, result });
                    }
                }
                Ok(ControlFlow::ok(result))
            }
            // `(( expr ))` — the sibling of `Test` above, and it reports an
            // evaluation fault (division by zero, an unset variable) the same
            // way: exit 2 with the error as the message, like any other
            // command that ran and failed.
            Stmt::Arith(expr_str) => {
                let result = match self.eval_arithmetic_async(expr_str).await {
                    Ok(n) if n != 0 => ExecResult::success(""),
                    Ok(_) => ExecResult::failure(1, ""),
                    Err(e) => ExecResult::failure(2, e.to_string()).into_fault(),
                };
                self.update_last_result(&result).await;
                if !result.ok() {
                    let scope = self.scope.read().await;
                    if scope.error_exit_enabled() {
                        let code = result.code;
                        return Ok(ControlFlow::Exit { code, result });
                    }
                }
                Ok(ControlFlow::ok(result))
            }
            Stmt::EnvScoped { assignments, body } => {
                // Inline env prefix (`NAME=value ... command`): apply the
                // assignments as EXPORTED vars in a fresh frame so the command
                // — and its subprocess environment — sees them, then unwind so
                // they do NOT persist (bash-style command-scoped env). Values
                // evaluate left-to-right with earlier ones already in scope, so
                // `A=1 B=$A cmd` works.
                {
                    let mut scope = self.scope.write().await;
                    scope.push_frame();
                }
                let mut prior_export: Vec<(String, bool)> =
                    Vec::with_capacity(assignments.len());
                let mut setup_err: Option<anyhow::Error> = None;
                for assign in assignments {
                    match self.eval_expr_async(&assign.value).await {
                        Ok(value) => {
                            let mut scope = self.scope.write().await;
                            prior_export
                                .push((assign.name().to_string(), scope.is_exported(assign.name())));
                            scope.set_exported(assign.name(), value);
                        }
                        Err(e) => {
                            setup_err = Some(e);
                            break;
                        }
                    }
                }

                let flow = if setup_err.is_none() {
                    self.execute_stmt_flow(body).await
                } else {
                    Ok(ControlFlow::ok(ExecResult::success("")))
                };

                // Unwind the env frame and restore export marks unconditionally
                // (names that were not exported before must not stay exported).
                {
                    let mut scope = self.scope.write().await;
                    scope.pop_frame();
                    for (name, was_exported) in &prior_export {
                        if !*was_exported {
                            scope.unexport(name);
                        }
                    }
                }

                match setup_err {
                    Some(e) => Err(e),
                    None => flow,
                }
            }
            Stmt::Empty => Ok(ControlFlow::ok(ExecResult::success(""))),
        }
        })
    }

    /// Build a boxed per-command `ExecContext` snapshot from the persistent
    /// kernel state (`ec`/`scope`, both already locked by the caller).
    ///
    /// Sync on purpose: the ~30 field clones live in this transient frame rather
    /// than a coroutine slot, and the result is `Box`ed so only an 8-byte pointer
    /// — not the 960-byte struct — rides the dispatch await at every recursion
    /// level (GH #48, item 2). `pipeline_position` and `cancel` are the only
    /// per-site differences (the pipeline runner uses the kernel's own cancel
    /// token and forces `Only`; the per-command dispatch inherits `ec`'s), so
    /// they're parameters; every other field is snapshotted identically.
    fn snapshot_exec_ctx(
        &self,
        ec: &ExecContext,
        scope: &Scope,
        pipeline_position: PipelinePosition,
        cancel: tokio_util::sync::CancellationToken,
    ) -> Box<ExecContext> {
        Box::new(ExecContext {
            backend: ec.backend.clone(),
            scope: scope.clone(),
            cwd: ec.cwd.clone(),
            prev_cwd: ec.prev_cwd.clone(),
            stdin: ec.stdin.clone(),
            stdin_data: ec.stdin_data.clone(),
            stdin_data_rx: None,
            pipe_stdin: None,
            pipe_stdout: None,
            stderr: ec.stderr.clone(),
            tool_schemas: ec.tool_schemas.clone(),
            tools: ec.tools.clone(),
            job_manager: ec.job_manager.clone(),
            pipeline_position,
            interactive: self.interactive,
            // The kernel-wide setting; a snapshot inherits it like `interactive`.
            kill_children_on_parent_death: ec.kill_children_on_parent_death,
            kill_grace: ec.kill_grace,
            background_job: ec.background_job,
            aliases: ec.aliases.clone(),
            ignore_config: ec.ignore_config.clone(),
            output_limit: ec.output_limit.clone(),
            allow_external_commands: self.allow_external_commands,
            trash_backend: ec.trash_backend.clone(),
            #[cfg(all(unix, feature = "subprocess"))]
            terminal_state: ec.terminal_state.clone(),
            dispatcher: self.dispatcher(),
            cancel,
            output_format: None,
            vfs_budget: self.vfs_budget.clone(),
            watchdog: ec.watchdog.clone(),
            #[cfg(all(feature = "localfs", feature = "overlay"))]
            overlay_handle: self.overlay_handle.clone(),
            // Correlate this command's requests with the background job it
            // runs for, if any — the ONE place `job_id` is stamped.
            // A replay correlation belongs to exactly one dispatch. Moved
            // (not cloned) out of the parent context at the dispatch seam —
            // see the stdin hand-off below, which takes it under the same
            // write lock — so the gate this snapshot reaches is the only one
            // that can adopt it.
            // A forked or backgrounded execution keeps its parenthood: a
            // gate reached from inside a gated statement is nested under it
            // (spec §A.7).
        })
    }

    /// Execute a pipeline.
    async fn execute_pipeline(&self, pipeline: &crate::ast::Pipeline) -> Result<ExecResult> {
        if pipeline.stages.is_empty() {
            return Ok(ExecResult::success(""));
        }

        // Handle background execution (`&` operator)
        if pipeline.background {
            return self.execute_background(pipeline).await;
        }

        // All commands go through the runner with the Kernel as dispatcher.
        // This is the single execution path — no fast path for single commands.
        //
        // IMPORTANT: We snapshot exec_ctx into a local context and release the
        // lock before running. This prevents deadlocks when dispatch_command
        // is called from within the pipeline and recursively triggers another
        // pipeline (e.g., via user-defined tools).
        let (mut ctx, has_pipe_stdin) = {
            let ec = self.exec_ctx.read().await;
            let scope = self.scope.read().await;
            // A frontend-seeded lazy stdin (`execute_with_pipe_stdin`) lives in
            // the persistent exec_ctx; it's moved (non-Clone) into this ctx in
            // the consume-once block below, so note its presence here.
            let has_pipe_stdin = ec.pipe_stdin.is_some();
            // The pipeline runner drives stage 0 with the first stage's stdin
            // seeded from any frontend-supplied input (`ExecuteOptions::stdin`,
            // e.g. `printf … | kaish -c sort`) unless a redirect already set it,
            // and uses the kernel's own cancel token so a `cancel()` reaches the
            // stages. See `snapshot_exec_ctx` for why the snapshot is boxed.
            let cancel = {
                #[allow(clippy::expect_used)]
                let token = self.cancel_token.lock().expect("cancel_token poisoned");
                token.clone()
            };
            (self.snapshot_exec_ctx(&ec, &scope, PipelinePosition::Only, cancel), has_pipe_stdin)
        }; // locks released

        // Consume-once: move/clear the seeded stdin sources from the persistent
        // exec_ctx now that this pipeline's ctx owns them, so a later statement
        // in the same call (`cat ; cat`) does not re-receive them — matching
        // shell stdin draining. `pipe_stdin` is non-Clone, so it's *moved* here
        // (the ctx above was built with `pipe_stdin: None`).
        if ctx.stdin.is_some() || ctx.stdin_data.is_some() || has_pipe_stdin {
            let mut ec = self.exec_ctx.write().await;
            ctx.pipe_stdin = ec.pipe_stdin.take();
            ec.stdin = None;
            ec.stdin_data = None;
        }

        // Park the enclosing command's write end and sideband receiver here for
        // the duration. `ec` is one shared slot and the snapshot above zeroes
        // both, so a nested dispatch — `$(…)` in a command's own arguments, a
        // function body, a `source`d file — overwrites whatever is left in it.
        // `echo $(echo sub) | cat` printed nothing at exit 0;
        // `seq 1 3 | jq -c $(echo .)` fell back to reading the pipe as text.
        //
        // Here rather than at each re-entering caller: this is the one path
        // they all take. The shared slot is the actual defect — threading a
        // ctx through the interpreter would retire this whole dance.
        {
            let mut ec = self.exec_ctx.write().await;
            ctx.pipe_stdout = ec.pipe_stdout.take();
            ctx.stdin_data_rx = ec.stdin_data_rx.take();
        }

        let mut result = self.runner.run(&pipeline.stages, &mut ctx, self).await;

        // `set -o pipefail`: the pipeline answers with the RIGHTMOST non-zero
        // stage, not the first. bash's `set -o pipefail; (exit 3) | (exit 4) |
        // true` is 4, and reading the first non-zero would have said 3.
        //
        // Applied BEFORE the spill contract so a spilled pipeline still reports
        // 3 and keeps the pipefail status as `original_code`, rather than the
        // last stage's — the spill remap is about output size and should
        // override whatever the pipeline decided its status was, not race it.
        //
        // Read back from the scope the runner just wrote rather than threaded
        // separately: PIPESTATUS is the one record of what each stage did, so
        // the mode and the variable cannot disagree about the same pipeline.
        if ctx.scope.pipefail_enabled() {
            if let Some(code) = ctx.scope.pipestatus_rightmost_failure() {
                result.code = code;
            }
        }

        // Post-hoc spill check + exit-3 remap (catches builtins and fast
        // external commands; also catches a ring overflow that already
        // flipped `did_spill` even when the limit itself is disabled, GH
        // #191). This is the shared contract every execution surface must
        // apply — see `apply_spill_contract`'s doc comment (GH #212).
        crate::output_limit::apply_spill_contract(&mut result, &ctx.output_limit).await;

        // Sync changes back from context
        {
            let mut ec = self.exec_ctx.write().await;
            ec.cwd = ctx.cwd.clone();
            ec.prev_cwd = ctx.prev_cwd.clone();
            ec.aliases = ctx.aliases.clone();
            ec.ignore_config = ctx.ignore_config.clone();
            ec.output_limit = ctx.output_limit.clone();
            // Unconsumed stdin goes back to the session, or it dies here with
            // `ctx`. A partial read (`read` takes one line) leaves the rest
            // split across two places: the bytes it over-read sit in `stdin`,
            // and the pipe still holds everything past them. Dropping the
            // reader discards that tail with no error — `read x; wc -c` over
            // 100 KiB counted 8187 bytes and said nothing.
            //
            // A multi-stage pipeline reaches here with the remainder already
            // returned by `run_pipeline`'s join, so this carries the
            // single-command and the pipeline case alike.
            ec.stdin = ctx.stdin.take();
            ec.pipe_stdin = ctx.pipe_stdin.take();
            // The parked handles go home. Stages get writers the runner owns,
            // so what is here is what was carried in.
            ec.pipe_stdout = ctx.pipe_stdout.take();
            ec.stdin_data_rx = ctx.stdin_data_rx.take();
        }
        {
            let mut scope = self.scope.write().await;
            *scope = ctx.scope.clone();
        }

        Ok(result)
    }

    /// Execute a pipeline in the background.
    ///
    /// The command is spawned as a tokio task and registered with the
    /// JobManager. The job is observable via `/v/jobs/{id}/status`,
    /// `/v/jobs/{id}/command`, and — while it is
    /// still running — `/v/jobs/{id}/stdout` and `/stderr`.
    ///
    /// GH #240 removed those two nodes because they filled once, at
    /// completion, while the docs promised a live stream. They are back on
    /// the terms the docs always claimed: `try_execute_external` tees each
    /// 8 KiB chunk into the job's stream as the child emits it. See
    /// `Job::stdout_stream` for exactly which bytes reach them.
    ///
    /// Returns immediately with a job ID like "[1]".
    #[tracing::instrument(level = "debug", skip(self, pipeline), fields(command_count = pipeline.stages.len()))]
    async fn execute_background(&self, pipeline: &crate::ast::Pipeline) -> Result<ExecResult> {
        use tokio::sync::oneshot;

        // Format the command for display in /v/jobs/{id}/command
        let command_str = self.format_pipeline(pipeline);

        // Create channel for result notification
        let (tx, rx) = oneshot::channel();

        // Register with JobManager to get job ID and create VFS entries
        let job_id = self.jobs.register(command_str.clone(), rx).await;

        // Fork the kernel for this background job. The fork snapshots the
        // parent's scope/cwd/aliases/user_tools so mutations stay isolated,
        // while sharing the job manager, VFS, and tool registry. The fork's
        // full dispatch chain (user tools, .kai scripts, `$(...)` in args)
        // is available here — something BackendDispatcher couldn't provide.
        //
        // The fork gets its own cancellation token (recorded on the job so
        // `kill %N` can stop the job — including a pure-builtin job with no OS
        // process group) and is stamped with the job id so any external
        // command it spawns records its process group for `kill -<sig> %N`.
        let cancel = tokio_util::sync::CancellationToken::new();
        self.jobs.set_cancel_token(job_id, cancel.clone()).await;
        let jobs = self.jobs.clone();
        let fork = self.fork_for_background(cancel, job_id).await;
        let runner = self.runner.clone();
        let stages = pipeline.stages.clone();

        // Snapshot the fork's exec_ctx for the spawned task. We have to do
        // this before tokio::spawn because the fork's exec_ctx is behind a
        // tokio RwLock and we want the spawned task to own its ctx.
        let mut bg_ctx = {
            let ec = fork.exec_ctx.read().await;
            ec.child_for_pipeline()
        };
        bg_ctx.scope = fork.scope.read().await.clone();
        // The fork's dispatcher points at the fork itself; set it here so
        // builtins inside the background task (e.g. timeout) re-dispatch
        // through the fork, not the parent.
        bg_ctx.dispatcher = fork.dispatcher();

        // Spawn the background task. Propagate the embedder's trace context
        // across the spawn boundary so the job's spans stay in the same trace.
        tokio::spawn(crate::telemetry::bind_current_context(async move {
            // runner.run needs a &dyn CommandDispatcher; fork.as_ref()
            // gives us that (Kernel implements CommandDispatcher).
            let mut result = runner.run(&stages, &mut bg_ctx, fork.as_ref()).await;

            // A background task is its own statement boundary. Pipeline stages
            // and command substitutions flush stderr to the fork's stderr
            // channel exactly as they would in the foreground, but the
            // statement-boundary drains live in `Kernel::execute`, which this
            // task never runs. Drain here, or the job's stderr never reaches
            // its result: a substitution's failure reason is lost and
            // `/v/jobs/{id}/stderr` stays empty.
            fork.drain_stderr_into(&mut result).await;

            // Apply the same spill/exit-3 contract the foreground path gets
            // (`execute_pipeline`'s `apply_spill_contract` call) — without
            // this, a background job whose output overflows the capture ring
            // or trips the output limit reports the child's ORIGINAL exit
            // code to JobManager, so `[N] done:0`/`Job::status()` silently
            // read success even though the output was capped (GH #212).
            crate::output_limit::apply_spill_contract(&mut result, &bg_ctx.output_limit).await;

            // Close out `/v/jobs/{id}/stdout`/`stderr`: a stream the external
            // drain tasks already fed live is left alone (re-writing the
            // aggregate would duplicate every byte), an untouched one takes
            // the captured result, and both close. Before `tx.send`, so a
            // reader that observes a terminal `status` also observes a
            // finished stream — never a `done:0` job whose output is still
            // arriving.
            jobs.finalize_streams(job_id, &result).await;

            // Send result to JobManager (ignore error if receiver dropped)
            let _ = tx.send(result);
        }));

        // The announcement is a shell message, not command output: bash writes
        // it to stderr, and stdout stays clean so `$(cmd &)` captures no shell
        // metadata. Terminated like every kaish diagnostic (#363).
        let mut announcement = ExecResult::success("");
        announcement.err = ExecResult::terminate_diagnostic(format!("[{job_id}]"));
        Ok(announcement)
    }

    /// Format a pipeline as a command string for display.
    fn format_pipeline(&self, pipeline: &crate::ast::Pipeline) -> String {
        pipeline
            .stages
            .iter()
            .map(|stage| {
                let cmd = match stage {
                    crate::ast::PipelineStage::Command(cmd) => cmd,
                    // A compound stage renders through the plan renderer,
                    // which already knows every statement form.
                    crate::ast::PipelineStage::Compound(stmt) => {
                        return crate::ast::plan::render_stmt(stmt)
                    }
                };
                let mut parts = vec![cmd.name.clone()];
                for arg in &cmd.args {
                    match arg {
                        Arg::Positional(expr) => {
                            parts.push(self.format_expr(expr));
                        }
                        Arg::Named { key, value } => {
                            parts.push(format!("--{}={}", key, self.format_expr(value)));
                        }
                        Arg::WordAssign { key, value } => {
                            parts.push(format!("{}={}", key, self.format_expr(value)));
                        }
                        Arg::ShortFlag(name) => {
                            parts.push(format!("-{}", name));
                        }
                        Arg::LongFlag(name) => {
                            parts.push(format!("--{}", name));
                        }
                        Arg::DoubleDash => {
                            parts.push("--".to_string());
                        }
                    }
                }
                parts.join(" ")
            })
            .collect::<Vec<_>>()
            .join(" | ")
    }

    /// Format an expression as a string for display.
    fn format_expr(&self, expr: &Expr) -> String {
        match expr {
            Expr::Literal(Value::String(s)) => {
                if s.contains(' ') || s.contains('"') {
                    format!("'{}'", s.replace('\'', "\\'"))
                } else {
                    s.clone()
                }
            }
            Expr::Literal(Value::Int(i)) => i.to_string(),
            Expr::Literal(Value::Float(f)) => f.to_string(),
            Expr::Literal(Value::Bool(b)) => b.to_string(),
            Expr::Literal(Value::Null) => "null".to_string(),
            // Show the source text, not the typed value.
            Expr::NumericLiteral { raw, .. } => raw.clone(),
            Expr::VarRef(path) => {
                let mut name = String::new();
                for (i, seg) in path.segments.iter().enumerate() {
                    match seg {
                        crate::ast::VarSegment::Field(f) => {
                            if i > 0 {
                                name.push('.');
                            }
                            name.push_str(f);
                        }
                        crate::ast::VarSegment::Index(idx) => name.push_str(&format!("[{idx}]")),
                        crate::ast::VarSegment::Key(k) => name.push_str(&format!("[{k}]")),
                        crate::ast::VarSegment::Dynamic(v) => name.push_str(&format!("[${v}]")),
                        crate::ast::VarSegment::Slice(a, b) => name.push_str(&format!(
                            "[{}:{}]",
                            a.map(|n| n.to_string()).unwrap_or_default(),
                            b.map(|n| n.to_string()).unwrap_or_default()
                        )),
                    }
                }
                format!("${{{}}}", name)
            }
            Expr::Interpolated(_) => "\"...\"".to_string(),
            Expr::HereDocBody { .. } => "<<heredoc".to_string(),
            _ => "...".to_string(),
        }
    }

    /// Execute a single command.
    async fn execute_command(&self, name: &str, args: &[Arg]) -> Result<ExecResult> {
        self.execute_command_depth(name, args, 0).await
    }

    async fn execute_command_depth(&self, name: &str, args: &[Arg], alias_depth: u8) -> Result<ExecResult> {
        // Dispatch breadcrumb instead of an `#[instrument]` span: this is the
        // most-recursed function on the ring, so wrapping its future in
        // `Instrumented<Span>` (plus the `err` recorder) cost native stack at
        // every level (GH #48, item 3). A `trace!` event records the command name
        // without living in the future.
        tracing::trace!(command = %name, alias_depth, "dispatch");
        // Special built-ins. `SpecialForm::from_name` is the single source of
        // truth (shared with `classify_command` via `is_runtime_special_form`),
        // and this match on the enum is *exhaustive* — adding a special-form is a
        // compile error until both the name mapping and the behavior here are
        // updated. A name that is not a special-form falls through to alias /
        // `/v/bin/` / user-tool / builtin / `PATH` resolution unchanged.
        if let Some(form) = crate::validator::SpecialForm::from_name(name) {
            return match form {
                crate::validator::SpecialForm::True => Ok(ExecResult::success("")),
                crate::validator::SpecialForm::False => Ok(ExecResult::failure(1, "")),
                crate::validator::SpecialForm::Source => Box::pin(self.execute_source(args)).await,
            };
        }

        // Alias expansion (with recursion limit)
        if alias_depth < 10 {
            let alias_value = {
                let ctx = self.exec_ctx.read().await;
                ctx.aliases.get(name).cloned()
            };
            if let Some(alias_val) = alias_value {
                // Split alias value into command + args
                let parts: Vec<&str> = alias_val.split_whitespace().collect();
                if let Some((alias_cmd, alias_args)) = parts.split_first() {
                    let mut new_args: Vec<Arg> = alias_args
                        .iter()
                        .map(|a| Arg::Positional(Expr::Literal(Value::String(a.to_string()))))
                        .collect();
                    new_args.extend_from_slice(args);
                    return Box::pin(self.execute_command_depth(alias_cmd, &new_args, alias_depth + 1)).await;
                }
            }
        }

        // Handle /v/bin/ prefix — dispatch to builtins via virtual path
        if let Some(builtin_name) = name.strip_prefix("/v/bin/") {
            return match self.tools.get(builtin_name) {
                Some(_) => Box::pin(self.execute_command_depth(builtin_name, args, alias_depth)).await,
                None => Ok(ExecResult::failure(127, format!("command not found: {}", name))),
            };
        }

        // Check user-defined tools first
        {
            let user_tools = self.user_tools.read().await;
            if let Some(tool_def) = user_tools.get(name) {
                let tool_def = tool_def.clone();
                drop(user_tools);
                return Box::pin(self.execute_user_tool(tool_def, args)).await;
            }
        }

        // Look up builtin tool
        let tool = match self.tools.get(name) {
            Some(t) => t,
            None => {
                // Try executing as .kai script from PATH
                if let Some(result) = Box::pin(self.try_execute_script(name, args)).await? {
                    return Ok(result);
                }
                // Try executing as external command from PATH — boxed because its
                // future is the heaviest branch here (holds a `tokio::process::Command`,
                // argv, the child's stdio streams, and kill/reap drop guards); leaving
                // it inline fattens every `execute_command_depth` frame on the recursion
                // ring even when the command is a builtin.
                //
                // A refusal (compiled without `subprocess`, or configured off)
                // does NOT return here — a backend-registered tool of the same
                // name is a separate capability and still gets a chance below.
                // `unavailable` carries the reason forward so the final "nothing
                // claimed this name" message can name it, instead of the
                // fallthrough re-deriving the wrong "command not found".
                let mut unavailable = None;
                match Box::pin(self.try_execute_external(name, args)).await? {
                    ExternalCommandOutcome::Ran(result) => return Ok(*result),
                    ExternalCommandOutcome::NotFound => {}
                    ExternalCommandOutcome::Unavailable(reason) => unavailable = Some(reason),
                }

                // Try backend-registered tools (embedder engines, etc.)
                // Look up tool schema for positional→named mapping.
                // Clone backend and drop read lock before awaiting (may involve network I/O).
                // Backend tools expect named JSON params, so enable positional mapping.
                let backend = self.exec_ctx.read().await.backend.clone();
                let tool_schema = backend
                    .get_tool(name)
                    .await
                    .unwrap_or_else(|e| {
                        // Schema lookup failing just means positionals won't
                        // get name-mapped below — `call_tool` is still
                        // attempted. Trace it so the degradation is visible
                        // rather than silently swallowed.
                        tracing::debug!("backend get_tool error for {name}: {e}");
                        None
                    })
                    .map(|t| {
                    let mut s = t.schema;
                    // Flat backend/MCP tools expect named JSON params, so map
                    // bare positionals onto named params. Subcommand-aware tools
                    // route positionals through the subcommand path and declare
                    // map_positionals per leaf (kj keeps it false so it re-parses
                    // the argv with its own clap) — don't blanket-override them.
                    if s.subcommands.is_empty() {
                        s.map_positionals = true;
                    }
                    s
                });
                let tool_args = self.build_args_async(args, tool_schema.as_ref()).await?;
                let mut ctx = self.exec_ctx.write().await;
                {
                    let scope = self.scope.read().await;
                    ctx.scope = scope.clone();
                }
                let backend = ctx.backend.clone();
                match backend.call_tool(name, tool_args, &mut *ctx).await {
                    Ok(tool_result) => {
                        let mut scope = self.scope.write().await;
                        *scope = ctx.scope.clone();
                        // Preserve every field (data/content_type/baggage,
                        // not just stdout text) — this is the embedder seam:
                        // `x=$(embedder_tool)` and structured iteration over
                        // its result depend on `.data` surviving the crossing
                        // back into the kernel.
                        let mut result = ExecResult::from(tool_result);
                        // The same rule the builtin dispatch applies, applied
                        // here too — this seam returns before it. Without this
                        // an embedder tool that hands back a value got its
                        // `$(…)` capture stringified, which is precisely what
                        // the comment above promises does not happen.
                        let data_is_only_output = result.data.is_some()
                            && !result.has_output()
                            && result.text_out().is_empty();
                        result.data_is_value |= data_is_only_output
                            || tool_schema
                                .as_ref()
                                .is_some_and(|s| s.typed_substitution);
                        return Ok(result);
                    }
                    Err(BackendError::ToolNotFound(_)) => {
                        // The backend confirms no such tool exists — fall
                        // through to "command not found" below.
                    }
                    Err(e) => {
                        // The tool was found (dispatch reached real
                        // execution) but running it failed — a genuine
                        // execution error, not "command not found". Surface
                        // it loudly instead of masking it as exit-127.
                        return Ok(ExecResult::failure(1, format!("{}: {}", name, e)));
                    }
                }

                return Ok(match unavailable {
                    Some(reason) => external_commands_unavailable_error(name, reason),
                    None => ExecResult::failure(127, format!("command not found: {}", name)),
                });
            }
        };

        // Build arguments (async to support command substitution, schema-aware
        // for flag values), then decide `--help` and `owns_output` — all three
        // read the tool's schema and nothing after this block does, so the whole
        // schema borrow is scoped here and cannot ride the `tool.execute` await
        // below (GH #48, item 7).
        let (tool_args, wants_help, owns_output, raw_argv, typed_substitution) = {
            // Prefer the kernel's schema catalog over `tool.schema()`: for a
            // clap-derived builtin, `schema()` rebuilds the entire clap
            // `Command` and reflects it into a fresh `ToolSchema` — ~34
            // allocations per command, 18% of all allocations in the GH #48
            // many-small-commands profile — to produce exactly what the catalog
            // already holds. The catalog is seeded from this same registry in
            // `Kernel::assemble` and is name-sorted, so this is a binary search
            // with no allocation at all. `owned` covers a tool the catalog
            // doesn't list (registered after assembly, or whose schema name
            // differs from its dispatch name): the fallback calls the same
            // `schema()` and is equivalent, just not free.
            let catalog = { self.exec_ctx.read().await.tool_schemas.clone() };
            let owned;
            let schema: &crate::tools::ToolSchema =
                match catalog.binary_search_by(|s| s.name.as_str().cmp(name)) {
                    Ok(i) => &catalog[i],
                    Err(_) => {
                        owned = tool.schema();
                        &owned
                    }
                };

            let tool_args = self.build_args_async(args, Some(schema)).await?;

            // --help / -h: show the generic whole-tool help, unless either the tool's
            // root schema claims that flag OR the tool owns its output. Owned-output
            // tools re-parse their own argv and route their own `--help` — including
            // leaf/subcommand help — through their internal (clap) parser, so the root
            // schema can't express "this leaf claims help" and intercepting here would
            // render top-level help and return before `execute()` ever sees the
            // request (#51). Pass it through and let the tool render its own help.
            let schema_claims = |flag: &str| -> bool {
                let bare = flag.trim_start_matches('-');
                schema.params.iter().any(|p| p.matches_flag(flag) || p.matches_flag(bare))
            };
            let wants_help = !schema.owns_output
                && ((tool_args.flags.contains("help") && !schema_claims("help"))
                    || (tool_args.flags.contains("h") && !schema_claims("-h")));

            (tool_args, wants_help, schema.owns_output, schema.raw_argv, schema.typed_substitution)
        };

        if wants_help {
            let help_topic = crate::help::HelpTopic::Tool(name.to_string());
            let ctx = self.exec_ctx.read().await;
            let content = crate::help::get_help(&help_topic, &ctx.tool_schemas);
            return Ok(ExecResult::with_output(crate::interpreter::OutputData::text(content)));
        }

        // Snapshot exec_ctx into a local context and release the write lock
        // before calling tool.execute. Holding the write across tool execution
        // would deadlock any builtin that re-dispatches through ctx.dispatcher
        // (timeout, scatter) — the inner dispatch_command needs its own
        // exec_ctx.write() and would block forever.
        let mut ctx = {
            let ec = self.exec_ctx.write().await;
            let scope = self.scope.read().await;
            // Inherit `ec.pipeline_position` and `ec.cancel` (the latter set by
            // dispatch_command from the runner's ctx.cancel, so a builtin-swapped
            // child token — e.g. timeout's — reaches the spawned external via
            // wait_or_kill; it falls back to the kernel's own token on a
            // non-dispatch path). See `snapshot_exec_ctx` for the boxing rationale.
            self.snapshot_exec_ctx(&ec, &scope, ec.pipeline_position, ec.cancel.clone())
        }; // both locks released — tool.execute can re-dispatch safely

        // Move stdin out of self.exec_ctx into the snapshot (consumed-by-tool
        // semantics): take() so a later dispatch doesn't see stale stdin.
        // Done after the snapshot above so we hold the write briefly.
        {
            let mut ec = self.exec_ctx.write().await;
            ctx.stdin = ec.stdin.take();
            ctx.stdin_data = ec.stdin_data.take();
            ctx.stdin_data_rx = ec.stdin_data_rx.take();
            ctx.pipe_stdin = ec.pipe_stdin.take();
            ctx.pipe_stdout = ec.pipe_stdout.take();
            // Same take-don't-clone discipline as stdin, and for the same
            // reason: these belong to exactly one dispatch, and a copy left
            // behind would let the next command adopt it.
        }

        // Honor --json before the builtin runs so its setting survives a clap
        // parse failure (e.g. `cmd --json --bogus-flag` would otherwise drop
        // --json on the floor when `try_parse_from` returns Err early).
        // The builtin's own `parsed.global.apply(ctx)` becomes idempotent.
        GlobalFlags::apply_from_args(&tool_args, raw_argv, &mut *ctx);

        let mut result = tool.execute(tool_args, &mut *ctx).await;
        // A command substitution binds `.data` only when it is the result's
        // VALUE. `--json` and the pipeline sideband read `.data` either way,
        // so this marks the ONE consumer whose answer is a matter of taste.
        //
        // Two ways to qualify. A tool that printed NOTHING has only its data,
        // so that data is trivially its value — this is `fromjson`'s shape and
        // an out-of-tree tool's, and it needs no declaration, which is what
        // keeps this from breaking embedder tools. A tool that printed text
        // AND attached data has to say which one it means, because the two
        // readings are equally defensible: `jq` means the data, `cut` means
        // the text it printed.
        let data_is_only_output = result.data.is_some()
            && !result.has_output()
            && result.text_out().is_empty();
        // OR, never assign: a wrapper that re-dispatches an inner command
        // returns the INNER result, and stamping it from the wrapper's own
        // schema erased what the inner tool declared —
        // `$(timeout 5 fromjson '[1,2]')` bound text while `$(fromjson …)`
        // bound a list. A result arrives here fresh from `tool.execute`, so a
        // marker already set is one the tool or its inner dispatch meant.
        result.data_is_value |= typed_substitution || data_is_only_output;

        // Sync mutations back. Tools may have changed scope (set/cd),
        // cwd/prev_cwd (cd), and aliases (alias). Also return any unused pipe
        // endpoints to self.exec_ctx so dispatch_command's post-execute sync
        // hands them back to the pipeline runner — the runner uses
        // stage_ctx.pipe_stdout to write the result to the next stage when
        // the tool itself didn't take and write to it.
        {
            let mut scope = self.scope.write().await;
            *scope = ctx.scope.clone();
        }
        {
            let mut ec = self.exec_ctx.write().await;
            ec.cwd = ctx.cwd;
            ec.prev_cwd = ctx.prev_cwd;
            ec.aliases = ctx.aliases;
            // A builtin (`set -o output-limit`, `kaish-output-limit set`) can
            // mutate the runtime output limit; without this sync the change is
            // dropped here and never reaches dispatch_command's read-back, so
            // it would not survive past the current statement.
            ec.output_limit = ctx.output_limit.clone();
            // Same for `kaish-ignore` (add/clear/defaults/scope): this field
            // was missing from this sync, so every runtime ignore mutation
            // silently died at the end of its own statement — including the
            // documented `kaish-ignore add .gitignore` rc-file recipe.
            ec.ignore_config = ctx.ignore_config.clone();
            ec.pipe_stdin = ctx.pipe_stdin.take();
            ec.pipe_stdout = ctx.pipe_stdout.take();
            // What a partial read left behind goes back too: `read` takes one
            // line and keeps the rest, and that remainder belongs to the next
            // reader. Without this it dies with the tool's context and
            // `read x; read y` loses the second line.
            ec.stdin = ctx.stdin.take();
            // The sideband is stdin in typed form and returns by the same
            // rule; taken in above, an unconsumed value would die here.
            ec.stdin_data = ctx.stdin_data.take();
            ec.stdin_data_rx = ctx.stdin_data_rx.take();
        }

        // Builtins parse --json via the GlobalFlags flatten in their clap
        // struct and write ctx.output_format. The kernel applies it — unless the
        // tool owns its own output (renders --json itself), in which case we
        // leave its bytes untouched.
        let result = finalize_output(result, ctx.output_format, owns_output);

        Ok(result)
    }

    /// The session `HOME` from the kernel scope, if set. Tilde expansion reads
    /// this rather than `std::env::var("HOME")` so the kernel stays hermetic —
    /// a hermetic embedder (empty `initial_vars`) gets `None`, and `~` is left
    /// unexpanded rather than leaking the host home directory.
    async fn scope_home(&self) -> Option<String> {
        match self.scope.read().await.get("HOME") {
            Some(Value::String(s)) => Some(s.clone()),
            _ => None,
        }
    }

    /// Build tool arguments from AST args.
    ///
    /// Uses async evaluation to support command substitution in arguments.
    /// Delegates to the shared `bind_tool_args` core (GH #188): this method
    /// now only supplies the evaluator — `self` implements `ArgValueSource`
    /// against the kernel's own session state (full recursion through the
    /// async pipeline, real glob expansion, tilde expansion). Before this,
    /// `bind_tool_args`'s flag/positional-binding logic was duplicated by a
    /// reduced sync twin (`scheduler::pipeline::build_tool_args`, used by
    /// scatter/gather's own option parsing and the `#[cfg(test)]`
    /// `BackendDispatcher`) that could — and did — drift from this method,
    /// the same drift-class GH #133 fixed for the external-command spawn
    /// sites. Now both paths call the one `bind_tool_args` core, differing
    /// only in which `ArgValueSource` they hand it.
    async fn build_args_async(&self, args: &[Arg], schema: Option<&crate::tools::ToolSchema>) -> Result<ToolArgs> {
        bind_tool_args(args, schema, self).await
    }

    /// Build arguments as flat string list for external commands.
    ///
    /// Unlike `build_args_async` which separates flags into a HashSet (for schema-aware builtins),
    /// this preserves the original flag format as strings for external commands:
    /// - `-l` stays as `-l`
    /// - `--verbose` stays as `--verbose`
    /// - `key=value` stays as `key=value`
    ///
    /// This is what external commands expect in their argv.
    #[cfg(feature = "subprocess")]
    async fn build_args_flat(&self, args: &[Arg]) -> Result<Vec<String>> {
        let mut argv = Vec::new();
        let home = self.scope_home().await;
        for arg in args {
            match arg {
                Arg::Positional(expr) => {
                    // Glob expansion for external commands
                    if let Expr::GlobPattern(pattern) = expr {
                        let glob_enabled = {
                            let scope = self.scope.read().await;
                            scope.glob_enabled()
                        };
                        if glob_enabled {
                            let (paths, cwd) = {
                                let ctx = self.exec_ctx.read().await;
                                let paths = ctx.expand_glob(pattern).await
                                    .map_err(|e| anyhow::anyhow!("glob: {}", e))?;
                                let cwd = ctx.resolve_path(".");
                                (paths, cwd)
                            };
                            if paths.is_empty() {
                                return Err(anyhow::anyhow!("no matches: {}", pattern));
                            }
                            for path in paths {
                                let display = if !pattern.starts_with('/') {
                                    path.strip_prefix(&cwd)
                                        .unwrap_or(&path)
                                        .to_string_lossy().into_owned()
                                } else {
                                    path.to_string_lossy().into_owned()
                                };
                                argv.push(display);
                            }
                            continue;
                        }
                    }
                    // The exact word the author typed reaches the external
                    // process, matching what `ast::plan::render_expr` showed.
                    // Skips `eval_expr_async`: no `Value` reproduces `raw`.
                    if let Expr::NumericLiteral { raw, .. } = expr {
                        argv.push(raw.clone());
                        continue;
                    }
                    let value = self.eval_expr_async(expr).await?;
                    // Decision D: a bare collection can't cross the external
                    // process boundary as an argv element — refuse rather than
                    // silently JSON-serializing it. A quoted `"$x"` already
                    // reduced to a `Value::String` above (via `Expr::Interpolated`),
                    // so only a live, un-interpolated `$x` trips this.
                    if let Some(msg) = crate::interpreter::structured_boundary_error("a command argument", &value) {
                        return Err(anyhow::anyhow!(msg));
                    }
                    let value = apply_tilde_expansion(value, home.as_deref());
                    // External-command argv is a text sink: a bare `$BIN` binary
                    // word goes loud, never the `[binary: N bytes]` placeholder.
                    argv.push(value_to_text_sink(&value).map_err(|e| anyhow::anyhow!("{e}"))?);
                }
                Arg::Named { key, value } => {
                    if let Expr::NumericLiteral { raw, .. } = value {
                        argv.push(format!("--{key}={raw}"));
                        continue;
                    }
                    let val = self.eval_expr_async(value).await?;
                    if let Some(msg) = crate::interpreter::structured_boundary_error("a command argument", &val) {
                        return Err(anyhow::anyhow!(msg));
                    }
                    let val = apply_tilde_expansion(val, home.as_deref());
                    let val_str = value_to_text_sink(&val).map_err(|e| anyhow::anyhow!("{e}"))?;
                    argv.push(format!("--{key}={val_str}"));
                }
                Arg::WordAssign { key, value } => {
                    if let Expr::NumericLiteral { raw, .. } = value {
                        argv.push(format!("{key}={raw}"));
                        continue;
                    }
                    let val = self.eval_expr_async(value).await?;
                    if let Some(msg) = crate::interpreter::structured_boundary_error("a command argument", &val) {
                        return Err(anyhow::anyhow!(msg));
                    }
                    let val = apply_tilde_expansion(val, home.as_deref());
                    let val_str = value_to_text_sink(&val).map_err(|e| anyhow::anyhow!("{e}"))?;
                    argv.push(format!("{key}={val_str}"));
                }
                Arg::ShortFlag(name) => {
                    // Preserve original format: -l, -la (combined flags)
                    argv.push(format!("-{}", name));
                }
                Arg::LongFlag(name) => {
                    // Preserve original format: --verbose
                    argv.push(format!("--{}", name));
                }
                Arg::DoubleDash => {
                    // Preserve the -- marker
                    argv.push("--".to_string());
                }
            }
        }
        Ok(argv)
    }

    /// Async expression evaluator that supports command substitution.
    ///
    /// This is used for contexts where expressions may contain `$(...)` command
    /// substitution. Unlike the sync `eval_expr`, this can execute pipelines.
    /// Evaluate an `if`/`while` condition, folding whatever its commands print
    /// into `out`.
    ///
    /// A condition's stdout belongs to the enclosing statement, the same rule
    /// `Expr::Command` already applies to its stderr. [`Self::eval_expr_async`]
    /// returns only a `Value`, so those bytes had nowhere to go and
    /// `if echo COND; then echo BODY; fi` printed only `BODY`. Handing them
    /// back to the caller keeps the decision there: the `if`/`while` arm folds
    /// them into the statement's own result, and every consumer of that result
    /// — a pipe, a `$(…)` capture, a redirect — carries them without learning
    /// what a condition is. A shared slot on `ExecContext` would have done it
    /// the other way; that is the pattern GH #369 exists to remove.
    ///
    /// Only the forms that can hold a command in STATEMENT position are handled
    /// here. Everything else is [`Self::eval_expr_async`]'s, `$(…)` above all:
    /// a substitution's stdout IS its value, so folding it in as well would
    /// print it twice.
    fn eval_condition_async<'a>(
        &'a self,
        expr: &'a Expr,
        out: &'a mut ExecResult,
    ) -> std::pin::Pin<Box<dyn std::future::Future<Output = Result<Value>> + Send + 'a>> {
        Box::pin(async move {
            match expr {
                Expr::Command(cmd) => {
                    let mut result = self.execute_command(&cmd.name, &cmd.args).await?;
                    self.emit_cmdsubst_stderr(&result.err).await;
                    // Truthiness comes from the command's OWN code, read before
                    // the spill contract can remap it. A capped `if seq 1
                    // 100000` succeeded; only its output was too big to keep,
                    // and reading the remapped 3 would send it to `else`.
                    // A fault has no boolean to give. Aborting here is the
                    // rule `[[ ]]` and `(( ))` already follow in this position;
                    // reading it as false would let `else` run on a comparison
                    // that never happened.
                    if result.fault {
                        self.emit_cmdsubst_stderr(&result.err).await;
                        return Err(anyhow::anyhow!("{}", result.err.trim_end()));
                    }
                    let truthy = result.code == 0;
                    // Carrying the stdout made this arm one of the surfaces
                    // that produce a raw `ExecResult`, and it reaches
                    // `execute_command` below the pipeline layer that applies
                    // the contract — so it applies it here, as
                    // `apply_spill_contract`'s "ONE seam" note requires.
                    // Without this a condition handed back its full output with
                    // no limit at all.
                    let limit = self.exec_ctx.read().await.output_limit.clone();
                    crate::output_limit::apply_spill_contract(&mut result, &limit).await;
                    push_stdout_of(out, &result);
                    Ok(Value::Bool(truthy))
                }
                // Short-circuits exactly as the `eval_expr_async` arm does, and
                // yields the operand's own value rather than a coerced bool. A
                // side that short-circuits never runs, so it prints nothing.
                Expr::BinaryOp { left, op, right } => {
                    let left_val = self.eval_condition_async(left, &mut *out).await?;
                    let short_circuits = match op {
                        BinaryOp::And => !is_truthy(&left_val),
                        BinaryOp::Or => is_truthy(&left_val),
                    };
                    if short_circuits {
                        return Ok(left_val);
                    }
                    self.eval_condition_async(right, out).await
                }
                // The negated command still RUNS, so its output belongs to the
                // statement exactly as an un-negated one's does. Routing this
                // through `eval_expr_async` would drop it.
                Expr::Not(inner) => {
                    let value = self.eval_condition_async(inner, out).await?;
                    Ok(Value::Bool(!is_truthy(&value)))
                }
                other => self.eval_expr_async(other).await,
            }
        })
    }

    fn eval_expr_async<'a>(&'a self, expr: &'a Expr) -> std::pin::Pin<Box<dyn std::future::Future<Output = Result<Value>> + Send + 'a>> {
        Box::pin(async move {
        match expr {
            Expr::Not(inner) => {
                let value = self.eval_expr_async(inner).await?;
                Ok(Value::Bool(!is_truthy(&value)))
            }
            Expr::Literal(value) => Ok(value.clone()),
            // Typed evaluation only needs `value`; `raw` is for argv and
            // plan text sinks that read the `Expr` directly.
            Expr::NumericLiteral { value, .. } => Ok(value.clone()),
            Expr::VarRef(path) => {
                let scope = self.scope.read().await;
                match scope.resolve_path(path) {
                    Ok(v) => Ok(v),
                    Err(PathError::UndefinedRoot(_)) => {
                        Err(anyhow::anyhow!("undefined variable"))
                    }
                    Err(PathError::Absence(msg)) | Err(PathError::Shape(msg)) => {
                        Err(anyhow::anyhow!(msg))
                    }
                }
            }
            Expr::Interpolated(parts) => {
                let mut result = String::new();
                for part in parts {
                    result.push_str(&self.eval_string_part_async(part).await?);
                }
                Ok(Value::String(result))
            }
            Expr::HereDocBody { parts, strip_tabs } => {
                // Assemble part-by-part so `<<-` tab stripping applies to the
                // literal source, not to tabs from a `$var` value (bash strips
                // source-line tabs before parameter expansion).
                let mut asm = crate::interpreter::HeredocAssembler::new(*strip_tabs);
                for sp in parts {
                    match &sp.part {
                        StringPart::Literal(s) => asm.push_literal(s),
                        other => {
                            asm.push_interpolated(&self.eval_string_part_async(other).await?)
                        }
                    }
                }
                Ok(Value::String(asm.into_string()))
            }
            Expr::BinaryOp { left, op, right } => match op {
                BinaryOp::And => {
                    let left_val = self.eval_expr_async(left).await?;
                    if !is_truthy(&left_val) {
                        return Ok(left_val);
                    }
                    self.eval_expr_async(right).await
                }
                BinaryOp::Or => {
                    let left_val = self.eval_expr_async(left).await?;
                    if is_truthy(&left_val) {
                        return Ok(left_val);
                    }
                    self.eval_expr_async(right).await
                }
            },
            Expr::CommandSubst(stmts) => {
                // Snapshot scope, cwd, and session config before running —
                // only output escapes, not side effects like `cd`, variable
                // assignments, or config mutations (`kaish-ignore`,
                // `kaish-output-limit`, `alias`/`unalias`) — matching how
                // every other execution context (background forks, scatter
                // workers) already isolates mutations (GH #139).
                // Boxed: this ~470 B scope snapshot is held across the nested
                // `$(…)` recursion await below, so inlining it grows every
                // command-substitution level's future (GH #48, item 4).
                let saved_scope = Box::new(self.scope.read().await.clone());
                let saved_ec = {
                    let ec = self.exec_ctx.read().await;
                    (
                        ec.cwd.clone(),
                        ec.prev_cwd.clone(),
                        ec.aliases.clone(),
                        ec.ignore_config.clone(),
                        ec.output_limit.clone(),
                    )
                };

                // Capture result without `?` — restore state unconditionally
                let run_result = self.execute_block_capturing(stmts).await;

                // Restore scope and cwd regardless of success/failure
                {
                    let mut scope = self.scope.write().await;
                    *scope = *saved_scope;
                    if let Ok(ref r) = run_result {
                        scope.set_last_result(r.clone());
                        scope.note_cmdsubst_code(r.code);
                    }
                }
                {
                    let mut ec = self.exec_ctx.write().await;
                    let (cwd, prev_cwd, aliases, ignore_config, output_limit) = saved_ec;
                    ec.cwd = cwd;
                    ec.prev_cwd = prev_cwd;
                    ec.aliases = aliases;
                    ec.ignore_config = ignore_config;
                    ec.output_limit = output_limit;
                }

                // A substitution's stderr belongs to the enclosing statement,
                // never to its value. Emit it before the value is built.
                if let Ok(ref r) = run_result {
                    self.emit_cmdsubst_stderr(&r.err).await;
                }

                // Now propagate the error
                let result = run_result?;

                // A held body stops the enclosing statement before its
                // missing output is used (spec §I.5) — the request rides up
                // as a typed error the statement loop converts back into a
                // held result, and is stashed for the boundary in case an
                // intermediate catch stringifies the error.

                // A binary result is preserved as bytes — never lossy-decoded to
                // a string. No trailing-newline trim (every byte is significant).
                if let Some(bytes) = result.out_bytes() {
                    Ok(Value::Bytes(bytes.to_vec()))
                // Prefer structured data (enables `for i in $(cmd)` iteration)
                } else if let Some(data) = &result.data {
                    Ok(data.clone())
                } else if let Some(output) = result.output() {
                    // Flat non-text node lists (glob, ls, tree) → iterable array
                    if output.is_flat() && !output.is_simple_text() && !output.root.is_empty() {
                        let items: Vec<serde_json::Value> = output.root.iter()
                            .map(|n| serde_json::Value::String(n.display_name().to_string()))
                            .collect();
                        Ok(Value::Json(serde_json::Value::Array(items)))
                    } else {
                        // Strip trailing newlines only (POSIX command-subst),
                        // not all trailing whitespace — spaces/tabs are
                        // significant. Use the exact same trim as the quoted
                        // `"$(…)"` interpolation path (`StringPart::CommandSubst`,
                        // `trim_end_matches('\n')`) so bare and quoted command
                        // substitution agree.
                        Ok(Value::String(
                            result.text_out().trim_end_matches('\n').to_string(),
                        ))
                    }
                } else {
                    // Otherwise return stdout as single string (NO implicit splitting)
                    Ok(Value::String(
                        result.text_out().trim_end_matches('\n').to_string(),
                    ))
                }
            }
            Expr::Test(test_expr) => {
                Ok(Value::Bool(self.eval_test_async(test_expr).await?))
            }
            // `(( expr ))` in condition position (`if`/`while`). Unlike the
            // standalone `Stmt::Arith` form, a condition has no exit-code
            // channel separate from true/false, so an evaluation fault
            // propagates like `Expr::Test`'s does — it aborts the
            // enclosing statement rather than silently reading false.
            Expr::Arith(expr_str) => {
                let n = self
                    .eval_arithmetic_async(expr_str)
                    .await
                    .context("arithmetic condition")?;
                Ok(Value::Bool(n != 0))
            }
            Expr::Positional(n) => {
                let scope = self.scope.read().await;
                match scope.get_positional(*n) {
                    Some(s) => Ok(Value::String(s.to_string())),
                    None => Ok(Value::String(String::new())),
                }
            }
            Expr::AllArgs => {
                let scope = self.scope.read().await;
                Ok(Value::String(scope.all_args().join(" ")))
            }
            Expr::ArgCount => {
                let scope = self.scope.read().await;
                Ok(Value::Int(scope.arg_count() as i64))
            }
            Expr::VarLength(path) => {
                let scope = self.scope.read().await;
                crate::interpreter::resolve_length(&scope, path)
                    .map(Value::Int)
                    .map_err(|msg| anyhow::anyhow!(msg))
            }
            Expr::VarWithDefault { path, default } => {
                // Resolve inside a scoped guard so the lock is released before the
                // recursive default evaluation.
                let resolved = {
                    let scope = self.scope.read().await;
                    crate::interpreter::resolve_default(&scope, path)
                        .map_err(|msg| anyhow::anyhow!(msg))?
                };
                match resolved {
                    Some(value) => Ok(value),
                    None => self.eval_string_parts_async(default).await.map(Value::String),
                }
            }
            Expr::Arithmetic(expr_str) => {
                self.eval_arithmetic_async(expr_str).await.map(Value::Int)
            }
            Expr::Command(cmd) => {
                // A command in expression position — an `if`/`while`
                // condition, or a side of `&&`/`||` inside one. Its VALUE is
                // the exit code's truthiness, but its OUTPUT belongs to the
                // enclosing statement, exactly as `Expr::CommandSubst` says of
                // a substitution's stderr. Dropping the `ExecResult` here made
                // `if cat /nonexistent; then …` print nothing at all, so every
                // condition that failed for a reason failed silently.
                let result = self.execute_command(&cmd.name, &cmd.args).await?;
                self.emit_cmdsubst_stderr(&result.err).await;
                Ok(Value::Bool(result.code == 0))
            }
            Expr::LastExitCode => {
                let scope = self.scope.read().await;
                Ok(Value::Int(scope.last_result().code))
            }
            Expr::CurrentPid => {
                let scope = self.scope.read().await;
                Ok(Value::Int(scope.pid() as i64))
            }
            Expr::GlobPattern(s) => Ok(Value::String(s.clone())),
            Expr::ListLiteral(elems) => {
                // Spread must itself be a list — a scalar/record spread is a
                // loud error, never silently coerced or dropped (mirrors the
                // sync `Evaluator::eval_list_literal`; wording shared via
                // `spread_non_list_message` so the two paths can't diverge).
                let mut out = Vec::with_capacity(elems.len());
                for elem in elems {
                    match elem {
                        ListElem::Item(e) => {
                            let value = self.eval_expr_async(e).await?;
                            out.push(crate::interpreter::value_to_json(&value));
                        }
                        ListElem::Spread(e) => {
                            let value = self.eval_expr_async(e).await?;
                            match value {
                                Value::Json(serde_json::Value::Array(items)) => out.extend(items),
                                other => return Err(anyhow::anyhow!(spread_non_list_message(&other))),
                            }
                        }
                    }
                }
                Ok(Value::Json(serde_json::Value::Array(out)))
            }
            Expr::RecordLiteral(entries) => {
                // Insertion order preserved (workspace serde_json has
                // `preserve_order`); a duplicate key keeps the last value
                // written, matching plain map-insert semantics.
                let mut map = serde_json::Map::new();
                for entry in entries {
                    let key = match &entry.key {
                        RecordKey::Bare(s) | RecordKey::Quoted(s) => s.clone(),
                        // `{"$k": v}` resolves like any double-quoted string
                        // (used to silently create a literal "$k" key).
                        RecordKey::Interpolated(parts) => {
                            self.eval_string_parts_async(parts).await?
                        }
                    };
                    let value = self.eval_expr_async(&entry.value).await?;
                    map.insert(key, crate::interpreter::value_to_json(&value));
                }
                Ok(Value::Json(serde_json::Value::Object(map)))
            }
        }
        })
    }

    /// Async helper to evaluate multiple StringParts into a single string.
    fn eval_string_parts_async<'a>(&'a self, parts: &'a [StringPart]) -> std::pin::Pin<Box<dyn std::future::Future<Output = Result<String>> + Send + 'a>> {
        Box::pin(async move {
            let mut result = String::new();
            for part in parts {
                result.push_str(&self.eval_string_part_async(part).await?);
            }
            Ok(result)
        })
    }

    /// Async helper to evaluate a StringPart.
    /// Evaluate a `[[ ]]` test expression asynchronously, routing file tests
    /// through the VFS backend instead of using raw `std::path`.
    fn eval_test_async<'a>(&'a self, test_expr: &'a TestExpr) -> std::pin::Pin<Box<dyn std::future::Future<Output = Result<bool>> + Send + 'a>> {
        Box::pin(async move {
            match test_expr {
                TestExpr::FileTest { op, path } => {
                    let path_value = self.eval_expr_async(path).await?;
                    // Expand `~` against the session HOME before stat'ing, the
                    // same way argv positionals do — otherwise `[[ -f ~/x ]]`
                    // stats the literal `~/x` and is always false.
                    let home = self.scope_home().await;
                    let path_value = apply_tilde_expansion(path_value, home.as_deref());
                    // A binary `[[ -f $bin ]]` operand goes loud rather than
                    // silently stat'ing a file literally named
                    // `[binary: N bytes]` (the same path-positional guard
                    // builtins like `stat`/`cp` use).
                    let path_str = crate::interpreter::value_to_text_sink_named(&path_value, "a path")
                        .map_err(|e| anyhow::anyhow!("{e}"))?;
                    // The empty path names no file. Resolving it lands on the
                    // working directory, so `[[ -e "" ]]` answered true — bash
                    // says false, and so does every reading of "does this file
                    // exist". Same guard as `test`'s `file_test`; the two
                    // spellings of a file test must not disagree about a path,
                    // and `test_compound_tests` pins that they agree.
                    if path_str.is_empty() {
                        return Ok(false);
                    }
                    // Resolve against the *session* cwd, not the process cwd, so a
                    // relative `[[ -f rel ]]` honors `cd` and agrees with the
                    // VFS-aware `test` builtin (GH #101). Backend stats a raw
                    // relative path against the process cwd otherwise.
                    let (resolved, backend) = {
                        let ctx = self.exec_ctx.read().await;
                        (ctx.resolve_path(&path_str), ctx.backend.clone())
                    };
                    // `-r`/`-w`/`-x` go through `path_access`, never through
                    // the raw mode bits: the mount's read-only state is half
                    // the answer and `stat` does not carry it. The `test`
                    // builtin's `file_test` reads the same query, and
                    // `file_test_writable_tests` runs every case through both
                    // spellings — this mirror has drifted before.
                    Ok(match op {
                        FileTestOp::Exists => backend.stat(&resolved).await.is_ok(),
                        FileTestOp::IsFile => {
                            backend.stat(&resolved).await.is_ok_and(|e| e.is_file())
                        }
                        FileTestOp::IsDir => {
                            backend.stat(&resolved).await.is_ok_and(|e| e.is_dir())
                        }
                        FileTestOp::Readable => backend
                            .path_access(&resolved)
                            .await
                            .is_ok_and(|access| access.readable),
                        FileTestOp::Writable => backend
                            .path_access(&resolved)
                            .await
                            .is_ok_and(|access| access.writable),
                        FileTestOp::Executable => backend
                            .path_access(&resolved)
                            .await
                            .is_ok_and(|access| access.executable),
                        // lstat: what is at this name. A dangling link is true
                        // here and false under `-e`.
                        FileTestOp::IsSymlink => {
                            backend.lstat(&resolved).await.is_ok_and(|e| e.is_symlink())
                        }
                    })
                }
                TestExpr::StringTest { op, value } => match op {
                    crate::ast::StringTestOp::IsEmpty | crate::ast::StringTestOp::IsNonEmpty => {
                        let val = self.eval_expr_async(value).await?;
                        // Decision E: a collection operand is a loud Shape error
                        // here too — must not diverge from the sync path in
                        // interpreter/eval.rs (shared `scalar_test_operand_error`).
                        let symbol = match op {
                            crate::ast::StringTestOp::IsEmpty => "-z",
                            crate::ast::StringTestOp::IsNonEmpty => "-n",
                            crate::ast::StringTestOp::IsList
                            | crate::ast::StringTestOp::IsRecord => unreachable!(),
                        };
                        if let Some(msg) = crate::interpreter::scalar_test_operand_error(symbol, &val) {
                            anyhow::bail!(msg);
                        }
                        let s = value_to_string(&val);
                        Ok(match op {
                            crate::ast::StringTestOp::IsEmpty => s.is_empty(),
                            crate::ast::StringTestOp::IsNonEmpty => !s.is_empty(),
                            crate::ast::StringTestOp::IsList
                            | crate::ast::StringTestOp::IsRecord => unreachable!(),
                        })
                    }
                    // Shape guard: propagates eval errors like -z/-n (a bare
                    // `$unset` is an undefined-variable error, not a silent
                    // false). A defined-but-wrong-shaped value is false. Must
                    // not diverge from the sync path in interpreter/eval.rs.
                    crate::ast::StringTestOp::IsList | crate::ast::StringTestOp::IsRecord => {
                        let val = self.eval_expr_async(value).await?;
                        Ok(op.matches_shape(&val))
                    }
                },
                TestExpr::Comparison { left, op, right } => {
                    // Evaluate operands async (handles $(cmd)), then compare sync
                    let left_val = self.eval_expr_async(left).await?;
                    let right_val = self.eval_expr_async(right).await?;
                    let resolved = TestExpr::Comparison {
                        left: Box::new(Expr::Literal(left_val)),
                        op: *op,
                        right: Box::new(Expr::Literal(right_val)),
                    };
                    let expr = Expr::Test(Box::new(resolved));
                    let mut scope = self.scope.write().await;
                    let value = eval_expr(&expr, &mut scope)
                        .map_err(|e| anyhow::anyhow!("{}", e))?;
                    Ok(value_to_bool(&value))
                }
                TestExpr::And { left, right } => {
                    if !self.eval_test_async(left).await? {
                        Ok(false)
                    } else {
                        self.eval_test_async(right).await
                    }
                }
                TestExpr::Or { left, right } => {
                    if self.eval_test_async(left).await? {
                        Ok(true)
                    } else {
                        self.eval_test_async(right).await
                    }
                }
                TestExpr::Not { expr } => {
                    Ok(!self.eval_test_async(expr).await?)
                }
                TestExpr::In { left, right } => {
                    let left_val = self.eval_expr_async(left).await?;
                    let right_val = self.eval_expr_async(right).await?;
                    let resolved = TestExpr::In {
                        left: Box::new(Expr::Literal(left_val)),
                        right: Box::new(Expr::Literal(right_val)),
                    };
                    let expr = Expr::Test(Box::new(resolved));
                    let mut scope = self.scope.write().await;
                    let value = eval_expr(&expr, &mut scope)
                        .map_err(|e| anyhow::anyhow!("{}", e))?;
                    Ok(value_to_bool(&value))
                }
                TestExpr::NotIn { left, right } => {
                    let left_val = self.eval_expr_async(left).await?;
                    let right_val = self.eval_expr_async(right).await?;
                    let resolved = TestExpr::NotIn {
                        left: Box::new(Expr::Literal(left_val)),
                        right: Box::new(Expr::Literal(right_val)),
                    };
                    let expr = Expr::Test(Box::new(resolved));
                    let mut scope = self.scope.write().await;
                    let value = eval_expr(&expr, &mut scope)
                        .map_err(|e| anyhow::anyhow!("{}", e))?;
                    Ok(value_to_bool(&value))
                }
            }
        })
    }

    fn eval_string_part_async<'a>(&'a self, part: &'a StringPart) -> std::pin::Pin<Box<dyn std::future::Future<Output = Result<String>> + Send + 'a>> {
        Box::pin(async move {
            match part {
                StringPart::Literal(s) => Ok(s.clone()),
                StringPart::Var(path) => {
                    let scope = self.scope.read().await;
                    match scope.resolve_path(path) {
                        // Text sink: binary goes loud, never the placeholder —
                        // a `b=$(cat blob)` capture holds real bytes; splicing
                        // `[binary: N bytes]` into "$b" would be silent loss.
                        Ok(value) => value_to_text_sink(&value).map_err(|e| anyhow::anyhow!("{e}")),
                        // Unset vars expand to empty; loud path errors surface.
                        Err(PathError::UndefinedRoot(_)) => Ok(String::new()),
                        Err(PathError::Absence(msg)) | Err(PathError::Shape(msg)) => {
                            Err(anyhow::anyhow!(msg))
                        }
                    }
                }
                StringPart::VarWithDefault { path, default } => {
                    let resolved = {
                        let scope = self.scope.read().await;
                        crate::interpreter::resolve_default(&scope, path)
                            .map_err(|msg| anyhow::anyhow!(msg))?
                    };
                    match resolved {
                        Some(value) => value_to_text_sink(&value).map_err(|e| anyhow::anyhow!("{e}")),
                        None => self.eval_string_parts_async(default).await,
                    }
                }
            StringPart::VarLength(path) => {
                let scope = self.scope.read().await;
                crate::interpreter::resolve_length(&scope, path)
                    .map(|n| n.to_string())
                    .map_err(|msg| anyhow::anyhow!(msg))
            }
            StringPart::Positional(n) => {
                let scope = self.scope.read().await;
                match scope.get_positional(*n) {
                    Some(s) => Ok(s.to_string()),
                    None => Ok(String::new()),
                }
            }
            StringPart::AllArgs => {
                let scope = self.scope.read().await;
                Ok(scope.all_args().join(" "))
            }
            StringPart::ArgCount => {
                let scope = self.scope.read().await;
                Ok(scope.arg_count().to_string())
            }
            StringPart::Arithmetic(expr) => {
                // Loud on purpose (GH #183): this used to be `Err(_) =>
                // Ok(String::new())`, silently splicing in "" for e.g.
                // `"$((1/0))"` — `echo "value: $((1/0))"` printed "value: "
                // at exit 0 instead of failing. Matches the bare (non-string)
                // `Expr::Arithmetic` arm above, which already propagates.
                self.eval_arithmetic_async(expr).await.map(|value| value.to_string())
            }
            StringPart::CommandSubst(stmts) => {
                // Snapshot scope, cwd, and session config — command
                // substitution in strings must not leak side effects (e.g.,
                // `"dir: $(cd /; pwd)"` must not change cwd, and
                // `"$(kaish-ignore clear)"` must not change the session's
                // ignore config) — matching how every other execution
                // context (background forks, scatter workers) already
                // isolates mutations (GH #139).
                // Boxed: this ~470 B scope snapshot is held across the nested
                // `$(…)` recursion await below, so inlining it grows every
                // command-substitution level's future (GH #48, item 4).
                let saved_scope = Box::new(self.scope.read().await.clone());
                let saved_ec = {
                    let ec = self.exec_ctx.read().await;
                    (
                        ec.cwd.clone(),
                        ec.prev_cwd.clone(),
                        ec.aliases.clone(),
                        ec.ignore_config.clone(),
                        ec.output_limit.clone(),
                    )
                };

                // Capture result without `?` — restore state unconditionally
                let run_result = self.execute_block_capturing(stmts).await;

                // Restore scope and cwd regardless of success/failure
                {
                    let mut scope = self.scope.write().await;
                    *scope = *saved_scope;
                    if let Ok(ref r) = run_result {
                        scope.set_last_result(r.clone());
                        scope.note_cmdsubst_code(r.code);
                    }
                }
                {
                    let mut ec = self.exec_ctx.write().await;
                    let (cwd, prev_cwd, aliases, ignore_config, output_limit) = saved_ec;
                    ec.cwd = cwd;
                    ec.prev_cwd = prev_cwd;
                    ec.aliases = aliases;
                    ec.ignore_config = ignore_config;
                    ec.output_limit = output_limit;
                }

                // A substitution's stderr belongs to the enclosing statement,
                // never to its value. Emit it before the value is built.
                if let Ok(ref r) = run_result {
                    self.emit_cmdsubst_stderr(&r.err).await;
                }

                // Now propagate the error
                let result = run_result?;

                // A held body stops the enclosing statement before its
                // missing output is spliced in (spec §I.5) — same conversion
                // and stash as the bare `$(…)` arm.

                // Embedding binary into a string is a text context: fail loud
                // rather than splice in U+FFFD garbage.
                match result.try_text_out() {
                    // Text wins when present — unchanged behavior.
                    Ok(s) if !s.is_empty() => Ok(s.trim_end_matches('\n').to_string()),
                    // `.out` is empty: a builtin/tool that set only structured
                    // `.data` must not silently evaporate to "" (SILENT DATA
                    // LOSS). Render it the same way a bare `"$x"`
                    // collection-valued variable renders — compact JSON for
                    // lists/records, plain form for scalars — by reusing
                    // `value_to_string` (the exact `StringPart::Var` helper
                    // above) so `"$(cmd)"` and `x=$(cmd); "$x"` display
                    // identically. No trailing-newline trim here: that's a
                    // text-path artifact, not applicable to a freshly
                    // rendered JSON/scalar string.
                    Ok(_) => match &result.data {
                        Some(data) => Ok(value_to_string(data)),
                        None => Ok(String::new()),
                    },
                    Err(e) => anyhow::bail!(
                        "command substitution in a string produced binary data ({e}) — \
                         pipe through base64/xxd"
                    ),
                }
            }
            StringPart::LastExitCode => {
                let scope = self.scope.read().await;
                Ok(scope.last_result().code.to_string())
            }
            StringPart::CurrentPid => {
                let scope = self.scope.read().await;
                Ok(scope.pid().to_string())
            }
        }
        })
    }

    /// Update the last result in scope.
    async fn update_last_result(&self, result: &ExecResult) {
        let mut scope = self.scope.write().await;
        scope.set_last_result(result.clone());
    }

    /// Drain accumulated pipeline stderr into a result.
    ///
    /// Called after each sub-statement inside control structures (`if`, `for`,
    /// `while`, `case`, `&&`, `||`) so that stderr appears incrementally rather
    /// than batching until the entire structure finishes.
    async fn drain_stderr_into(&self, result: &mut ExecResult) {
        let drained = {
            let mut receiver = self.stderr_receiver.lock().await;
            receiver.drain_lossy()
        };
        if !drained.is_empty() {
            if !result.err.is_empty() && !result.err.ends_with('\n') {
                result.err.push('\n');
            }
            result.err.push_str(&drained);
        }
    }

    /// Execute a user-defined function with local variable scoping.
    ///
    /// Functions push a new scope frame for local variables. Variables declared
    /// with `local` are scoped to the function; other assignments modify outer
    /// scopes (or create in root if new).
    async fn execute_user_tool(&self, def: ToolDef, args: &[Arg]) -> Result<ExecResult> {
        let _depth = self.enter_recursion("a shell function")?;

        // 1. Build function args from AST args (async to support command substitution)
        let tool_args = self.build_args_async(args, None).await?;

        // 2. Push a new scope frame for local variables
        {
            let mut scope = self.scope.write().await;
            scope.push_frame();
        }

        // 3. Save current positional parameters and set new ones for this function
        let saved_positional = {
            let mut scope = self.scope.write().await;
            let saved = scope.save_positional();

            // Set up new positional parameters ($0 = function name, $1, $2, ... = args)
            // `$1` is a text sink like any argv word, and `value_to_string`
            // cannot reproduce the source text — see `ToolArgs::positional_raw`.
            let positional_args: Vec<String> = tool_args.positional
                .iter()
                .enumerate()
                .map(|(i, v)| {
                    tool_args
                        .positional_raw
                        .get(&i)
                        .cloned()
                        .unwrap_or_else(|| value_to_string(v))
                })
                .collect();
            scope.set_positional(&def.name, positional_args);

            saved
        };

        // 3. Execute body statements with control flow handling
        // Accumulate output across statements (like sh)
        // Accumulate stdout as raw bytes so a binary-producing statement in a
        // function body survives instead of being lossy-decoded here.
        let mut accumulated_out: Vec<u8> = Vec::new();
        let mut accumulated_err = String::new();
        let mut last_code = 0i64;
        let mut last_data: Option<Value> = None;

        fn push_out(buf: &mut Vec<u8>, r: &ExecResult) {
            match r.out_bytes() {
                Some(b) => buf.extend_from_slice(b),
                None => buf.extend_from_slice(r.text_out().as_bytes()),
            }
        }

        // Track execution error for propagation after cleanup
        let mut exec_error: Option<anyhow::Error> = None;
        let mut exit_code: Option<i64> = None;

        for stmt in &def.body {
            match self.execute_stmt_flow(stmt).await {
                Ok(flow) => {
                    // Drain pipeline stderr after each sub-statement.
                    let drained = {
                        let mut receiver = self.stderr_receiver.lock().await;
                        receiver.drain_lossy()
                    };
                    if !drained.is_empty() {
                        accumulated_err.push_str(&drained);
                    }

                    match flow {
                        ControlFlow::Normal(r) => {
                            push_out(&mut accumulated_out, &r);
                            accumulated_err.push_str(&r.err);
                            last_code = r.code;
                            // A structured VIEW of printed text does not escape as the
                    // substitution's value — `$(cut -f2 f)` is the text `cut`
                    // printed, the same as `$(awk '{print $2}' f)`.
                    last_data = if r.data_is_value { r.data } else { None };
                        }
                        ControlFlow::Return { value } => {
                            push_out(&mut accumulated_out, &value);
                            accumulated_err.push_str(&value.err);
                            last_code = value.code;
                            last_data = if value.data_is_value { value.data } else { None };
                            break;
                        }
                        ControlFlow::Exit { code, result: r } => {
                            push_out(&mut accumulated_out, &r);
                            accumulated_err.push_str(&r.err);
                            exit_code = Some(code);
                            break;
                        }
                        ControlFlow::Break { result: r, .. } | ControlFlow::Continue { result: r, .. } => {
                            push_out(&mut accumulated_out, &r);
                            accumulated_err.push_str(&r.err);
                            last_code = r.code;
                            last_data = if r.data_is_value { r.data } else { None };
                        }
                    }
                }
                Err(e) => {
                    exec_error = Some(e);
                    break;
                }
            }
        }

        // 4. Pop scope frame and restore original positional parameters (unconditionally)
        {
            let mut scope = self.scope.write().await;
            scope.pop_frame();
            scope.set_positional(saved_positional.0, saved_positional.1);
        }

        // 5. Propagate error or exit after cleanup
        if let Some(e) = exec_error {
            return Err(e);
        }
        let code = exit_code.unwrap_or(last_code);
        let mut result = ExecResult::success_text_or_bytes(accumulated_out).with_code(code);
        result.err = accumulated_err;
        // Whatever survived the gate above IS a value, so the result says so
        // and a further `$( )` around this one keeps it typed.
        result.data_is_value = last_data.is_some();
        result.data = last_data;
        Ok(result)
    }

    fn enter_recursion(&self, what: &str) -> Result<RecursionGuard<'_>> {
        let depth = self.recursion_depth.fetch_add(1, Ordering::Relaxed) + 1;
        let guard = RecursionGuard { counter: &self.recursion_depth };
        if depth > MAX_RECURSION_DEPTH {
            return Err(anyhow::anyhow!(
                "maximum recursion depth ({MAX_RECURSION_DEPTH}) exceeded in {what} — \
                 a runaway or mutually recursive script (deeply nested $(…), or \
                 functions/scripts that call each other without a base case) was \
                 stopped before it could overflow the stack"
            ));
        }
        Ok(guard)
    }

    /// Hand a finished command substitution's stderr to the kernel's stderr
    /// stream.
    ///
    /// bash gives `$(…)` the shell's own fd 2, so a substitution's stderr goes
    /// straight to the terminal and is never captured alongside its stdout.
    /// kaish runs the block captured, so the equivalent is to write the block's
    /// stderr to the same channel pipeline stages use: the enclosing
    /// statement's drain folds it into that statement's `err`, ahead of the
    /// statement's own output. `x=$(cat /nope)` kept the exit code and lost the
    /// reason until this existed.
    ///
    /// Nesting composes without a stack. Each level drains at its own statement
    /// boundary, so an inner substitution's stderr is already inside the outer
    /// block's result by the time this runs for the outer one — which is why it
    /// is written exactly once, here, rather than also accumulated by callers.
    /// Hand a nested command's stderr to the enclosing statement.
    ///
    /// Two callers, one rule: a command substitution's stderr is not part of
    /// its value, and a condition command's stderr is not part of its
    /// truthiness. Both belong to the statement the author wrote.
    async fn emit_cmdsubst_stderr(&self, err: &str) {
        if err.is_empty() {
            return;
        }
        // Terminate the chunk. Builtins are inconsistent about a trailing
        // newline (`cat`'s failure message has none), and two substitutions in
        // one statement would otherwise concatenate into a single unreadable
        // line: `x="$(cat /a)$(cat /b)"` produced both messages run together.
        // The statement drain already normalizes this boundary the same way
        // when it joins drained stderr to a statement's own.
        let terminated;
        let err = if err.ends_with('\n') {
            err
        } else {
            terminated = format!("{err}\n");
            &terminated
        };
        match self.exec_ctx.read().await.stderr.as_ref() {
            Some(stream) => stream.write_str(err),
            // The kernel seeds this stream in both `new` and `fork`, so it is
            // always present on the kernel's own context; the `Option` exists
            // for tool contexts built elsewhere. If it is ever absent there is
            // no channel to carry the bytes and no drain to collect them, which
            // is the same condition under which every pipeline stage's stderr
            // is dropped — so record it rather than failing an interactive
            // shell over it.
            None => tracing::warn!("command substitution stderr dropped: no stderr stream"),
        }
    }

    async fn execute_block_capturing(&self, stmts: &[Stmt]) -> Result<ExecResult> {
        let _depth = self.enter_recursion("command substitution")?;
        // Accumulate stdout as raw bytes so a binary-producing statement
        // (`$(dd …)`, `$(base64 -d …)`) isn't lossy-decoded here before the
        // caller can preserve it. The final result is text iff valid UTF-8.
        let mut accumulated_out: Vec<u8> = Vec::new();
        let mut accumulated_err = String::new();
        let mut last_code = 0i64;
        let mut last_data: Option<Value> = None;

        // Append a statement's stdout as raw bytes (binary) or its UTF-8 bytes.
        fn push_out(buf: &mut Vec<u8>, r: &ExecResult) {
            match r.out_bytes() {
                Some(b) => buf.extend_from_slice(b),
                None => buf.extend_from_slice(r.text_out().as_bytes()),
            }
        }

        for stmt in stmts {
            let flow = self.execute_stmt_flow(stmt).await?;

            // Drain pipeline stderr after each sub-statement (incremental, like
            // the control-structure and function-body executors).
            let drained = {
                let mut receiver = self.stderr_receiver.lock().await;
                receiver.drain_lossy()
            };
            if !drained.is_empty() {
                accumulated_err.push_str(&drained);
            }

            match flow {
                ControlFlow::Normal(r)
                | ControlFlow::Break { result: r, .. }
                | ControlFlow::Continue { result: r, .. } => {
                    push_out(&mut accumulated_out, &r);
                    accumulated_err.push_str(&r.err);
                    last_code = r.code;
                    last_data = if r.data_is_value { r.data } else { None };
                }
                ControlFlow::Return { value } => {
                    push_out(&mut accumulated_out, &value);
                    accumulated_err.push_str(&value.err);
                    last_code = value.code;
                    last_data = if value.data_is_value { value.data } else { None };
                    break;
                }
                ControlFlow::Exit { code, result: r } => {
                    push_out(&mut accumulated_out, &r);
                    accumulated_err.push_str(&r.err);
                    last_code = code;
                    break;
                }
            }
        }

        let mut result = ExecResult::success_text_or_bytes(accumulated_out).with_code(last_code);
        result.err = accumulated_err;
        // Whatever survived the gate above IS a value, so the result says so
        // and a further `$( )` around this one keeps it typed.
        result.data_is_value = last_data.is_some();
        result.data = last_data;
        Ok(result)
    }

    /// Evaluate `$(( text ))`'s content. Takes the sync fast path
    /// (`arithmetic::eval_sync` under one scope read lock) when no `$(...)`
    /// is reachable in the parsed tree; otherwise walks it with
    /// `Self::eval_arith_expr_async`, which can run a `$(...)` operand and
    /// never runs one on the unselected side of `&&`/`||`/`?:`.
    async fn eval_arithmetic_async(&self, text: &str) -> Result<i64> {
        let ast = crate::arithmetic::parse(text).map_err(|e| anyhow::anyhow!("arithmetic error: {e}"))?;
        if ast.contains_command_subst() {
            self.eval_arith_expr_async(&ast).await
        } else {
            let scope = self.scope.read().await;
            crate::arithmetic::eval_sync(&ast, &scope).map_err(|e| anyhow::anyhow!("arithmetic error: {e}"))
        }
    }

    /// Async recursive walk over a parsed `$(( ))` tree. Boxed for the same
    /// reason as `Self::eval_expr_async`: the recursion is unbounded by
    /// the type system, so a fixed-depth stack frame can't hold it. Each
    /// leaf takes its own short `self.scope` read lock rather than one held
    /// across the whole walk — `Expansion::CommandSubst` runs through
    /// `Self::execute_block_capturing`, which takes its own scope lock
    /// internally, so a lock held here across that await would deadlock.
    fn eval_arith_expr_async<'a>(
        &'a self,
        expr: &'a crate::arithmetic::ArithExpr,
    ) -> std::pin::Pin<Box<dyn std::future::Future<Output = Result<i64>> + Send + 'a>> {
        use crate::arithmetic::{ArithExpr, BinOp};
        Box::pin(async move {
            match expr {
                ArithExpr::Int(n) => Ok(*n),
                ArithExpr::Expansion(e) => self.eval_arith_expansion_async(e).await,
                ArithExpr::Subscript { root, indices } => {
                    let mut values = Vec::with_capacity(indices.len());
                    for index in indices {
                        values.push(self.eval_arith_expr_async(index).await?);
                    }
                    let scope = self.scope.read().await;
                    crate::arithmetic::resolve_subscript_sync(&scope, root, &values)
                        .map_err(|e| anyhow::anyhow!("arithmetic error: {e}"))
                }
                ArithExpr::BasedExpansion { base, expansion } => {
                    let text = self.eval_arith_expansion_text_async(expansion).await?;
                    let (label, verb) = crate::arithmetic::expansion_label(expansion);
                    crate::arithmetic::based_value(*base, &text, &label, verb, false)
                        .map_err(|e| anyhow::anyhow!("arithmetic error: {e}"))
                }
                // `-base#$expansion`: fold the sign into the range check
                // (see `arithmetic::based_value`'s doc comment) instead of
                // evaluating positive then negating, which can never reach
                // i64::MIN.
                ArithExpr::Unary { op: crate::arithmetic::UnOp::Neg, operand }
                    if matches!(operand.as_ref(), ArithExpr::BasedExpansion { .. }) =>
                {
                    let ArithExpr::BasedExpansion { base, expansion } = operand.as_ref() else {
                        unreachable!("guarded by the match arm's pattern")
                    };
                    let text = self.eval_arith_expansion_text_async(expansion).await?;
                    let (label, verb) = crate::arithmetic::expansion_label(expansion);
                    crate::arithmetic::based_value(*base, &text, &label, verb, true)
                        .map_err(|e| anyhow::anyhow!("arithmetic error: {e}"))
                }
                ArithExpr::Unary { op, operand } => {
                    let v = self.eval_arith_expr_async(operand).await?;
                    crate::arithmetic::apply_unary(*op, v).map_err(|e| anyhow::anyhow!("arithmetic error: {e}"))
                }
                // `&&`/`||` short-circuit: the unselected side's `$(...)`
                // must not run (docs/LANGUAGE.md, "Operators").
                ArithExpr::Binary { op: BinOp::And, left, right } => {
                    if self.eval_arith_expr_async(left).await? == 0 {
                        Ok(0)
                    } else {
                        Ok(if self.eval_arith_expr_async(right).await? != 0 { 1 } else { 0 })
                    }
                }
                ArithExpr::Binary { op: BinOp::Or, left, right } => {
                    if self.eval_arith_expr_async(left).await? != 0 {
                        Ok(1)
                    } else {
                        Ok(if self.eval_arith_expr_async(right).await? != 0 { 1 } else { 0 })
                    }
                }
                ArithExpr::Binary { op, left, right } => {
                    let l = self.eval_arith_expr_async(left).await?;
                    let r = self.eval_arith_expr_async(right).await?;
                    crate::arithmetic::apply_binary(*op, l, r).map_err(|e| anyhow::anyhow!("arithmetic error: {e}"))
                }
                ArithExpr::Ternary { cond, then_branch, else_branch } => {
                    if self.eval_arith_expr_async(cond).await? != 0 {
                        self.eval_arith_expr_async(then_branch).await
                    } else {
                        self.eval_arith_expr_async(else_branch).await
                    }
                }
            }
        })
    }

    fn eval_arith_expansion_async<'a>(
        &'a self,
        expansion: &'a crate::arithmetic::Expansion,
    ) -> std::pin::Pin<Box<dyn std::future::Future<Output = Result<i64>> + Send + 'a>> {
        use crate::arithmetic::Expansion;
        Box::pin(async move {
            match expansion {
                Expansion::Var(name) => {
                    let scope = self.scope.read().await;
                    crate::arithmetic::resolve_var_sync(&scope, name)
                        .map_err(|e| anyhow::anyhow!("arithmetic error: {e}"))
                }
                Expansion::BracedPath { root, brackets } => {
                    let scope = self.scope.read().await;
                    let value = crate::arithmetic::braced_path_value(&scope, root, brackets)
                        .map_err(|e| anyhow::anyhow!("arithmetic error: {e}"))?;
                    crate::arithmetic::value_to_arith(&value, root)
                        .map_err(|e| anyhow::anyhow!("arithmetic error: {e}"))
                }
                Expansion::BracedDefault { root, brackets, default } => {
                    let resolved = {
                        let scope = self.scope.read().await;
                        crate::arithmetic::braced_default_operand(&scope, root, brackets)
                            .map_err(|e| anyhow::anyhow!("arithmetic error: {e}"))?
                    };
                    match resolved {
                        None => {
                            let default_expr = crate::arithmetic::parse(default)
                                .map_err(|e| anyhow::anyhow!("arithmetic error: {e}"))?;
                            self.eval_arith_expr_async(&default_expr).await
                        }
                        Some(value) => crate::arithmetic::value_to_arith(&value, root)
                            .map_err(|e| anyhow::anyhow!("arithmetic error: {e}")),
                    }
                }
                Expansion::LastExitCode => {
                    let scope = self.scope.read().await;
                    Ok(scope.last_result().code)
                }
                Expansion::CurrentPid => {
                    let scope = self.scope.read().await;
                    Ok(scope.pid() as i64)
                }
                Expansion::CommandSubst(stmts) => self.run_arith_command_subst(stmts).await,
                Expansion::Nested(inner) => self.eval_arith_expr_async(inner).await,
            }
        })
    }

    /// The expansion's rendered VALUE, for `base#<expansion>` — mirrors
    /// `crate::arithmetic::expansion_text_sync`, async so `$(...)` can
    /// run for real. Never routes through `Self::eval_arith_expansion_async`
    /// (the arithmetically-coerced form): that coercion refuses a leading
    /// zero, which is exactly what `10#$m`/`10#$(date +%m)` exist to escape.
    fn eval_arith_expansion_text_async<'a>(
        &'a self,
        expansion: &'a crate::arithmetic::Expansion,
    ) -> std::pin::Pin<Box<dyn std::future::Future<Output = Result<String>> + Send + 'a>> {
        use crate::arithmetic::Expansion;
        Box::pin(async move {
            match expansion {
                Expansion::Var(name) => {
                    let scope = self.scope.read().await;
                    if let Ok(index) = name.parse::<usize>() {
                        return match scope.get_positional(index) {
                            Some(s) => Ok(s.to_string()),
                            None => Err(anyhow::anyhow!(
                                "arithmetic error: {}",
                                crate::arithmetic::unset_error(name)
                            )),
                        };
                    }
                    match scope.get(name) {
                        Some(v) => Ok(value_to_string(v)),
                        None => Err(anyhow::anyhow!(
                            "arithmetic error: {}",
                            crate::arithmetic::unset_error(name)
                        )),
                    }
                }
                Expansion::BracedPath { root, brackets } => {
                    let scope = self.scope.read().await;
                    crate::arithmetic::braced_path_value(&scope, root, brackets)
                        .map(|v| value_to_string(&v))
                        .map_err(|e| anyhow::anyhow!("arithmetic error: {e}"))
                }
                Expansion::BracedDefault { root, brackets, default } => {
                    let resolved = {
                        let scope = self.scope.read().await;
                        crate::arithmetic::braced_default_operand(&scope, root, brackets)
                            .map_err(|e| anyhow::anyhow!("arithmetic error: {e}"))?
                    };
                    match resolved {
                        // Stays in TEXT mode when the default is itself a
                        // single expansion — see the sync twin,
                        // `expansion_text_sync`, for why.
                        None => {
                            let default_expr = crate::arithmetic::parse(default)
                                .map_err(|e| anyhow::anyhow!("arithmetic error: {e}"))?;
                            match default_expr {
                                crate::arithmetic::ArithExpr::Expansion(e) => {
                                    self.eval_arith_expansion_text_async(&e).await
                                }
                                default_expr => {
                                    let n = self.eval_arith_expr_async(&default_expr).await?;
                                    Ok(n.to_string())
                                }
                            }
                        }
                        Some(value) => Ok(value_to_string(&value)),
                    }
                }
                Expansion::LastExitCode => {
                    let scope = self.scope.read().await;
                    Ok(scope.last_result().code.to_string())
                }
                Expansion::CurrentPid => {
                    let scope = self.scope.read().await;
                    Ok(scope.pid().to_string())
                }
                Expansion::CommandSubst(stmts) => self.run_arith_command_subst_text(stmts).await,
                Expansion::Nested(inner) => {
                    let n = self.eval_arith_expr_async(inner).await?;
                    Ok(n.to_string())
                }
            }
        })
    }

    /// Run a `$(...)` operand inside `$(( ))`. Mirrors `Expr::CommandSubst`'s
    /// isolation (scope/cwd/config snapshot-and-restore, stderr forwarded to
    /// the enclosing statement) — the same substitution mechanism, just
    /// coerced to an integer instead of spliced in as text.
    async fn run_arith_command_subst(&self, stmts: &[Stmt]) -> Result<i64> {
        let text = self.run_arith_command_subst_text(stmts).await?;
        crate::arithmetic::parse_command_output(&text, "$(...)")
            .map_err(|e| anyhow::anyhow!("arithmetic error: {e}"))
    }

    /// Run a `$(...)` operand and return its printed text — the shared half
    /// of `Self::run_arith_command_subst` (a bare operand, coerced to an
    /// integer) and the `base#$(...)` case (the text is read as digits in a
    /// base, never coerced first — see `crate::arithmetic::based_value`).
    async fn run_arith_command_subst_text(&self, stmts: &[Stmt]) -> Result<String> {
        let saved_scope = Box::new(self.scope.read().await.clone());
        let saved_ec = {
            let ec = self.exec_ctx.read().await;
            (
                ec.cwd.clone(),
                ec.prev_cwd.clone(),
                ec.aliases.clone(),
                ec.ignore_config.clone(),
                ec.output_limit.clone(),
            )
        };

        let run_result = self.execute_block_capturing(stmts).await;

        {
            let mut scope = self.scope.write().await;
            *scope = *saved_scope;
            if let Ok(ref r) = run_result {
                scope.set_last_result(r.clone());
                scope.note_cmdsubst_code(r.code);
            }
        }
        {
            let mut ec = self.exec_ctx.write().await;
            let (cwd, prev_cwd, aliases, ignore_config, output_limit) = saved_ec;
            ec.cwd = cwd;
            ec.prev_cwd = prev_cwd;
            ec.aliases = aliases;
            ec.ignore_config = ignore_config;
            ec.output_limit = output_limit;
        }

        if let Ok(ref r) = run_result {
            self.emit_cmdsubst_stderr(&r.err).await;
        }

        let result = run_result?;
        if result.out_bytes().is_some() {
            return Err(anyhow::anyhow!(
                "arithmetic error: `$(...)` printed binary data; the command must print one integer"
            ));
        }
        Ok(result.text_out().trim_end_matches('\n').to_string())
    }

    /// Execute the `source` / `.` command to include and run a script.
    ///
    /// Unlike regular tool execution, `source` executes in the CURRENT scope,
    /// allowing the sourced script to set variables and modify shell state.
    async fn execute_source(&self, args: &[Arg]) -> Result<ExecResult> {
        // `source`/`.` is the fourth dynamic re-entry point: it runs the
        // sourced file's statements inline via `execute_stmt_flow`, so a file
        // that sources itself recurses unbounded just like a runaway function
        // (GH #46). It's intercepted as a special form *before* the other
        // guarded paths, so it needs its own guard.
        let _depth = self.enter_recursion("source")?;

        // Get the file path from the first positional argument
        let tool_args = self.build_args_async(args, None).await?;
        let path = match tool_args.positional.first() {
            Some(Value::String(s)) => s.clone(),
            Some(v) => value_to_string(v),
            None => {
                return Ok(ExecResult::failure(1, "source: missing filename"));
            }
        };

        // Resolve path relative to cwd
        let full_path = {
            let ctx = self.exec_ctx.read().await;
            if path.starts_with('/') {
                std::path::PathBuf::from(&path)
            } else {
                ctx.cwd.join(&path)
            }
        };

        // Read file content via backend
        let content = {
            let ctx = self.exec_ctx.read().await;
            match ctx.backend.read(&full_path, None).await {
                Ok(bytes) => {
                    String::from_utf8(bytes).map_err(|e| {
                        anyhow::anyhow!("source: {}: invalid UTF-8: {}", path, e)
                    })?
                }
                Err(e) => {
                    return Ok(ExecResult::failure(
                        1,
                        format!("source: {}: {}", path, e),
                    ));
                }
            }
        };

        // Parse the content
        let program = match crate::parser::parse(&content) {
            Ok(p) => p,
            Err(errors) => {
                let msg = errors
                    .iter()
                    .map(|e| format!("{}:{}: {}", path, e.span.start, e.message))
                    .collect::<Vec<_>>()
                    .join("\n");
                return Ok(ExecResult::failure(1, format!("source: {}", msg)));
            }
        };

        // Execute each statement in the CURRENT scope (not isolated), accumulating
        // stdout/stderr across statements like `execute_user_tool` — a sourced
        // script's earlier statements must not be silently dropped in favor of
        // just the last one.
        fn push_out(buf: &mut Vec<u8>, r: &ExecResult) {
            match r.out_bytes() {
                Some(b) => buf.extend_from_slice(b),
                None => buf.extend_from_slice(r.text_out().as_bytes()),
            }
        }

        let mut accumulated_out: Vec<u8> = Vec::new();
        let mut accumulated_err = String::new();
        let mut last_code = 0i64;
        let mut last_data: Option<Value> = None;

        for stmt in program.statements {
            if matches!(stmt, crate::ast::Stmt::Empty) {
                continue;
            }

            match self.execute_stmt_flow(&stmt).await {
                Ok(flow) => {
                    let drained = {
                        let mut receiver = self.stderr_receiver.lock().await;
                        receiver.drain_lossy()
                    };
                    if !drained.is_empty() {
                        accumulated_err.push_str(&drained);
                    }
                    match flow {
                        ControlFlow::Normal(r) => {
                            push_out(&mut accumulated_out, &r);
                            accumulated_err.push_str(&r.err);
                            last_code = r.code;
                            last_data = if r.data_is_value { r.data.clone() } else { None };
                            self.update_last_result(&r).await;
                        }
                        ControlFlow::Break { .. } | ControlFlow::Continue { .. } => {
                            return Err(anyhow::anyhow!(
                                "source: {}: unexpected break/continue outside loop",
                                path
                            ));
                        }
                        ControlFlow::Return { value } => {
                            push_out(&mut accumulated_out, &value);
                            accumulated_err.push_str(&value.err);
                            let mut result = ExecResult::success_text_or_bytes(accumulated_out)
                                .with_code(value.code);
                            result.err = accumulated_err;
                            result.data = value.data;
                            return Ok(result);
                        }
                        ControlFlow::Exit { code, result: r } => {
                            push_out(&mut accumulated_out, &r);
                            accumulated_err.push_str(&r.err);
                            let mut result =
                                ExecResult::success_text_or_bytes(accumulated_out).with_code(code);
                            result.err = accumulated_err;
                            // Whatever survived the gate above IS a value, so the result says so
        // and a further `$( )` around this one keeps it typed.
        result.data_is_value = last_data.is_some();
        result.data = last_data;
                            return Ok(result);
                        }
                    }
                }
                Err(e) => {
                    return Err(e.context(format!("source: {}", path)));
                }
            }
        }

        let mut result = ExecResult::success_text_or_bytes(accumulated_out).with_code(last_code);
        result.err = accumulated_err;
        // Whatever survived the gate above IS a value, so the result says so
        // and a further `$( )` around this one keeps it typed.
        result.data_is_value = last_data.is_some();
        result.data = last_data;
        Ok(result)
    }

    /// Try to execute a script from PATH directories.
    ///
    /// Searches PATH for `{name}.kai` files and executes them in isolated scope
    /// (like user-defined tools). Returns None if no script is found.
    async fn try_execute_script(&self, name: &str, args: &[Arg]) -> Result<Option<ExecResult>> {
        // Held across the PATH probe *and* body execution: a `.kai` sourcing a
        // `.kai` re-enters here, and that nesting is what must be bounded (#46).
        // A non-script command pays only a transient, balanced increment during
        // the probe before falling through to the external path.
        let _depth = self.enter_recursion("a .kai script")?;

        // Get PATH from scope (default to "/bin")
        let path_value = {
            let scope = self.scope.read().await;
            scope
                .get("PATH")
                .map(value_to_string)
                .unwrap_or_else(|| "/bin".to_string())
        };

        // Search PATH directories for script
        for dir in path_value.split(':') {
            if dir.is_empty() {
                continue;
            }

            // Build script path: {dir}/{name}.kai
            let script_path = PathBuf::from(dir).join(format!("{}.kai", name));

            // Check if script exists
            let exists = {
                let ctx = self.exec_ctx.read().await;
                ctx.backend.exists(&script_path).await
            };

            if !exists {
                continue;
            }

            // Read script content
            let content = {
                let ctx = self.exec_ctx.read().await;
                match ctx.backend.read(&script_path, None).await {
                    Ok(bytes) => match String::from_utf8(bytes) {
                        Ok(s) => s,
                        Err(e) => {
                            return Ok(Some(ExecResult::failure(
                                1,
                                format!("{}: invalid UTF-8: {}", script_path.display(), e),
                            )));
                        }
                    },
                    Err(e) => {
                        return Ok(Some(ExecResult::failure(
                            1,
                            format!("{}: {}", script_path.display(), e),
                        )));
                    }
                }
            };

            // Parse the script
            let program = match crate::parser::parse(&content) {
                Ok(p) => p,
                Err(errors) => {
                    let msg = errors
                        .iter()
                        .map(|e| format!("{}:{}: {}", script_path.display(), e.span.start, e.message))
                        .collect::<Vec<_>>()
                        .join("\n");
                    return Ok(Some(ExecResult::failure(1, msg)));
                }
            };

            // Build tool_args from args (async for command substitution support)
            let tool_args = self.build_args_async(args, None).await?;

            // Create isolated scope (like user tools). The trash rail and
            // errexit are NOT session state a script may shed: a `.kai`
            // script starting from a blank scope would otherwise overwrite
            // and delete without the recovery net `set -o trash` promised,
            // or run past a gating failure the caller turned errexit on for.
            // Carry both.
            let mut isolated_scope = Scope::new();
            {
                let scope = self.scope.read().await;
                isolated_scope.set_pid(scope.pid());
                isolated_scope.set_trash_enabled(scope.trash_enabled());
                isolated_scope.set_trash_max_size(scope.trash_max_size());
                isolated_scope.set_error_exit(scope.error_exit_enabled());
            }

            // Set up positional parameters ($0 = script name, $1, $2, ... = args)
            // Same source-text fidelity as the function-call site above.
            let positional_args: Vec<String> = tool_args.positional
                .iter()
                .enumerate()
                .map(|(i, v)| {
                    tool_args
                        .positional_raw
                        .get(&i)
                        .cloned()
                        .unwrap_or_else(|| value_to_string(v))
                })
                .collect();
            isolated_scope.set_positional(name, positional_args);

            // Save current scope and swap with isolated scope
            let original_scope = {
                let mut scope = self.scope.write().await;
                std::mem::replace(&mut *scope, isolated_scope)
            };

            // Execute script statements — accumulate stdout/stderr across
            // statements like `execute_user_tool`, rather than keeping only the
            // last one's result.
            fn push_out(buf: &mut Vec<u8>, r: &ExecResult) {
                match r.out_bytes() {
                    Some(b) => buf.extend_from_slice(b),
                    None => buf.extend_from_slice(r.text_out().as_bytes()),
                }
            }

            let mut accumulated_out: Vec<u8> = Vec::new();
            let mut accumulated_err = String::new();
            let mut last_code = 0i64;
            let mut last_data: Option<Value> = None;
            let mut exec_error: Option<anyhow::Error> = None;
            let mut exit_code: Option<i64> = None;

            for stmt in program.statements {
                if matches!(stmt, crate::ast::Stmt::Empty) {
                    continue;
                }

                match self.execute_stmt_flow(&stmt).await {
                    Ok(flow) => {
                        let drained = {
                            let mut receiver = self.stderr_receiver.lock().await;
                            receiver.drain_lossy()
                        };
                        if !drained.is_empty() {
                            accumulated_err.push_str(&drained);
                        }
                        match flow {
                            ControlFlow::Normal(r) => {
                                push_out(&mut accumulated_out, &r);
                                accumulated_err.push_str(&r.err);
                                last_code = r.code;
                                last_data = if r.data_is_value { r.data } else { None };
                            }
                            ControlFlow::Return { value } => {
                                push_out(&mut accumulated_out, &value);
                                accumulated_err.push_str(&value.err);
                                last_code = value.code;
                                last_data = if value.data_is_value { value.data } else { None };
                                break;
                            }
                            ControlFlow::Exit { code, result: r } => {
                                push_out(&mut accumulated_out, &r);
                                accumulated_err.push_str(&r.err);
                                exit_code = Some(code);
                                break;
                            }
                            ControlFlow::Break { result: r, .. } | ControlFlow::Continue { result: r, .. } => {
                                push_out(&mut accumulated_out, &r);
                                accumulated_err.push_str(&r.err);
                                last_code = r.code;
                                last_data = if r.data_is_value { r.data } else { None };
                            }
                        }
                    }
                    Err(e) => {
                        exec_error = Some(e);
                        break;
                    }
                }
            }

            // Restore original scope unconditionally
            {
                let mut scope = self.scope.write().await;
                *scope = original_scope;
            }

            // Propagate error or exit after cleanup
            if let Some(e) = exec_error {
                return Err(e.context(format!("script: {}", script_path.display())));
            }
            let code = exit_code.unwrap_or(last_code);
            let mut result = ExecResult::success_text_or_bytes(accumulated_out).with_code(code);
            result.err = accumulated_err;
            // Whatever survived the gate above IS a value, so the result says so
        // and a further `$( )` around this one keeps it typed.
        result.data_is_value = last_data.is_some();
        result.data = last_data;
            return Ok(Some(result));
        }

        // No script found
        Ok(None)
    }

    /// Try to execute an external command from PATH.
    ///
    /// This is the fallback when no builtin or user-defined tool matches.
    /// External commands receive a clean argv (flags preserved in their original format).
    ///
    /// # Requirements
    /// - Command must be found in PATH
    /// - Current working directory must be on a real filesystem (not virtual like /v)
    ///
    /// # Returns
    /// - [`ExternalCommandOutcome::Ran`] if a command was resolved and run (any exit code)
    /// - [`ExternalCommandOutcome::NotFound`] if nothing on PATH matches — the
    ///   caller should still try a backend-registered tool of the same name
    /// - [`ExternalCommandOutcome::Unavailable`] if kaish will not attempt a
    ///   PATH lookup or spawn at all; a backend tool of the same name is a
    ///   separate capability and is still tried by the caller
    /// - `Err` on execution errors
    #[cfg(not(feature = "subprocess"))]
    async fn try_execute_external(&self, _name: &str, _args: &[Arg]) -> Result<ExternalCommandOutcome> {
        Ok(ExternalCommandOutcome::Unavailable(ExternalCommandsUnavailable::NotCompiled))
    }

    /// Try to execute an external command from PATH.
    #[cfg(feature = "subprocess")]
    async fn try_execute_external(&self, name: &str, args: &[Arg]) -> Result<ExternalCommandOutcome> {
        if !self.allow_external_commands {
            return Ok(ExternalCommandOutcome::Unavailable(ExternalCommandsUnavailable::ConfiguredOff));
        }
        Ok(match Box::pin(self.try_execute_external_on_path(name, args)).await? {
            Some(result) => ExternalCommandOutcome::Ran(Box::new(result)),
            None => ExternalCommandOutcome::NotFound,
        })
    }

    /// The actual PATH lookup + spawn, once the caller has confirmed external
    /// commands are allowed at all. Unchanged from before the disabled/
    /// not-compiled cases were split out — still `Option`-shaped: `None`
    /// means "bare name, nothing on PATH", the one case where the caller
    /// should keep looking elsewhere.
    #[cfg(feature = "subprocess")]
    #[tracing::instrument(level = "debug", skip(self, args), fields(command = %name))]
    async fn try_execute_external_on_path(&self, name: &str, args: &[Arg]) -> Result<Option<ExecResult>> {
        // Get the shell's cwd and its real filesystem location, if any. A
        // `None` real path means the cwd is virtual (a CoW overlay, an
        // in-memory VFS mount, `/dev`, …) — there's nowhere for a child OS
        // process to run. Don't bail out here: a bare command name that isn't
        // in PATH at all is a genuine "not found" regardless of cwd, and the
        // virtual-cwd error would blame the wrong thing for that case. Once
        // the command actually resolves, `real_cwd` is checked again below
        // and the honest reason is given then (issue #181).
        let (cwd, real_cwd) = {
            let ctx = self.exec_ctx.read().await;
            (ctx.cwd.clone(), ctx.backend.resolve_real_path(&ctx.cwd))
        };

        let executable = if name.contains('/') {
            // Resolve relative paths (./script, ../bin/tool) against the shell's cwd
            let resolved = if std::path::Path::new(name).is_absolute() {
                std::path::PathBuf::from(name)
            } else {
                match &real_cwd {
                    Some(real_cwd) => real_cwd.join(name),
                    // A relative path can't be resolved without a real cwd to
                    // join against, so we can't even tell whether it would
                    // exist — name the actual blocker instead of a
                    // misleading "No such file or directory".
                    None => return Ok(Some(virtual_cwd_error(name, &cwd))),
                }
            };
            if !resolved.exists() {
                return Ok(Some(ExecResult::failure(
                    127,
                    format!("{}: No such file or directory", name),
                )));
            }
            if !resolved.is_file() {
                return Ok(Some(ExecResult::failure(
                    126,
                    format!("{}: Is a directory", name),
                )));
            }
            #[cfg(unix)]
            {
                use std::os::unix::fs::PermissionsExt;
                let mode = std::fs::metadata(&resolved)
                    .map(|m| m.permissions().mode())
                    .unwrap_or(0);
                if mode & 0o111 == 0 {
                    return Ok(Some(ExecResult::failure(
                        126,
                        format!("{}: Permission denied", name),
                    )));
                }
            }
            resolved.to_string_lossy().into_owned()
        } else {
            // Get PATH from scope only. The kernel never reads OS env: a
            // frontend that wants host PATH seeds it via initial_vars (the REPL
            // does, with os_env_vars()). No PATH in scope → nothing resolves.
            let path_var = {
                let scope = self.scope.read().await;
                scope.get("PATH").map(value_to_string).unwrap_or_default()
            };

            // Resolve command in PATH
            match resolve_in_path(name, &path_var) {
                Some(path) => path,
                None => return Ok(None), // Not found - let caller handle error
            }
        };

        // The executable resolved — found in PATH, or a path that exists and
        // is executable — but there's still nowhere to run it without a real
        // cwd to spawn the child process in.
        let real_cwd = match real_cwd {
            Some(p) => p,
            None => return Ok(Some(virtual_cwd_error(name, &cwd))),
        };

        tracing::debug!(executable = %executable, "resolved external command");

        // Build flat argv (preserves flag format)
        let argv = self.build_args_flat(args).await?;

        // Get stdin sources: a streaming `pipe_stdin` (an inter-stage pipeline
        // pipe, or a frontend-seeded process-stdin pipe) and/or a buffered
        // byte vector. Take both out under the lock but do NOT drain here — a
        // pipe read can block on its producer (a still-running upstream stage),
        // so draining before spawn would serialize the pipeline (deadlocking
        // `sleep 60 | extern`). The pipe is streamed to the child *after* spawn.
        // `set_stdin` clears `pipe_stdin`, so a redirect-set buffer and a pipe
        // are mutually exclusive in practice; prefer the pipe.
        let (pipe_stdin, stdin_bytes) = {
            let mut ctx = self.exec_ctx.write().await;
            (ctx.pipe_stdin.take(), ctx.take_stdin())
        };
        let has_stdin = pipe_stdin.is_some() || stdin_bytes.is_some();

        // The cancel token, the kill grace, and the background job all come
        // from `self.exec_ctx`, which `dispatch_command` populates from the
        // inbound ctx on every dispatch. That is what makes the `timeout`
        // builtin's swapped child token reach the wait_or_kill discipline —
        // reading `self.cancel_token` would give the kernel-wide token and
        // miss the timeout's child cascade.
        //
        // In interactive mode, standalone or last-in-pipeline commands inherit
        // the terminal's stdout/stderr so output streams in real-time.
        // First/middle commands must capture stdout for the pipe — same as bash.
        let (pipeline_position, spawn_ctx) = {
            let ctx = self.exec_ctx.read().await;
            (
                ctx.pipeline_position,
                crate::spawn::SpawnContext::from_exec_context(&ctx),
            )
        };
        let inherit_output = self.interactive
            && matches!(pipeline_position, PipelinePosition::Only | PipelinePosition::Last);

        // Hermetic env: the child sees only kaish's exported vars, not the
        // kaish process's OS env. Frontends that want OS-env passthrough
        // (REPL, MCP) populate it via KernelConfig::initial_vars.
        let env = {
            let scope = self.scope.read().await;
            crate::spawn::hermetic_env(&scope)?
        };

        let stdin = if has_stdin {
            crate::spawn::StdinPolicy::Piped {
                prefix: stdin_bytes,
                pipe: pipe_stdin,
            }
        } else if self.interactive {
            crate::spawn::StdinPolicy::Inherit
        } else {
            crate::spawn::StdinPolicy::Null
        };

        // `self.interactive` and `self.terminal_state`, not the context's:
        // the persistent `exec_ctx` never carries the kernel's interactive
        // flag (only per-dispatch snapshots do), so the inherit decision is
        // made here and handed to the spawn as a policy.
        let output = if inherit_output {
            crate::spawn::OutputPolicy::Inherit {
                #[cfg(unix)]
                terminal_state: self.terminal_state.clone(),
            }
        } else {
            crate::spawn::OutputPolicy::Captured
        };

        let request = crate::spawn::SpawnRequest {
            executable: PathBuf::from(executable),
            argv,
            cwd: real_cwd,
            env,
            stdin,
            output,
            label: name.to_string(),
        };

        Ok(Some(crate::spawn::spawn_process(request, &spawn_ctx).await))
    }

    // --- Variable Access ---

    /// Get a variable value.
    pub async fn get_var(&self, name: &str) -> Option<Value> {
        let scope = self.scope.read().await;
        scope.get(name).cloned()
    }

    /// Check if error-exit mode is enabled (for testing).
    #[cfg(test)]
    pub async fn error_exit_enabled(&self) -> bool {
        let scope = self.scope.read().await;
        scope.error_exit_enabled()
    }

    /// Set a variable value.
    pub async fn set_var(&self, name: &str, value: Value) {
        let mut scope = self.scope.write().await;
        scope.set(name.to_string(), value);
    }

    /// Set positional parameters ($0 script name and $1-$9 args).
    pub async fn set_positional(&self, script_name: impl Into<String>, args: Vec<String>) {
        let mut scope = self.scope.write().await;
        scope.set_positional(script_name, args);
    }

    /// List all variables.
    pub async fn list_vars(&self) -> Vec<(String, Value)> {
        let scope = self.scope.read().await;
        scope.all()
    }

    /// List exported variables (name, value), sorted by name. These are the
    /// vars a child process would see (see `dispatch`'s hermetic env build).
    pub async fn exported_vars(&self) -> Vec<(String, Value)> {
        let scope = self.scope.read().await;
        scope.exported_vars()
    }

    // --- CWD ---

    /// Get current working directory.
    pub async fn cwd(&self) -> PathBuf {
        self.exec_ctx.read().await.cwd.clone()
    }

    /// Set current working directory.
    pub async fn set_cwd(&self, path: PathBuf) {
        let mut ctx = self.exec_ctx.write().await;
        ctx.set_cwd(path);
    }

    /// Set the working directory only if `path` resolves to a directory in the
    /// kernel's backend — the same namespace `cd` validates against. Unlike a
    /// raw host-FS `is_dir()` check, this correctly accepts virtual mounts
    /// (`/v/docs`, in-memory scratch, …) and rejects real paths that have since
    /// disappeared. Returns whether the cwd was changed.
    pub async fn try_set_cwd(&self, path: PathBuf) -> bool {
        // Clone the backend Arc out before the stat so we never hold the
        // exec_ctx lock across the await.
        let backend = self.exec_ctx.read().await.backend.clone();
        let is_dir = matches!(backend.stat(&path).await, Ok(entry) if entry.is_dir());
        if is_dir {
            self.exec_ctx.write().await.set_cwd(path);
        }
        is_dir
    }

    // --- Last Result ---

    /// Get the last result ($?).
    pub async fn last_result(&self) -> ExecResult {
        let scope = self.scope.read().await;
        scope.last_result().clone()
    }

    // --- Tools ---

    /// Check if a user-defined function exists.
    pub async fn has_function(&self, name: &str) -> bool {
        self.user_tools.read().await.contains_key(name)
    }

    /// Get available tool schemas.
    pub fn tool_schemas(&self) -> Vec<crate::tools::ToolSchema> {
        self.tools.schemas()
    }

    /// Classify how the kernel will resolve a command name.
    ///
    /// This is the supported, single source of truth for command resolution that
    /// embedders should call instead of re-deriving the rules. Walk a parsed
    /// script (`kaish_kernel::parser::parse` → `Stmt::Command` nodes) and call
    /// this per command name to bucket each into builtin / user-function /
    /// special-form / dynamic / external — for example a consent gate that blocks
    /// a script until external commands are approved.
    ///
    /// The classification mirrors the interpreter's real resolution order
    /// (`execute_command_depth`): special-forms (`true`/`false`/`source`/`.`)
    /// short-circuit first, then **aliases are expanded** (bounded recursion,
    /// re-checking special-forms each step, exactly as execution does), then user
    /// functions (which shadow builtins), then builtins, then a `PATH` lookup. A
    /// name that is a variable or command-substitution expansion (`$cmd`,
    /// `$(pick)`, `${x}`) classifies as [`CommandKind::Dynamic`] because it can't
    /// be resolved statically.
    ///
    /// Aliases are resolved against the kernel's current alias table, so an
    /// `alias cat=/bin/something` makes `cat` classify as `External` — the same
    /// thing it would actually run. The safe direction of any residual imprecision
    /// is `External`/`Dynamic`, never a false "internal": the `/v/bin/` prefix and
    /// `.kai`/backend-tool resolution are reported `External` even though some of
    /// those resolve in-process, so a consent gate over-gates rather than letting
    /// a `PATH` escape slip through.
    pub async fn classify_command(&self, name: &str) -> CommandKind {
        // Resolve the command head the way `execute_command_depth` does: a
        // special-form short-circuits before any alias lookup, otherwise expand
        // aliases (bounded, recursive) and re-check from the top. A dynamic name
        // can't be resolved at all.
        let mut name = name.to_string();
        let mut alias_depth = 0u8;
        loop {
            if !crate::validator::is_static_command_name(&name) {
                return CommandKind::Dynamic;
            }
            if crate::validator::is_runtime_special_form(&name) {
                return CommandKind::Special;
            }
            if alias_depth >= 10 {
                break;
            }
            let alias_value = {
                let ctx = self.exec_ctx.read().await;
                ctx.aliases.get(&name).cloned()
            };
            // Expand to the alias's head command. An empty alias value (no head)
            // is ignored by execution, so resolution continues with this name.
            match alias_value
                .as_deref()
                .and_then(|v| v.split_whitespace().next())
            {
                Some(head) => {
                    name = head.to_string();
                    alias_depth += 1;
                }
                None => break,
            }
        }

        let is_user_tool = self.user_tools.read().await.contains_key(&name);
        let is_builtin = self.tools.contains(&name);
        crate::validator::classify_command_name(&name, is_builtin, is_user_tool)
    }

    // --- Jobs ---

    /// Get job manager.
    pub fn jobs(&self) -> Arc<JobManager> {
        self.jobs.clone()
    }

    // --- VFS ---

    /// Get VFS router.
    pub fn vfs(&self) -> Arc<VfsRouter> {
        self.vfs.clone()
    }

    // --- State ---

    /// Reset kernel to initial state.
    ///
    /// Clears in-memory variables and resets cwd to root. History is not
    /// cleared (it persists across resets). The kernel's `$$` identity, the
    /// trash-on-delete configuration, the current errexit state, and any
    /// frontend-seeded `initial_vars` (HOME/PATH/etc, from `KernelConfig`)
    /// are re-applied to the fresh scope rather than silently reverting to
    /// defaults — an embedder that opted into trash or errexit must not find
    /// either quietly disabled after a `reset()` between requests.
    ///
    /// **Background jobs are untouched** (GH #245) — `reset()` is a scope/cwd
    /// reset, not a session boundary for `&`. A job started before `reset()`
    /// keeps running, stays in `jobs`, and the job ID counter keeps counting
    /// up. An embedder treating `reset()` as "new session" (a fresh MCP
    /// conversation reusing one kernel, say) inherits every job the previous
    /// conversation backgrounded — call [`Self::cancel_all_jobs`] first if
    /// that inheritance is not wanted.
    pub async fn reset(&self) -> Result<()> {
        {
            let mut scope = self.scope.write().await;
            let pid = scope.pid();
            let trash_enabled = scope.trash_enabled();
            let errexit_enabled = scope.error_exit_enabled();
            let mut fresh = Scope::new();
            fresh.set_pid(pid);
            for (name, value) in self.initial_vars.clone() {
                fresh.set_exported(name, value);
            }
            // The pin travels with the policy it pins — a `reset()` between
            // requests that dropped it would hand the next request an
            // unpinned session (spec §F.3 item 3).
            fresh.set_trash_enabled(trash_enabled);
            // Same reasoning as trash: an embedder relying on errexit for a
            // gating decision must not find it quietly disabled after a
            // `reset()` between requests.
            fresh.set_error_exit(errexit_enabled);
            // `reset()` puts the session back at `/`, so `$PWD` says so.
            // `initial_vars` can carry an inherited `PWD` from the invoking
            // environment, which would otherwise survive the reset and name a
            // directory this session is no longer in. `$OLDPWD` goes for the
            // same reason a fresh kernel has none: there is no previous
            // directory, and `cd -` refuses.
            fresh.set_global("PWD", Value::String("/".to_string()));
            fresh.remove("OLDPWD");
            *scope = fresh;
        }
        {
            let mut ctx = self.exec_ctx.write().await;
            ctx.cwd = PathBuf::from("/");
            ctx.prev_cwd = None;
        }
        Ok(())
    }

    /// Trip the cancellation token of every tracked background job (`&`) —
    /// whether or not `shutdown` follows.
    ///
    /// This is the same lever `kill %N` uses: a *running* job's in-process
    /// future exits at its next checkpoint, and any external children it
    /// spawned get the SIGTERM→SIGKILL cascade; it then stays tracked with
    /// status `Killed` once it unwinds. For an already-finished job the
    /// token trip is a no-op — its future has already resolved and the job
    /// keeps reporting its terminal status. This only
    /// *starts* cancellation, it does not wait (pair with
    /// [`JobManager::wait`]/`wait_all` if the caller needs to block on the
    /// unwind, bounded as [`Self::shutdown`] does).
    ///
    /// A job registered by an embedder via [`JobManager::register`] with no
    /// cancel token attached has no lever to cancel — silently skipped here,
    /// same as `kill %N`'s own "no cancellation token" case.
    ///
    /// Returns how many jobs a token was actually tripped for.
    pub async fn cancel_all_jobs(&self) -> usize {
        let ids = self.jobs.list_ids().await;
        let mut cancelled = 0;
        for id in ids {
            if self.jobs.mark_killed_and_cancel(id, false).await {
                cancelled += 1;
            }
        }
        cancelled
    }

    /// Shut down the kernel.
    ///
    /// Cancels every tracked background job ([`Self::cancel_all_jobs`]), then
    /// waits up to `kill_grace + 3s` **per job** — the same bound `kill %N`
    /// gives a single target (GH #244) — for it to actually unwind. The
    /// waits are sequential, so the worst case is additive: N jobs that all
    /// ignore cancellation block shutdown for N × (kill_grace + 3s). Jobs
    /// that unwind promptly (the normal case) cost only their own unwind
    /// time. Before this fix `shutdown` called `wait_all()` with no timeout
    /// at all: `sleep 3600 &` then `shutdown()` blocked for an hour (GH #245).
    ///
    /// A job that has not unwound by its deadline is abandoned: logged via
    /// `tracing::warn!` and left running detached until the tokio runtime
    /// itself goes away. There is no further lever once `shutdown()` has
    /// returned — this method does not hang, but it also does not guarantee
    /// every job actually stopped.
    ///
    /// Takes `&self`, not owned `self` — an embedder holding `Arc<Kernel>`
    /// (e.g. `kaish-client`'s `EmbeddedClient`) can call this without
    /// `Arc::try_unwrap`, since the work here only touches the shared
    /// `Arc<JobManager>`, never kernel state that would need exclusive
    /// ownership.
    pub async fn shutdown(&self) -> Result<()> {
        let ids = self.jobs.list_ids().await;
        self.cancel_all_jobs().await;

        let bound = self.jobs.kill_grace() + Duration::from_secs(3);
        for id in ids {
            if tokio::time::timeout(bound, self.jobs.wait(id)).await.is_err() {
                tracing::warn!(
                    job_id = %id,
                    bound_secs = bound.as_secs_f64(),
                    "kernel shutdown: job did not exit within the grace period after \
                     cancellation — abandoning it"
                );
            }
        }
        Ok(())
    }

    /// Run a compound statement that occupies a pipeline stage.
    ///
    /// Same ctx↔exec_ctx sync as `dispatch_command`, with one deliberate
    /// difference: the stage's pipe writer stays behind with the runner. The
    /// statement buffers — its whole output comes back in the `ExecResult` and
    /// the runner writes it to the pipe once. Handing the writer down instead
    /// would give it to whichever nested command grabbed the slot first, and
    /// every later iteration would write nowhere.
    ///
    /// Streaming a stage would mean threading a writer through nested
    /// statement execution, which is the shared-slot machinery GH #369 is
    /// about. Revisit once the interpreter takes a ctx parameter.
    async fn dispatch_statement(&self, stmt: &Stmt, ctx: &mut ExecContext) -> Result<ExecResult> {
        if let Some(d) = self.dispatcher() {
            ctx.dispatcher = Some(d);
        }

        // 1. Sync ctx → self internals
        {
            let mut scope = self.scope.write().await;
            *scope = ctx.scope.clone();
        }
        {
            let mut ec = self.exec_ctx.write().await;
            ec.cwd = ctx.cwd.clone();
            ec.prev_cwd = ctx.prev_cwd.clone();
            ec.stdin = ctx.stdin.take();
            ec.stdin_data = ctx.stdin_data.take();
            ec.stdin_data_rx = ctx.stdin_data_rx.take();
            ec.pipe_stdin = ctx.pipe_stdin.take();
            // The writer is NOT handed over — see this function's doc comment.
            // Clearing the slot keeps a writer left by an earlier dispatch from
            // catching the first command inside the loop body.
            ec.pipe_stdout = None;
            if let Some(stderr) = ctx.stderr.clone() {
                ec.stderr = Some(stderr);
            }
            ec.aliases = ctx.aliases.clone();
            ec.ignore_config = ctx.ignore_config.clone();
            ec.output_limit = ctx.output_limit.clone();
            ec.pipeline_position = ctx.pipeline_position;
            ec.cancel = ctx.cancel.clone();
            ec.watchdog = ctx.watchdog.clone();
        }

        // 2. Run the statement. A stage is its own execution unit, so a
        // `break`, `continue`, `return`, or `exit` that reaches the top of the
        // statement stops here rather than escaping into the enclosing script —
        // the same boundary bash draws by running each stage in a subshell.
        // Whatever output the statement produced before the signal still comes
        // back and still reaches the pipe.
        let result = match self.execute_stmt_flow(stmt).await? {
            ControlFlow::Normal(result)
            | ControlFlow::Break { result, .. }
            | ControlFlow::Continue { result, .. }
            | ControlFlow::Return { value: result } => result,
            ControlFlow::Exit { code, mut result } => {
                result.code = code;
                result
            }
        };

        // 3. Sync self → ctx
        {
            let scope = self.scope.read().await;
            ctx.scope = scope.clone();
        }
        {
            let mut ec = self.exec_ctx.write().await;
            ctx.cwd = ec.cwd.clone();
            ctx.prev_cwd = ec.prev_cwd.clone();
            ctx.aliases = ec.aliases.clone();
            ctx.ignore_config = ec.ignore_config.clone();
            ctx.output_limit = ec.output_limit.clone();
            ctx.pipe_stdin = ec.pipe_stdin.take();
            ctx.stdin = ec.stdin.take();
            ctx.stdin_data = ec.stdin_data.take();
            ctx.stdin_data_rx = ec.stdin_data_rx.take();
        }

        Ok(result)
    }

    /// Dispatch a single command using the full resolution chain.
    ///
    /// This is the core of `CommandDispatcher` — it syncs state between the
    /// passed-in `ExecContext` and kernel-internal state (scope, exec_ctx),
    /// then delegates to `execute_command` for the actual dispatch.
    ///
    /// State flow:
    /// 1. ctx → self: sync scope, cwd, stdin so internal methods see current state
    /// 2. execute_command: full dispatch chain (user tools, builtins, scripts, external, backend)
    /// 3. self → ctx: sync scope, cwd changes back so the pipeline runner sees them
    async fn dispatch_command(&self, cmd: &Command, ctx: &mut ExecContext) -> Result<ExecResult> {
        // Ensure nested dispatch (e.g. the `timeout` builtin re-dispatching
        // its inner command via ctx.dispatcher) routes through THIS kernel,
        // not a stale parent. Critical for forks: the fork's builtins must
        // use the fork's dispatcher, not the parent's.
        if let Some(d) = self.dispatcher() {
            ctx.dispatcher = Some(d);
        }

        // 1. Sync ctx → self internals
        {
            let mut scope = self.scope.write().await;
            *scope = ctx.scope.clone();
        }
        {
            let mut ec = self.exec_ctx.write().await;
            ec.cwd = ctx.cwd.clone();
            ec.prev_cwd = ctx.prev_cwd.clone();
            ec.stdin = ctx.stdin.take();
            ec.stdin_data = ctx.stdin_data.take();
            // The structured-data sideband receiver (set by the concurrent
            // pipeline runner on the stage ctx) must reach the tool's snapshot
            // too — same reason as the pipe endpoints below. Without this a
            // pipeline consumer never sees the producer's `.data`.
            ec.stdin_data_rx = ctx.stdin_data_rx.take();
            // Streaming pipe endpoints and kernel stderr must flow to the
            // tool via self.exec_ctx — execute_command reads that, not the
            // passed-in ctx. Without moving these, concurrent pipeline
            // stages dispatched via a fork get pipe_stdin = None and
            // silently read nothing.
            ec.pipe_stdin = ctx.pipe_stdin.take();
            ec.pipe_stdout = ctx.pipe_stdout.take();
            if let Some(stderr) = ctx.stderr.clone() {
                ec.stderr = Some(stderr);
            }
            ec.aliases = ctx.aliases.clone();
            ec.ignore_config = ctx.ignore_config.clone();
            ec.output_limit = ctx.output_limit.clone();
            ec.pipeline_position = ctx.pipeline_position;
            // Sync the cancel token from ctx → ec. Builtins like `timeout`
            // swap ctx.cancel to a derived child token before re-dispatching;
            // execute_command's snapshot reads ec.cancel (kept aligned by
            // this sync), so try_execute_external sees the right token.
            ec.cancel = ctx.cancel.clone();
            // Same alignment for the watchdog: a fork dispatching through its
            // own kernel must hand the shared script clock to the snapshot so
            // patient holds in forked stages suspend the right timer.
            ec.watchdog = ctx.watchdog.clone();
        }

        // 2. Execute via the full dispatch chain
        let result = self.execute_command(&cmd.name, &cmd.args).await?;

        // 3. Sync self → ctx
        {
            let scope = self.scope.read().await;
            ctx.scope = scope.clone();
        }
        {
            let mut ec = self.exec_ctx.write().await;
            ctx.cwd = ec.cwd.clone();
            ctx.prev_cwd = ec.prev_cwd.clone();
            ctx.aliases = ec.aliases.clone();
            ctx.ignore_config = ec.ignore_config.clone();
            ctx.output_limit = ec.output_limit.clone();
            // Return any pipe endpoints that the tool didn't consume.
            // `take()` here keeps the fork's exec_ctx in a clean state for
            // the next dispatch — these are per-command and shouldn't leak
            // between calls.
            ctx.pipe_stdin = ec.pipe_stdin.take();
            ctx.pipe_stdout = ec.pipe_stdout.take();
            // Unconsumed buffered stdin comes back the same way, and for a
            // sharper reason than symmetry: a partial read (`read` takes one
            // line) leaves its remainder in `ec`, and the caller's own
            // end-of-statement sync writes `ctx.stdin` back over `ec.stdin`.
            // Without this the caller writes its stale `None` over the
            // remainder and the rest of the stream is gone.
            ctx.stdin = ec.stdin.take();
            // The sideband rides home with stdin, same rule.
            ctx.stdin_data = ec.stdin_data.take();
            ctx.stdin_data_rx = ec.stdin_data_rx.take();
            // Same take-don't-clone discipline as stdin, and for the same
            // reason: these belong to exactly one dispatch, and a copy left
            // behind would let the next command adopt it.
        }

        Ok(result)
    }
}

/// Evaluates a single AST expression on behalf of [`bind_tool_args`], the one
/// shared arg-binding core behind both `Kernel::build_args_async`
/// (production: full recursion through the async pipeline, command
/// substitution, real glob expansion) and the reduced sync evaluator behind
/// scatter/gather's own option parsing and the `#[cfg(test)]`
/// `BackendDispatcher` (`scheduler::pipeline::build_tool_args`'s
/// `SyncEvalSource`). GH #188 closes the drift class between those two
/// callers: the flag/positional-binding logic (this file's `bind_tool_args`)
/// is now the ONLY implementation; only expression evaluation, which is
/// capability-bound (recursing into command substitution needs a live async
/// pipeline the reduced context doesn't have), still has two providers.
#[async_trait]
pub(crate) trait ArgValueSource: Send + Sync {
    /// Evaluate `expr` to a `Value`. `Ok(None)` means "not representable by
    /// this evaluator" — the reduced sync evaluator's bash-compatible
    /// "coalesce" convention for an unset bare variable, or an expression
    /// form it doesn't support (a binary op) — and the caller drops the
    /// argument the same way an unset bare variable always has. The real
    /// (Kernel) evaluator never returns `Ok(None)`: it can always fully
    /// evaluate.
    async fn eval(&self, expr: &Expr) -> Result<Option<Value>>;

    /// Expand a bare glob-pattern positional to display strings, or `None`
    /// if this evaluator doesn't expand globs here (disabled, or the reduced
    /// sync context, which never has — matching its documented "no
    /// filesystem walk before worker forks" limit). `bind_tool_args` falls
    /// back to `eval` (which hands back the pattern text as a literal
    /// string) when this returns `None`. An enabled expansion that matches
    /// nothing is a genuine error, not `Ok(None)`.
    async fn expand_glob(&self, pattern: &str) -> Result<Option<Vec<String>>>;

    /// Session `HOME`, for tilde expansion. `None` disables tilde expansion
    /// — the reduced sync evaluator's existing behavior (it never expanded
    /// `~`).
    async fn home(&self) -> Option<String>;
}

#[async_trait]
impl ArgValueSource for Kernel {
    async fn eval(&self, expr: &Expr) -> Result<Option<Value>> {
        Ok(Some(self.eval_expr_async(expr).await?))
    }

    async fn expand_glob(&self, pattern: &str) -> Result<Option<Vec<String>>> {
        let glob_enabled = self.scope.read().await.glob_enabled();
        if !glob_enabled {
            return Ok(None);
        }
        let (paths, cwd) = {
            let ctx = self.exec_ctx.read().await;
            let paths = ctx
                .expand_glob(pattern)
                .await
                .map_err(|e| anyhow::anyhow!("glob: {}", e))?;
            let cwd = ctx.resolve_path(".");
            (paths, cwd)
        };
        if paths.is_empty() {
            anyhow::bail!("no matches: {}", pattern);
        }
        let display = paths
            .into_iter()
            .map(|path| {
                if !pattern.starts_with('/') {
                    path.strip_prefix(&cwd)
                        .unwrap_or(&path)
                        .to_string_lossy()
                        .into_owned()
                } else {
                    path.to_string_lossy().into_owned()
                }
            })
            .collect();
        Ok(Some(display))
    }

    async fn home(&self) -> Option<String> {
        self.scope_home().await
    }
}

/// Pull `consumes` positional args after a non-bool flag and stash them on
/// `tool_args.named` under the canonical param name. Shared core behind
/// [`bind_tool_args`]'s `ShortFlag`/`LongFlag` value-flag arms — see that
/// function's doc comment for the unification story (GH #188).
///
/// - `consumes == 1` (non-repeatable) keeps the historical contract: a
///   single scalar value (last write wins on the rare duplicate).
/// - `consumes == 1` + `repeatable` accumulates each occurrence as a scalar
///   inside `named[canonical] = Value::Json(Array(...))`, preserving
///   invocation order. This is the shape sed's `-e EXPR -e EXPR` lands in —
///   a repeated single-value flag must keep every value, not silently drop
///   all but the last (a "no silent corruption" violation).
/// - `consumes > 1` accumulates each occurrence as an inner
///   `serde_json::Value::Array` inside `named[canonical] =
///   Value::Json(Array(...))`, preserving invocation order. This is the
///   shape jq's `--arg NAME VAL` / `--argjson NAME VAL` land in.
///
/// Errors loudly if the flag is missing required positionals — matches
/// kaish's "no silent fallback" posture and mirrors real jq, which errors on
/// `--arg NAME` with no value. A reduced evaluator's `Ok(None)` (a value it
/// can't represent — Kernel's evaluator never returns this) falls back to a
/// bare flag on the FIRST occurrence, matching the pre-#188 sync twin's
/// unset-bare-var "coalesce" convention; mid-accumulation it's a genuine
/// error rather than a silently-partial array.
#[allow(clippy::too_many_arguments)]
async fn consume_flag_positionals(
    source: &dyn ArgValueSource,
    home: Option<&str>,
    args: &[Arg],
    flag_name: &str,
    canonical: &str,
    consumes: usize,
    repeatable: bool,
    positional_indices: &[usize],
    consumed: &mut std::collections::HashSet<usize>,
    current_idx: usize,
    tool_args: &mut ToolArgs,
) -> Result<()> {
    let mut collected: Vec<Value> = Vec::with_capacity(consumes.max(1));
    for _ in 0..consumes.max(1) {
        // A `key=value` (WordAssign) token is consumable only by a
        // single-value flag (`-v a=1`). For a multi-value flag (`jq --arg
        // NAME VAL`, consumes>1) it is NOT eligible — otherwise `--arg x=1
        // filter` would reassemble `x=1` into the first slot and steal the
        // filter into the second. Multi-value flags take plain positionals.
        let allow_word_assign = consumes <= 1;
        let next_pos = positional_indices
            .iter()
            .find(|idx| {
                **idx > current_idx
                    && !consumed.contains(idx)
                    && (allow_word_assign || matches!(args[**idx], Arg::Positional(_)))
            })
            .copied();
        match next_pos {
            Some(pos_idx) => match &args[pos_idx] {
                Arg::Positional(expr) => match source.eval(expr).await? {
                    Some(value) => {
                        let value = apply_tilde_expansion(value, home);
                        collected.push(value);
                        consumed.insert(pos_idx);
                    }
                    None if collected.is_empty() => {
                        tool_args.flags.insert(flag_name.to_string());
                        return Ok(());
                    }
                    None => anyhow::bail!(
                        "--{flag_name}: could not evaluate argument {} in this context",
                        collected.len() + 1
                    ),
                },
                // `-v a=1`: reassemble the `key=value` token as the flag's
                // scalar value (see `positional_indices` construction).
                Arg::WordAssign { key, value } => match source.eval(value).await? {
                    Some(val) => {
                        let val = apply_tilde_expansion(val, home);
                        // Loud on binary (GH #116): `-v a=$BIN` must not silently
                        // reassemble the `[binary: N bytes]` placeholder into the
                        // flag's value — same text-sink boundary as the primary
                        // sinks fixed in #93 item 1.
                        let val_str = crate::interpreter::value_to_text_sink_named(
                            &val,
                            "a key=value argument",
                        )
                        .map_err(|e| anyhow::anyhow!("{e}"))?;
                        collected.push(Value::String(format!("{key}={val_str}")));
                        consumed.insert(pos_idx);
                    }
                    None if collected.is_empty() => {
                        tool_args.flags.insert(flag_name.to_string());
                        return Ok(());
                    }
                    None => anyhow::bail!(
                        "--{flag_name}: could not evaluate argument {} in this context",
                        collected.len() + 1
                    ),
                },
                _ => {}
            },
            None => {
                if consumes <= 1 && collected.is_empty() {
                    // Back-compat: a flag with no follow-up positional
                    // becomes a bare flag. `--path` with nothing after
                    // lands in `flags`, same as before this refactor.
                    tool_args.flags.insert(flag_name.to_string());
                    return Ok(());
                }
                anyhow::bail!(
                    "--{flag_name} requires {consumes} argument{}, got {}",
                    if consumes == 1 { "" } else { "s" },
                    collected.len()
                );
            }
        }
    }

    if consumes <= 1 {
        if let Some(v) = collected.pop() {
            if repeatable {
                push_repeatable_value(tool_args, flag_name, canonical, v)?;
            } else {
                tool_args.named.insert(canonical.to_string(), v);
            }
        }
        return Ok(());
    }

    // Multi-consume: accumulate under named[canonical] as array-of-arrays.
    let occ: Vec<serde_json::Value> = collected
        .iter()
        .map(|v| flag_value_to_json(canonical, v))
        .collect::<Result<Vec<_>>>()?;
    let entry = tool_args
        .named
        .entry(canonical.to_string())
        .or_insert_with(|| Value::Json(serde_json::Value::Array(Vec::new())));
    if let Value::Json(serde_json::Value::Array(outer)) = entry {
        outer.push(serde_json::Value::Array(occ));
    } else {
        anyhow::bail!(
            "--{flag_name}: named[{canonical}] already holds a non-array value"
        );
    }
    Ok(())
}

/// Build `ToolArgs` from AST `Arg`s — the single arg-binding implementation
/// (GH #188) shared by `Kernel::build_args_async` (production) and the
/// reduced sync path (`scheduler::pipeline::build_tool_args`, used by
/// scatter/gather's own option parsing and the `#[cfg(test)]`
/// `BackendDispatcher`). The two differ only in the [`ArgValueSource`] they
/// pass: Kernel's evaluates full expressions (including `$(...)` command
/// substitution) and expands real globs/tilde; the reduced one can't recurse
/// into the async pipeline this early (scatter/gather's own flags bind
/// before any worker forks) so it evaluates a smaller expression subset and
/// never expands globs/tilde — see `SyncEvalSource` in `scheduler::pipeline`.
///
/// If a schema is provided, uses it to determine argument types:
/// - For `--flag` where schema says type is non-bool: consume next
///   positional(s) as value(s) (`consumes`/`repeatable`-aware).
/// - For `--flag` where schema says type is bool (or unknown): treat as a
///   boolean flag.
///
/// This enables natural shell syntax like `mcp_tool --query "test" --limit 10`.
pub(crate) async fn bind_tool_args(
    args: &[Arg],
    schema: Option<&crate::tools::ToolSchema>,
    source: &dyn ArgValueSource,
) -> Result<ToolArgs> {
    let mut tool_args = ToolArgs::new();
    let home = source.home().await;

    // A glob-passthrough tool (`glob`) consumes patterns as data: skip
    // argv glob expansion so the pattern reaches the tool as written —
    // otherwise `glob **/*.rs` binds the first *matching path* as its
    // pattern. The eval fallback turns `Expr::GlobPattern` into its
    // literal string.
    let glob_passthrough = schema.is_some_and(|s| s.glob_passthrough);

    // Verbatim: the tool owns its grammar, so it gets every word in source
    // order and nothing in `positional`/`named`. The typed split below is
    // set-shaped and drops the order and multiplicity a clap subcommand tree
    // needs, which no inversion can recover.
    //
    // `--json` is still the kernel's, so it is lifted into `flags` wherever it
    // sits and `apply_from_args` handles it as it does for a typed tool —
    // unless the tool owns its output, in which case the kernel renders
    // nothing and the flag has to reach the tool's own argv instead. Lifting it
    // there would strip it from the words AND skip rendering, so asking for
    // JSON would do nothing at all.
    if schema.is_some_and(|s| matches!(s.arg_binding, crate::tools::ArgBinding::Verbatim)) {
        let lift_global_flags = !schema.is_some_and(|s| s.owns_output);
        let mut words: Vec<Value> = Vec::new();
        let mut past_double_dash = false;
        for arg in args {
            match arg {
                Arg::Positional(expr) => {
                    let glob = if let Expr::GlobPattern(p) = expr {
                        (!glob_passthrough).then(|| p.clone())
                    } else {
                        None
                    };
                    let expanded = match &glob {
                        Some(pattern) => source.expand_glob(pattern).await?,
                        None => None,
                    };
                    match expanded {
                        Some(paths) => {
                            for path in paths {
                                words.push(Value::String(path));
                            }
                        }
                        None => {
                            // Nothing evaluated means no word, matching the
                            // typed path's `if let Some(value)`.
                            if let Some(value) = source.eval(expr).await? {
                                // Recorded at the index the push below lands
                                // at — see `ToolArgs::words_raw`.
                                if let Expr::NumericLiteral { raw, .. } = expr {
                                    tool_args.words_raw.insert(words.len(), raw.clone());
                                }
                                words.push(apply_tilde_expansion(value, home.as_deref()));
                            }
                        }
                    }
                }
                Arg::ShortFlag(name) => words.push(Value::String(format!("-{name}"))),
                Arg::LongFlag(name) => {
                    if lift_global_flags
                        && !past_double_dash
                        && crate::tools::is_global_output_flag(name)
                    {
                        tool_args.flags.insert(name.clone());
                        continue;
                    }
                    words.push(Value::String(format!("--{name}")));
                }
                Arg::Named { key, value } => {
                    let val = source.eval(value).await?.ok_or_else(|| {
                        anyhow::anyhow!("verbatim --key=value could not be evaluated in this context")
                    })?;
                    let val = apply_tilde_expansion(val, home.as_deref());
                    if lift_global_flags
                        && !past_double_dash
                        && crate::tools::is_global_output_flag(key)
                    {
                        // Removed from the words whether or not it is on: the
                        // tool must not meet the kernel's flag in any form.
                        if global_flag_value_is_truthy(&val) {
                            tool_args.flags.insert(key.clone());
                        }
                        continue;
                    }
                    // Loud on binary (GH #116): reassembling `--k=$BIN` as text
                    // hands the tool a placeholder that looks like data. A bare
                    // binary word is fine — it stays typed. The whole word is
                    // composed here, so no later render step could reach a
                    // `words_raw` entry.
                    let val_str = if let Expr::NumericLiteral { raw, .. } = value {
                        raw.clone()
                    } else {
                        crate::interpreter::value_to_text_sink_named(
                            &val,
                            "a --key=value argument",
                        )
                        .map_err(|e| anyhow::anyhow!("{e}"))?
                    };
                    words.push(Value::String(format!("--{key}={val_str}")));
                }
                Arg::WordAssign { key, value } => {
                    let val = source.eval(value).await?.ok_or_else(|| {
                        anyhow::anyhow!("verbatim key=value could not be evaluated in this context")
                    })?;
                    let val = apply_tilde_expansion(val, home.as_deref());
                    let val_str = if let Expr::NumericLiteral { raw, .. } = value {
                        raw.clone()
                    } else {
                        crate::interpreter::value_to_text_sink_named(
                            &val,
                            "a key=value argument",
                        )
                        .map_err(|e| anyhow::anyhow!("{e}"))?
                    };
                    words.push(Value::String(format!("{key}={val_str}")));
                }
                Arg::DoubleDash => {
                    past_double_dash = true;
                    words.push(Value::String("--".to_string()));
                }
            }
        }
        tool_args.words = Some(words);
        return Ok(tool_args);
    }

    // Raw-argv fast path (POSIX `test`): bind every argument to `positional`
    // in source order with types preserved — operators (`-f`, `=`, `!`) as
    // strings, operands keeping their `Value` — leaving `flags`/`named`
    // empty. A position-sensitive command needs the *true* argv: an operand
    // that looks like a flag (`test $x = -n`, `test 0 -gt -5`) must not be
    // hoisted into the unordered flag set the normal binder splits into.
    // Globs still expand and `~` still resolves, matching normal positional
    // binding — so `test -f *.rs` errors on too many args, not a literal
    // pattern stat.
    if schema.is_some_and(|s| s.raw_argv) {
        for arg in args {
            match arg {
                Arg::Positional(expr) => {
                    let glob = if let Expr::GlobPattern(p) = expr {
                        (!glob_passthrough).then(|| p.clone())
                    } else {
                        None
                    };
                    if let Some(pattern) = glob {
                        match source.expand_glob(&pattern).await? {
                            Some(paths) => {
                                for path in paths {
                                    tool_args.positional.push(Value::String(path));
                                }
                            }
                            None => {
                                let value = source.eval(expr).await?.ok_or_else(|| {
                                    anyhow::anyhow!(
                                        "raw-argv positional could not be evaluated in this context"
                                    )
                                })?;
                                let value = apply_tilde_expansion(value, home.as_deref());
                                if let Expr::NumericLiteral { raw, .. } = expr {
                                    tool_args
                                        .positional_raw
                                        .insert(tool_args.positional.len(), raw.clone());
                                }
                                tool_args.positional.push(value);
                            }
                        }
                    } else {
                        let value = source.eval(expr).await?.ok_or_else(|| {
                            anyhow::anyhow!(
                                "raw-argv positional could not be evaluated in this context"
                            )
                        })?;
                        let value = apply_tilde_expansion(value, home.as_deref());
                        // `test`'s numeric operators still get the real
                        // `value`; a text consumer gets `raw`.
                        if let Expr::NumericLiteral { raw, .. } = expr {
                            tool_args
                                .positional_raw
                                .insert(tool_args.positional.len(), raw.clone());
                        }
                        tool_args.positional.push(value);
                    }
                }
                Arg::ShortFlag(name) => {
                    tool_args.positional.push(Value::String(format!("-{name}")));
                }
                Arg::LongFlag(name) => {
                    tool_args.positional.push(Value::String(format!("--{name}")));
                }
                Arg::Named { key, value } => {
                    let val = source.eval(value).await?.ok_or_else(|| {
                        anyhow::anyhow!("raw-argv --key=value could not be evaluated in this context")
                    })?;
                    let val = apply_tilde_expansion(val, home.as_deref());
                    // Loud on binary (GH #116): `test --k=$BIN` must not
                    // silently reassemble the placeholder into the raw-argv
                    // positional stream `test` binds against. Source text
                    // wins, as in the Verbatim binder's `Arg::Named` arm.
                    let val_str = if let Expr::NumericLiteral { raw, .. } = value {
                        raw.clone()
                    } else {
                        crate::interpreter::value_to_text_sink_named(
                            &val,
                            "a --key=value argument",
                        )
                        .map_err(|e| anyhow::anyhow!("{e}"))?
                    };
                    tool_args
                        .positional
                        .push(Value::String(format!("--{key}={val_str}")));
                }
                Arg::WordAssign { key, value } => {
                    let val = source.eval(value).await?.ok_or_else(|| {
                        anyhow::anyhow!("raw-argv key=value could not be evaluated in this context")
                    })?;
                    let val = apply_tilde_expansion(val, home.as_deref());
                    // Loud on binary (GH #116): same reasoning as the Named
                    // arm above, for the bare `key=value` raw-argv form.
                    let val_str = if let Expr::NumericLiteral { raw, .. } = value {
                        raw.clone()
                    } else {
                        crate::interpreter::value_to_text_sink_named(
                            &val,
                            "a key=value argument",
                        )
                        .map_err(|e| anyhow::anyhow!("{e}"))?
                    };
                    tool_args
                        .positional
                        .push(Value::String(format!("{key}={val_str}")));
                }
                Arg::DoubleDash => {
                    tool_args.positional.push(Value::String("--".to_string()));
                }
            }
        }
        return Ok(tool_args);
    }

    // Subcommand-aware tools (e.g. `kj context list`) expose a tree of
    // schemas; pick the leaf the leading positionals route to and bind
    // flags against *its* params. Flat tools return the root. select_leaf
    // errors (fail loud) if a computed positional sits where a subcommand
    // selector is required.
    let leaf = match schema {
        Some(s) => Some(select_leaf(s, args)?),
        None => None,
    };
    // Bind against the leaf's params, but MERGE the root schema's params on
    // top as "global" flags: a value-flag declared at the tool's top level
    // (e.g. kj's `--confirm <token>`) must bind at every leaf, including when
    // it trails the subcommand path (`kj context retag a b --confirm <n>`).
    // The leaf wins on name conflicts. For a flat tool, leaf == root, so the
    // merge is a harmless no-op.
    let mut param_lookup = schema.map(schema_param_lookup).unwrap_or_default();
    if let Some(l) = leaf {
        param_lookup.extend(schema_param_lookup(l));
    }
    // accepts_word_assign keys off the root tool name (the WORD_ASSIGN list),
    // not the leaf — it's a property of the command, not the subcommand.
    let accepts_word_assign = schema
        .map(|s| crate::tools::accepts_word_assign(s.name.as_str()))
        .unwrap_or(false);

    // Track which positional indices have been consumed as flag values
    let mut consumed: std::collections::HashSet<usize> = std::collections::HashSet::new();
    let mut past_double_dash = false;

    // Indices a value-flag may consume as its value. Positionals always
    // qualify. A `WordAssign` (`a=1`) also qualifies when the tool does not
    // itself treat `key=value` as an assignment (everything but
    // export/alias/unalias) — getopt semantics: `awk -v a=1` binds `a=1` to
    // `-v`, rather than skipping it and grabbing the next positional (the
    // program). Without this, the natural `-F`/`-v NAME=VALUE` form silently
    // mis-binds. The main-loop `WordAssign` arm skips consumed indices.
    let positional_indices: Vec<usize> = args
        .iter()
        .enumerate()
        .filter_map(|(i, a)| {
            let consumable = matches!(a, Arg::Positional(_))
                || (!accepts_word_assign && matches!(a, Arg::WordAssign { .. }));
            consumable.then_some(i)
        })
        .collect();

    let mut i = 0;
    while i < args.len() {
        match &args[i] {
            Arg::DoubleDash => {
                past_double_dash = true;
            }
            Arg::Positional(expr) => {
                if !consumed.contains(&i) {
                    // Glob expansion: bare glob patterns expand to matching files
                    if let Expr::GlobPattern(pattern) = expr {
                        if !glob_passthrough {
                            if let Some(paths) = source.expand_glob(pattern).await? {
                                for path in paths {
                                    tool_args.positional.push(Value::String(path));
                                }
                                i += 1;
                                continue;
                            }
                        }
                    }
                    if let Some(value) = source.eval(expr).await? {
                        let value = apply_tilde_expansion(value, home.as_deref());
                        // The path `echo` reads: it takes `args.positional`
                        // directly, never the clap-parsed field, so a plain
                        // `Value::Int` here could not reproduce `-0`.
                        if let Expr::NumericLiteral { raw, .. } = expr {
                            tool_args
                                .positional_raw
                                .insert(tool_args.positional.len(), raw.clone());
                        }
                        tool_args.positional.push(value);
                    }
                }
            }
            Arg::Named { key, value } => {
                if let Some(val) = source.eval(value).await? {
                    let val = apply_tilde_expansion(val, home.as_deref());
                    // Past `--` this is data, not a flag: one operand spelled
                    // `--key=value`, the same collapse the `WordAssign` arm
                    // below does for `A=1` (GH #189). The value still expands.
                    if past_double_dash {
                        let val_str = if let Expr::NumericLiteral { raw, .. } = value {
                            raw.clone()
                        } else {
                            crate::interpreter::value_to_text_sink_named(
                                &val,
                                "a --key=value operand after `--`",
                            )
                            .map_err(|e| anyhow::anyhow!("{e}"))?
                        };
                        tool_args
                            .positional
                            .push(Value::String(format!("--{key}={val_str}")));
                        i += 1;
                        continue;
                    }
                    // The kernel's own `--json=VALUE`, decided here and never
                    // placed in `named`. Left there it reaches the builtin's
                    // clap parser as a value on a `bool` field, whose `SetTrue`
                    // action rejects every spelling but `true`/`false` — so
                    // `seq --json=1` exited 2 while the raw-argv and verbatim
                    // binders were quietly accepting the same word. One rule,
                    // asked in one place, for all three.
                    if !past_double_dash && crate::tools::is_global_output_flag(key) {
                        if global_flag_value_is_truthy(&val) {
                            tool_args.flags.insert(key.clone());
                        }
                        i += 1;
                        continue;
                    }
                    // A repeatable flag in `--flag=value` form must accumulate too,
                    // not overwrite — otherwise `--expression=A --expression=B`
                    // would silently keep only B, and mixing with the `-e` space
                    // form would clobber the array. Route it through the same
                    // accumulator the space form uses.
                    let is_declared_value_flag = param_lookup
                        .get(key.as_str())
                        .is_some_and(|(_, typ, ..)| !is_bool_type(typ));
                    if let Some(&(canonical, _, _, true)) = param_lookup.get(key.as_str()) {
                        push_repeatable_value(&mut tool_args, key, canonical, val)?;
                    } else if matches!(val, Value::Bool(_)) && !is_declared_value_flag {
                        // Flagify at bind time (GH #189): `--flag=true`/
                        // `--flag=false` binds the same way the bare
                        // `--flag`/its absence already do (true → flag
                        // presence, false → dropped) instead of landing in
                        // `named` as a literal `Value::Bool` that a clap
                        // `bool` field's `SetTrue` action rejects
                        // (`seq --json=true` used to exit 2 with a clap
                        // parse error). Covers both a schema-declared bool
                        // param AND an undeclared flag — `--json` itself is
                        // deliberately excluded from every builtin's schema
                        // (`clap_schema::is_skipped`), so this is what makes
                        // `--json=true` work universally instead of only for
                        // the builtins that happen to call
                        // `ToolArgs::flagify_bool_named` themselves. A
                        // declared VALUE-taking flag's own `=true` literal
                        // (`spawn --command=true`) is excluded by
                        // `is_declared_value_flag` and still falls to
                        // `named` below.
                        if let Value::Bool(true) = val {
                            tool_args.flags.insert(key.clone());
                        }
                        // Value::Bool(false): absent == false, nothing to insert.
                    } else {
                        // A named value is normally read off the clap-parsed
                        // field, built from `to_argv()` — see
                        // `ToolArgs::named_raw`.
                        if let Expr::NumericLiteral { raw, .. } = value {
                            tool_args.named_raw.insert(key.clone(), raw.clone());
                        }
                        tool_args.named.insert(key.clone(), val);
                    }
                }
            }
            Arg::WordAssign { key, value } => {
                // Already pulled in as a preceding value-flag's argument
                // (`awk -v a=1`); don't also emit it as a positional.
                if consumed.contains(&i) {
                    i += 1;
                    continue;
                }
                if let Some(val) = source.eval(value).await? {
                    let val = apply_tilde_expansion(val, home.as_deref());
                    // Past `--`, EVERY token is raw data — including for
                    // export/alias, whose `key=value` is normally a shell
                    // assignment (GH #189). `export -- A=1` must bind `A=1`
                    // as a literal positional, not silently re-enter the
                    // named-assignment path `past_double_dash` exists to
                    // suppress for flags right above this arm.
                    if accepts_word_assign && !past_double_dash {
                        if let Expr::NumericLiteral { raw, .. } = value {
                            tool_args.named_raw.insert(key.clone(), raw.clone());
                        }
                        tool_args.named.insert(key.clone(), val);
                    } else {
                        // Stringify "key=value" and pass as a positional.
                        // Matches bash: `cat foo=bar` opens a file named `foo=bar`.
                        // Loud on binary (GH #116): `cat foo=$BIN`/`dd if=$BIN`
                        // must not silently become a path/operand literally named
                        // `foo=[binary: N bytes]`. Source text wins, as in
                        // every other composed-string arm.
                        let val_str = if let Expr::NumericLiteral { raw, .. } = value {
                            raw.clone()
                        } else {
                            crate::interpreter::value_to_text_sink_named(
                                &val,
                                "a key=value argument",
                            )
                            .map_err(|e| anyhow::anyhow!("{e}"))?
                        };
                        tool_args.positional.push(Value::String(format!("{key}={val_str}")));
                    }
                }
            }
            Arg::ShortFlag(name) => {
                if past_double_dash {
                    tool_args.positional.push(Value::String(format!("-{name}")));
                } else if name.len() == 1 {
                    let flag_name = name.as_str();
                    let lookup = param_lookup.get(flag_name);

                    // Same ambiguity guard as the `LongFlag` arm below (GH
                    // #189 item 4): an undeclared short flag immediately
                    // followed by an unconsumed positional under a
                    // map_positionals (backend/MCP) schema is exactly as
                    // ambiguous as the long-flag case — kaish can't tell a
                    // space-form value (`-t explorer`) from a bool flag
                    // sitting before a real positional (`-f file.txt`).
                    // Unlike `--flag`, there is no `-f=value` escape hatch to
                    // suggest: a glued `-f=val` is two tokens with a dangling
                    // `=` that the parser's no-token-pasting guard already
                    // rejects — the only fix is declaring the flag.
                    let ambiguous_value = (lookup.is_none()
                        && leaf.is_some_and(|s| s.map_positionals)
                        && !consumed.contains(&(i + 1)))
                        .then(|| match args.get(i + 1) {
                            Some(Arg::Positional(Expr::Literal(Value::String(s)))) => {
                                Some(s.clone())
                            }
                            Some(Arg::Positional(_)) => Some("VALUE".to_string()),
                            _ => None,
                        })
                        .flatten();
                    if let Some(val) = ambiguous_value {
                        let tool = leaf.map(|s| s.name.as_str()).unwrap_or("command");
                        anyhow::bail!(
                            "{tool}: -{name} is not a declared flag, so the \
                             space-separated value ({val:?}) would be silently \
                             dropped. Have {tool} declare -{name} in its schema \
                             (short flags have no -{name}=value form to fall \
                             back on)."
                        );
                    }

                    let is_bool = lookup.map(|(_, typ, ..)| is_bool_type(typ)).unwrap_or(true);

                    if is_bool {
                        tool_args.flags.insert(flag_name.to_string());
                    } else {
                        // Non-bool: consume `consumes` positionals as value(s)
                        let canonical = lookup.map(|(n, ..)| *n).unwrap_or(flag_name);
                        let consumes = lookup.map(|(_, _, c, _)| *c).unwrap_or(1);
                        let repeatable = lookup.map(|(_, _, _, r)| *r).unwrap_or(false);
                        consume_flag_positionals(
                            source,
                            home.as_deref(),
                            args,
                            name,
                            canonical,
                            consumes,
                            repeatable,
                            &positional_indices,
                            &mut consumed,
                            i,
                            &mut tool_args,
                        )
                        .await?;
                    }
                } else if let Some(&(canonical, typ, consumes, repeatable)) = param_lookup.get(name.as_str()) {
                    // Multi-char short flag matches a schema param (POSIX style: -name value)
                    if is_bool_type(typ) {
                        tool_args.flags.insert(canonical.to_string());
                    } else {
                        consume_flag_positionals(
                            source,
                            home.as_deref(),
                            args,
                            name,
                            canonical,
                            consumes,
                            repeatable,
                            &positional_indices,
                            &mut consumed,
                            i,
                            &mut tool_args,
                        )
                        .await?;
                    }
                } else if let Some(&(canonical, _, consumes, repeatable)) = param_lookup
                    .get(&name[..1])
                    .filter(|(_, typ, ..)| !is_bool_type(typ))
                {
                    // Glued short-flag value: `cut -f1`, `head -c5`, `cut -f1-3`,
                    // `grep -A1`, `sed -e1d`. The first char is a declared
                    // value-taking short flag, so the rest of the token is its
                    // value — the coreutils idiom. The lexer's flag char class is
                    // `[a-zA-Z][a-zA-Z0-9-]*`, so the first byte is always ASCII
                    // (safe to slice) and the tail is a plain literal.
                    bind_glued_short_value(
                        &mut tool_args,
                        &name[..1],
                        canonical,
                        consumes,
                        repeatable,
                        name[1..].to_string(),
                    )?;
                } else {
                    // Multi-char combined short flags. Bool flags stack
                    // (`-la`), but the FIRST value-taking flag reached
                    // consumes the rest of the token as its glued value
                    // (`-ivC3` → C=3) or, if it is the last char, the next
                    // positional (`grep -ivC 3` → C=3). Before this, a
                    // trailing value-flag was silently treated as a bool,
                    // stranding its argument as a stray positional (arity
                    // error). Undeclared/bool chars stay bare flags, so a
                    // schemaless tool keeps the old all-boolean behavior.
                    // The first char being value-taking is handled by the
                    // glued arm above, so it never reaches here. The flag
                    // char class is ASCII, so byte indexing is char indexing
                    // (no `Vec<char>` allocation needed).
                    let bytes = name.as_bytes();
                    let mut p = 0;
                    while p < bytes.len() {
                        let key = &name[p..p + 1];
                        match param_lookup.get(key) {
                            Some(&(canonical, typ, consumes, repeatable))
                                if !is_bool_type(typ) =>
                            {
                                let glued = name[p + 1..].to_string();
                                if glued.is_empty() {
                                    // Value flag is the last char: take the
                                    // next positional. `consume_flag_positionals`
                                    // respects `consumes`.
                                    consume_flag_positionals(
                                        source,
                                        home.as_deref(),
                                        args,
                                        key,
                                        canonical,
                                        consumes,
                                        repeatable,
                                        &positional_indices,
                                        &mut consumed,
                                        i,
                                        &mut tool_args,
                                    )
                                    .await?;
                                } else {
                                    bind_glued_short_value(
                                        &mut tool_args,
                                        key,
                                        canonical,
                                        consumes,
                                        repeatable,
                                        glued,
                                    )?;
                                }
                                break;
                            }
                            _ => {
                                tool_args.flags.insert(key.to_string());
                                p += 1;
                            }
                        }
                    }
                }
            }
            Arg::LongFlag(name) => {
                if past_double_dash {
                    tool_args.positional.push(Value::String(format!("--{name}")));
                } else {
                    let lookup = param_lookup.get(name.as_str());
                    // An *undeclared* long flag under a `map_positionals`
                    // (backend/MCP) schema that is immediately followed by an
                    // unconsumed positional is ambiguous: kaish can't tell the
                    // space-form value (`--type explorer`) from a bool flag
                    // before a real positional (`--force file.txt`). Defaulting
                    // to bool here silently divorces the value and misroutes it
                    // — a privilege-escalation-by-typo against deny-by-default
                    // embedders. Fail loud instead of guessing.
                    let ambiguous_value = (lookup.is_none()
                        && leaf.is_some_and(|s| s.map_positionals)
                        && !consumed.contains(&(i + 1)))
                        .then(|| match args.get(i + 1) {
                            // Echo a concrete value for a copy-pasteable fix
                            // when it's a plain literal; fall back to VALUE.
                            Some(Arg::Positional(Expr::Literal(Value::String(s)))) => {
                                Some(s.clone())
                            }
                            Some(Arg::Positional(_)) => Some("VALUE".to_string()),
                            _ => None,
                        })
                        .flatten();
                    if let Some(val) = ambiguous_value {
                        let tool = leaf.map(|s| s.name.as_str()).unwrap_or("command");
                        anyhow::bail!(
                            "{tool}: --{name} is not a declared flag, so the \
                             space-separated value would be silently dropped. \
                             Use --{name}={val}, or have {tool} declare --{name} \
                             in its schema."
                        );
                    }
                    let is_bool = lookup.map(|(_, typ, ..)| is_bool_type(typ)).unwrap_or(true);

                    if is_bool {
                        tool_args.flags.insert(name.clone());
                    } else {
                        let canonical = lookup.map(|(n, ..)| *n).unwrap_or(name.as_str());
                        let consumes = lookup.map(|(_, _, c, _)| *c).unwrap_or(1);
                        let repeatable = lookup.map(|(_, _, _, r)| *r).unwrap_or(false);
                        consume_flag_positionals(
                            source,
                            home.as_deref(),
                            args,
                            name,
                            canonical,
                            consumes,
                            repeatable,
                            &positional_indices,
                            &mut consumed,
                            i,
                            &mut tool_args,
                        )
                        .await?;
                    }
                }
            }
        }
        i += 1;
    }

    // Map remaining positionals to unfilled non-bool schema params (in order).
    // This enables `drift_push "abc" "hello"` → named["target_ctx"] = "abc", named["content"] = "hello"
    // Positionals that appeared after `--` are never mapped (they're raw data).
    // Only for backend/external tools (map_positionals=true). Builtins handle their own positionals.
    // Keyed off the routed leaf so a subcommand tool maps against the active
    // leaf's params (kj leaves keep map_positionals=false → block skipped).
    if let Some(schema) = leaf.filter(|s| s.map_positionals) {
        let pre_dash_count = if past_double_dash {
            let dash_pos = args.iter().position(|a| matches!(a, Arg::DoubleDash)).unwrap_or(args.len());
            positional_indices.iter()
                .filter(|idx| **idx < dash_pos && !consumed.contains(idx))
                .count()
        } else {
            tool_args.positional.len()
        };

        // This block reindexes `positional`, and `positional_raw` is keyed
        // by index — a value that moves must carry its raw text along or the
        // map mislabels some other positional's text as this one's.
        // `old_raw` is keyed by the pre-drain index; both destinations insert
        // under the index the value actually lands at.
        let old_raw = std::mem::take(&mut tool_args.positional_raw);
        let mut remaining = Vec::new();
        let mut remaining_raw: std::collections::BTreeMap<usize, String> =
            std::collections::BTreeMap::new();
        let mut positional_iter = tool_args.positional.drain(..).enumerate();

        for param in &schema.params {
            if tool_args.named.contains_key(&param.name) || tool_args.flags.contains(&param.name) {
                continue;
            }
            if is_bool_type(&param.param_type) {
                continue;
            }
            loop {
                match positional_iter.next() {
                    Some((idx, val)) if idx < pre_dash_count => {
                        if let Some(raw) = old_raw.get(&idx) {
                            tool_args.named_raw.insert(param.name.clone(), raw.clone());
                        }
                        tool_args.named.insert(param.name.clone(), val);
                        break;
                    }
                    Some((idx, val)) => {
                        if let Some(raw) = old_raw.get(&idx) {
                            remaining_raw.insert(remaining.len(), raw.clone());
                        }
                        remaining.push(val);
                    }
                    None => break,
                }
            }
        }

        for (idx, val) in positional_iter {
            if let Some(raw) = old_raw.get(&idx) {
                remaining_raw.insert(remaining.len(), raw.clone());
            }
            remaining.push(val);
        }
        tool_args.positional = remaining;
        tool_args.positional_raw = remaining_raw;
    }

    Ok(tool_args)
}

#[async_trait]
impl CommandDispatcher for Kernel {
    /// Dispatch a command through the Kernel's full resolution chain.
    ///
    /// This is the single path for all command execution when called from
    /// the pipeline runner. It provides the full dispatch chain:
    /// user tools → builtins → .kai scripts → external commands → backend tools.
    async fn dispatch(&self, cmd: &Command, ctx: &mut ExecContext) -> Result<ExecResult> {
        self.dispatch_command(cmd, ctx).await
    }

    /// Run a compound pipeline stage through the kernel's statement executor.
    async fn dispatch_stmt(&self, stmt: &Stmt, ctx: &mut ExecContext) -> Result<ExecResult> {
        self.dispatch_statement(stmt, ctx).await
    }

    /// Evaluate an expression through the kernel's async chain, including
    /// command substitution. Delegates to `eval_expr_async`, which snapshots
    /// the kernel's scope/cwd and restores them after any `$(...)` runs, so
    /// only command output escapes. The `ctx` is unused here because the
    /// kernel evaluates against its own session state (a fork carries the
    /// pipeline stage's snapshot); var refs resolve against that scope.
    async fn eval_expr(&self, expr: &Expr, _ctx: &ExecContext) -> Result<Value> {
        self.eval_expr_async(expr).await
    }

    /// Produce a forked dispatcher with independent mutable state (detached).
    ///
    /// Calls the inherent `Kernel::fork` method (note the UFCS to avoid
    /// recursing into the trait method we're defining) and coerces the
    /// returned `Arc<Kernel>` to `Arc<dyn CommandDispatcher>`.
    async fn fork(&self) -> Arc<dyn CommandDispatcher> {
        let fork: Arc<Kernel> = Kernel::fork(self).await;
        fork
    }

    /// Produce a forked dispatcher with cancellation cascading from this kernel.
    async fn fork_attached(&self) -> Arc<dyn CommandDispatcher> {
        let fork: Arc<Kernel> = Kernel::fork_attached(self).await;
        fork
    }
}

/// Apply the requested output format to a builtin's result, unless the tool
/// owns its own output — and even then, only on success.
///
/// `format` is `ctx.output_format` (set from `--json`). `owns_output` means
/// "this tool renders its own bespoke SUCCESS envelope" (scatter/gather's
/// JSONL/array rendering), not "never touch this tool's bytes" — scatter and
/// gather never render a structured error themselves, so a failure
/// (`ExecResult::failure(code, msg)`, plain text, no `.data`/`.output`) was
/// never "already rendered" by the tool. Skipping `apply_output_format` on
/// that path just leaked the raw diagnostic under `--json` instead of the
/// uniform `{"error","code"}` envelope every other builtin's failure gets
/// (kaibo review finding on merged PR #215, confirmed pre-existing for the
/// whole owns_output error-path class). Gating the skip on `result.ok()`
/// keeps the intentional success-path opt-out while closing that gap.
fn finalize_output(
    result: ExecResult,
    format: Option<crate::interpreter::OutputFormat>,
    owns_output: bool,
) -> ExecResult {
    match format {
        Some(_) if owns_output && result.ok() => result,
        Some(format) => apply_output_format(result, format),
        None => result,
    }
}

/// Accumulate output from one result into another.
///
/// Appends stdout and stderr verbatim and updates the exit code to match the
/// new result. Used to preserve output from multiple statements, loop
/// iterations, and command chains. No separator is inserted between outputs —
/// each command's output concatenates raw, matching bash (`printf a; printf b`
/// and `printf a && printf b` both yield `ab`; a trailing newline only appears
/// when a command emits its own, as `echo` does).
/// Append `new`'s stdout to `accumulated`'s, and nothing else.
///
/// Split out of [`accumulate_result`] because a condition carries only its
/// stdout up to the enclosing statement — its exit code is the `if`/`while`'s
/// answer, not the statement's status. Sharing the append keeps the two
/// callers from drifting on the byte handling below.
fn push_stdout_of(accumulated: &mut ExecResult, new: &ExecResult) {
    // Materialize lazy OutputData into .out before accumulating.
    // Without this, the first command's output stays in .output while
    // the second's text gets appended to .out, losing the first.
    accumulated.materialize();
    match new.out_bytes() {
        // A binary result must not be lossy-decoded by text_out(): concatenate
        // raw bytes so the combined output stays binary (this is the path every
        // top-level statement's result flows through). See docs/binary-data.md.
        Some(new_bytes) => {
            let mut combined: Vec<u8> = match accumulated.out_bytes() {
                Some(b) => b.to_vec(),
                None => accumulated.text_out().into_owned().into_bytes(),
            };
            combined.extend_from_slice(new_bytes);
            accumulated.set_out_bytes(combined);
        }
        None => accumulated.push_out(&new.text_out()),
    }
}

fn accumulate_result(accumulated: &mut ExecResult, new: &ExecResult) {
    push_stdout_of(accumulated, new);
    accumulated.err.push_str(&new.err);
    accumulated.code = new.code;
    // The marker travels WITH the data, always. Copying one without the other
    // is wrong in both directions: a compound statement ending in `fromjson`
    // lost its value (`$(if true; then fromjson '[1,2]'; fi)` bound text), and
    // a chain whose LEFT side was typed kept that marker over the right side's
    // data (`$(fromjson '[1,2]' && cut -f2 f)` bound `["b"]` typed — the very
    // bug this mechanism exists to fix, re-entering through a side door).
    accumulated.data = new.data.clone();
    accumulated.data_is_value = new.data_is_value;
    // Assign, like `code`: the combined result IS `new`'s value, so it is a
    // fault exactly when `new` is. This lets an outer chain see a fault that
    // arrived through an inner chain's right operand.
    accumulated.fault = new.fault;
    // OR, not assign. `did_spill` is a fact about the OUTPUT — this block's
    // text was truncated — and an ordinary statement running afterwards does
    // not untruncate it. Assigning let `seq …; echo after` report
    // `did_spill: false` with output still missing, telling an embedder asking
    // "did I get everything" the wrong thing. The exit CODE is a separate
    // question and still belongs to the last statement, as in any shell.
    accumulated.did_spill |= new.did_spill;
    // `original_code` is only meaningful alongside a spill, so it follows the
    // same rule: keep the first one rather than letting a later clean
    // statement's `None` erase the code the spill replaced.
    if accumulated.original_code.is_none() {
        accumulated.original_code = new.original_code;
    }
    accumulated.content_type = new.content_type.clone();
    accumulated.baggage.clone_from(&new.baggage);
}

/// Fold a block's accumulated output into a signal that is leaving the block.
///
/// Any block that builds up a result — a loop body, an `if`/`case` branch, the
/// left side of a `&&`/`||` chain — hands that result back when it finishes.
/// When `break`/`continue`/`return`/`exit` leaves early instead, the signal
/// replaces the result on the way up, so output printed before the signal
/// would otherwise be discarded. Leaving early stops the block; it does not
/// unprint what already ran. The block's output comes first (it ran before the
/// signal was raised), then the signal's already-carried output.
fn fold_block_output_into_flow(block_output: ExecResult, flow: &mut ControlFlow) {
    let carried = match flow {
        ControlFlow::Break { result, .. }
        | ControlFlow::Continue { result, .. }
        | ControlFlow::Exit { result, .. } => result,
        ControlFlow::Return { value } => value,
        ControlFlow::Normal(_) => return,
    };
    let mut merged = block_output;
    accumulate_result(&mut merged, carried);
    *carried = merged;
}

/// Accumulate the output a break/continue signal carried (from inner loops it
/// propagated through) into the loop that finally handles it, so it survives
/// into that loop's result.
fn accumulate_flow_output(accumulated: &mut ExecResult, flow: &ControlFlow) {
    if let ControlFlow::Break { result, .. } | ControlFlow::Continue { result, .. } = flow {
        // `break`/`continue` carry no value of their own, and a signal that
        // produced nothing must not erase what the body already produced —
        // leaving a loop early stops it, it does not unmake its output. Same
        // reasoning as `fold_block_output_into_flow`'s, one step further:
        // `$(while true; do fromjson '[5]'; break; done)` bound text because
        // the empty `break` result overwrote the body's value.
        let carried = (accumulated.data.take(), accumulated.data_is_value);
        accumulate_result(accumulated, result);
        if result.data.is_none() {
            (accumulated.data, accumulated.data_is_value) = carried;
        }
    }
}

/// Check if a value is truthy.
fn is_truthy(value: &Value) -> bool {
    match value {
        Value::Null => false,
        Value::Bool(b) => *b,
        Value::Int(i) => *i != 0,
        Value::Float(f) => *f != 0.0,
        Value::String(s) => !s.is_empty(),
        Value::Json(json) => match json {
            serde_json::Value::Null => false,
            serde_json::Value::Array(arr) => !arr.is_empty(),
            serde_json::Value::Object(obj) => !obj.is_empty(),
            serde_json::Value::Bool(b) => *b,
            serde_json::Value::Number(n) => n.as_f64().map(|f| f != 0.0).unwrap_or(false),
            serde_json::Value::String(s) => !s.is_empty(),
        },
        Value::Bytes(b) => !b.is_empty(), // empty bytes are falsy, like ""
    }
}

/// Apply tilde expansion to a value.
///
/// Only string values starting with `~` are expanded. `home` is the session
/// `HOME` from the kernel scope (the kernel is hermetic and never reads the
/// host env); `None` leaves `~`/`~/path` unexpanded. See [`expand_tilde`].
fn apply_tilde_expansion(value: Value, home: Option<&str>) -> Value {
    match value {
        Value::String(s) if s.starts_with('~') => Value::String(expand_tilde(&s, home)),
        _ => value,
    }
}

/// Classify an already-tokenized argv (`&[Value]`) into AST [`Arg`]s, mirroring
/// how the lexer tokenizes the equivalent minimally-quoted command string —
/// the seam that lets [`Kernel::execute_argv`] reuse the string door's binder
/// (`build_args_async`) verbatim instead of carrying a parallel one that could
/// drift. Tokens are literal: every string becomes an `Expr::Literal`, never an
/// `Expr::GlobPattern` or `VarRef`, so no glob/`$VAR`/`$()`/split can occur.
///
/// Classification matches the lexer's word classes:
/// - `--` → [`Arg::DoubleDash`] (subsequent flags are demoted to positionals by
///   the binder's `past_double_dash` arms, exactly as for the string door).
/// - `--name=value` → [`Arg::Named`]; `--name` → [`Arg::LongFlag`].
/// - `-x…` where the first char after `-` is an ASCII letter → [`Arg::ShortFlag`]
///   (the lexer's flag char class begins `[a-zA-Z]`; `-1`/`-9` lex as numbers, so
///   they fall through to a positional, not a flag).
/// - `key=value` with an identifier LHS → [`Arg::WordAssign`] (the binder either
///   binds it to a preceding value-flag — `awk -v x=1` — or stringifies it to a
///   `key=value` positional, per the command's word-assign allowlist).
/// - everything else → a literal [`Arg::Positional`].
///
/// A **non-string** `Value` (`Bytes`/`Json`/`Int`/`Bool`) is always a literal
/// positional — it can never be a flag — and rides through as-is. That is the
/// typed passthrough the string-native door cannot offer.
pub(crate) fn argv_to_args(argv: &[Value]) -> Vec<Arg> {
    argv.iter().map(classify_argv_token).collect()
}

fn classify_argv_token(token: &Value) -> Arg {
    let Value::String(s) = token else {
        return Arg::Positional(Expr::Literal(token.clone()));
    };

    if s == "--" {
        return Arg::DoubleDash;
    }

    // Long flag: the lexer requires `--[a-zA-Z]…`. `---`, `--=v`, `--1` are NOT
    // long-flag words — the lexer now tokenizes each as one `DoubleDashBare`
    // literal word (GH #137), matching this classifier's own literal
    // fallback — so they fall through to a literal positional rather than a
    // silently-misbound `LongFlag("-")` / empty-key `Named{ key: "" }`.
    if let Some(rest) = s.strip_prefix("--") {
        if rest.starts_with(|c: char| c.is_ascii_alphabetic()) {
            return match rest.split_once('=') {
                Some((key, val)) => Arg::Named {
                    key: key.to_string(),
                    value: Expr::Literal(Value::String(val.to_string())),
                },
                None => Arg::LongFlag(rest.to_string()),
            };
        }
    } else if let Some(rest) = s.strip_prefix('-') {
        // Short flag: the lexer's flag char class is `[a-zA-Z][a-zA-Z0-9-]*`. A
        // token carrying any other char — notably `=` (`-k=v` is a parse error in
        // the string door) — or a leading digit (`-1` lexes as a number) is not a
        // short-flag word, so it falls through to a literal positional instead of
        // a `ShortFlag("k=v")` the binder would mangle into a stray `=` flag.
        if is_short_flag_body(rest) {
            return Arg::ShortFlag(rest.to_string());
        }
    }

    if let Some((key, val)) = s.split_once('=') {
        if is_shell_identifier(key) {
            return Arg::WordAssign {
                key: key.to_string(),
                value: Expr::Literal(Value::String(val.to_string())),
            };
        }
    }

    Arg::Positional(Expr::Literal(Value::String(s.clone())))
}

/// A short-flag word: a leading ASCII letter, then only ASCII
/// letters/digits/`-` (the lexer's base `-[a-zA-Z][a-zA-Z0-9-]*` regex) or `:`
/// (which `merge_flag_metachar_adjacent` glues onto a `ShortFlag` for the
/// `awk -F:` idiom). `-la`, `-A1`, `-a:` qualify; `-1` (a number), `-k=v`
/// (`=` is the assignment operator — a parse error in the string door), and
/// any non-ASCII tail (never produced by the lexer, and not safe for the
/// combined-short-flag binder's byte-index slicing) do not, so they fall
/// through to a literal positional instead of a malformed `ShortFlag`.
fn is_short_flag_body(s: &str) -> bool {
    s.starts_with(|c: char| c.is_ascii_alphabetic())
        && s.chars().all(|c| c.is_ascii_alphanumeric() || c == '-' || c == ':')
}

/// Bash-style assignment-LHS identifier: `[A-Za-z_][A-Za-z0-9_]*`.
fn is_shell_identifier(s: &str) -> bool {
    let mut chars = s.chars();
    match chars.next() {
        Some(c) if c.is_ascii_alphabetic() || c == '_' => {}
        _ => return false,
    }
    chars.all(|c| c.is_ascii_alphanumeric() || c == '_')
}

/// Accumulate one occurrence of a repeatable value flag (e.g. sed `-e`) under
/// `named[canonical]` as a flat `Value::Json(Array(...))`, in invocation order.
/// Never overwrites — that's the whole point of `repeatable`: a repeated flag
/// must keep every value, not silently drop all but the last. Used by every flag
/// surface that can carry the same flag twice — the space form
/// (`consume_flag_positionals`) and the `--flag=value` form (`Arg::Named`) — so
/// `-e A -e B`, `--expression=A --expression=B`, and any mix all converge on one
/// ordered array.
/// Flatten a bound flag value to JSON, going LOUD on binary.
///
/// The accumulating flag forms (`jq --arg NAME VAL`, `sed -e EXPR -e EXPR`)
/// store their values as `serde_json::Value` rather than keeping the kaish
/// `Value`, and [`value_to_json`](crate::interpreter::value_to_json) renders a
/// `Value::Bytes` as the base64 envelope
/// (`{"_type":"bytes","encoding":"base64",…}`). That envelope is an internal
/// wire form, not the user's data: bound into `--arg x`, the tool sees the
/// envelope's literal JSON *text* where the bytes should be and reports
/// success, which is silent corruption (GH #223). Binary stops here instead,
/// with the same wording and exit 1 as every other text sink.
///
/// Valid-UTF-8 bytes coerce to their text, matching
/// [`value_to_text_sink_named`](crate::interpreter::value_to_text_sink_named);
/// in practice `Value::Bytes` only ever holds non-UTF-8, so this errors
/// whenever binary reaches a flag value. Gating on the kaish `Value` (not on
/// the envelope's JSON shape) is what keeps an envelope-shaped record the user
/// actually built — `fromjson '{"_type":"bytes",…}'` — a plain record: kaish
/// never sniffs JSON to decide a type.
fn flag_value_to_json(canonical: &str, v: &Value) -> Result<serde_json::Value> {
    match v {
        Value::Bytes(_) => crate::interpreter::value_to_text_sink_named(
            v,
            &format!("the value of the {canonical} flag"),
        )
        .map(serde_json::Value::String)
        .map_err(|e| anyhow::anyhow!("{e}")),
        other => Ok(crate::interpreter::value_to_json(other)),
    }
}

pub(crate) fn push_repeatable_value(
    tool_args: &mut ToolArgs,
    flag_name: &str,
    canonical: &str,
    v: Value,
) -> anyhow::Result<()> {
    let occ = flag_value_to_json(canonical, &v)?;
    let entry = tool_args
        .named
        .entry(canonical.to_string())
        .or_insert_with(|| Value::Json(serde_json::Value::Array(Vec::new())));
    if let Value::Json(serde_json::Value::Array(items)) = entry {
        items.push(occ);
        Ok(())
    } else {
        anyhow::bail!("--{flag_name}: named[{canonical}] already holds a non-array value")
    }
}

/// Bind a *glued* short-flag value (`-f1` → f=1, `-e1d`, `-A2`). The whole tail
/// is one token, so it carries a single value: a repeatable flag accumulates
/// (never clobbers — `-e1d -e2d` keeps both), a plain one inserts. Shared by the
/// first-char glued arm and the combined-bundle arm so the two can't drift on
/// `repeatable` handling. A `consumes > 1` flag can't be expressed glued — that
/// is a loud error, not a silent single-value bind.
pub(crate) fn bind_glued_short_value(
    tool_args: &mut ToolArgs,
    flag_name: &str,
    canonical: &str,
    consumes: usize,
    repeatable: bool,
    value: String,
) -> anyhow::Result<()> {
    if consumes > 1 {
        anyhow::bail!(
            "-{flag_name} takes {consumes} arguments; use the separated form, not a glued value"
        );
    }
    if repeatable {
        push_repeatable_value(tool_args, flag_name, canonical, Value::String(value))
    } else {
        tool_args
            .named
            .insert(canonical.to_string(), Value::String(value));
        Ok(())
    }
}

/// Map a child's exit status to a shell-style exit code.
///
/// `ExitStatus::code()` is `None` when the process died from a signal rather
/// than exiting normally; in that case this maps to POSIX's `128 + signal`
/// convention (SIGKILL → 137, SIGTERM → 143, …) instead of losing the signal
/// number. Shared by both external-command spawn sites — production
/// (`try_execute_external`, below) and the test-only twin
/// (`dispatch.rs::BackendDispatcher::try_external`) — so they can't drift on
/// this mapping again (GH #133 item 1).
#[cfg(feature = "subprocess")]
pub(crate) fn exit_code_from_status(status: &std::process::ExitStatus) -> i64 {
    status.code().unwrap_or_else(|| {
        #[cfg(unix)]
        {
            use std::os::unix::process::ExitStatusExt;
            128 + status.signal().unwrap_or(0)
        }
        #[cfg(not(unix))]
        {
            -1
        }
    }) as i64
}

/// Wait for a child to exit, killing it if `cancel` fires first.
///
/// `target` carries a Linux pidfd (when available) for race-free direct-child
/// kill; fall-through to PID-based kill otherwise. On non-unix targets the
/// parameter is ignored and we use tokio's cross-platform `start_kill`.
#[cfg(all(unix, feature = "subprocess"))]
pub(crate) async fn wait_or_kill(
    child: &mut tokio::process::Child,
    target: Option<&crate::pidfd::KillTarget>,
    cancel: &tokio_util::sync::CancellationToken,
    grace: Duration,
) -> std::io::Result<std::process::ExitStatus> {
    tokio::select! {
        biased;
        status = child.wait() => status,
        _ = cancel.cancelled() => kill_with_grace(child, target, grace).await,
    }
}

#[cfg(all(not(unix), feature = "subprocess"))]
pub(crate) async fn wait_or_kill(
    child: &mut tokio::process::Child,
    _target: Option<&()>,
    cancel: &tokio_util::sync::CancellationToken,
    _grace: Duration,
) -> std::io::Result<std::process::ExitStatus> {
    tokio::select! {
        biased;
        status = child.wait() => status,
        _ = cancel.cancelled() => {
            let _ = child.start_kill();
            child.wait().await
        }
    }
}

/// Send SIGTERM to the child and its process group; wait `grace`; then SIGKILL.
///
/// Direct-child kill goes through `target.signal()`, which on Linux uses a
/// pidfd (immune to PID reuse). Process-group kill uses `killpg` — there is
/// no PGID-equivalent of pidfd, so grandchildren retain a small reuse window.
#[cfg(all(unix, feature = "subprocess"))]
pub(crate) async fn kill_with_grace(
    child: &mut tokio::process::Child,
    target: Option<&crate::pidfd::KillTarget>,
    grace: Duration,
) -> std::io::Result<std::process::ExitStatus> {
    use nix::sys::signal::Signal;

    if let Some(t) = target {
        t.signal(Signal::SIGTERM);
        t.signal_pg(Signal::SIGTERM);
        if grace > Duration::ZERO
            && let Ok(status) = tokio::time::timeout(grace, child.wait()).await
        {
            return status;
        }
        t.signal(Signal::SIGKILL);
        t.signal_pg(Signal::SIGKILL);
    }
    child.wait().await
}

#[cfg(test)]
#[allow(clippy::unwrap_used, clippy::expect_used)]
mod argv_classify_tests {
    use super::*;

    /// A normalized, comparable view of one `Arg` representing its *logical
    /// argument* (what the command observably receives), not its exact AST shape:
    ///
    /// - Value-bearing arms compare by *stringified* value, so the parser's
    ///   number coercion (`-1`→`Int(-1)`) vs the classifier's literal
    ///   (`String("-1")`) count as the same argument.
    /// - `WordAssign{k,v}` collapses to the *same* form as a `Positional("k=v")`.
    ///   For every command except the `export`/`alias` allowlist, a bareword
    ///   `key=value` is stringified straight back to a `"key=value"` positional
    ///   (bash: `cat foo=bar` opens a file named `foo=bar`). So the two doors
    ///   converge observably even when they disagree on the AST tag — e.g. the
    ///   lexer colon-merges `:A` into one `Ident` and parses `:A=0` as a
    ///   `WordAssign`, where the classifier (bash-correctly) makes a positional.
    ///   The genuine `WordAssign` *detection* on a real identifier LHS is pinned
    ///   separately by `classifies_each_word_class`.
    ///
    /// Returns `None` for shapes we deliberately don't compare:
    /// - a parsed glob/interp `Expr`, which argv-native semantics never produce;
    /// - a parsed literal the lexer **number-coerced** (`Int`/`Float`). `00`/`-1`
    ///   lex to `Int`, dropping the literal text, where the classifier keeps the
    ///   string. That divergence is *intentional* — `execute_argv` preserves a
    ///   literal numeric string (pass `Value::Int` for a number), the string door
    ///   can only guess — so the property skips it rather than demanding the
    ///   classifier replicate a lossy coercion. Numeric edges are pinned exactly
    ///   by `classifies_each_word_class`.
    fn canonical(arg: &Arg) -> Option<(&'static str, String, String)> {
        // Only a *string*-valued literal is comparable; a coerced number is not.
        let lit = |e: &Expr| match e {
            Expr::Literal(Value::String(s)) => Some(s.clone()),
            _ => None,
        };
        Some(match arg {
            Arg::DoubleDash => ("dash", String::new(), String::new()),
            Arg::ShortFlag(s) => ("short", s.clone(), String::new()),
            Arg::LongFlag(s) => ("long", s.clone(), String::new()),
            Arg::Positional(e) => ("pos", String::new(), lit(e)?),
            Arg::Named { key, value } => ("named", key.clone(), lit(value)?),
            Arg::WordAssign { key, value } => ("pos", String::new(), format!("{key}={}", lit(value)?)),
        })
    }

    /// Classify a single string token the way `execute_argv` would.
    fn classify(token: &str) -> Arg {
        classify_argv_token(&Value::String(token.to_string()))
    }

    #[test]
    fn classifies_each_word_class() {
        assert_eq!(classify("--"), Arg::DoubleDash);
        assert_eq!(classify("-l"), Arg::ShortFlag("l".into()));
        assert_eq!(classify("-la"), Arg::ShortFlag("la".into()));
        assert_eq!(classify("--force"), Arg::LongFlag("force".into()));
        assert_eq!(
            classify("--key=value"),
            Arg::Named { key: "key".into(), value: Expr::Literal(Value::String("value".into())) }
        );
        assert_eq!(
            classify("NAME=val"),
            Arg::WordAssign { key: "NAME".into(), value: Expr::Literal(Value::String("val".into())) }
        );
        // Digits after the first flag char are ordinary (kept verbatim).
        assert_eq!(classify("-A1"), Arg::ShortFlag("A1".into()));
        assert_eq!(classify("--type2"), Arg::LongFlag("type2".into()));
        // Leading-digit dash is a number to the lexer, not a flag → positional.
        assert_eq!(classify("-1"), Arg::Positional(Expr::Literal(Value::String("-1".into()))));
        // Numeric strings keep their literal text — `execute_argv` does NOT
        // coerce (the string door's lexer would: `00`→`Int(0)`→"0"). A caller
        // who wants a number passes `Value::Int`; a string stays the string.
        assert_eq!(classify("00"), Arg::Positional(Expr::Literal(Value::String("00".into()))));
        assert_eq!(classify("1.50"), Arg::Positional(Expr::Literal(Value::String("1.50".into()))));
        // A lone dash (stdin convention) is a positional, not a flag.
        assert_eq!(classify("-"), Arg::Positional(Expr::Literal(Value::String("-".into()))));
        // Non-identifier LHS is not an assignment.
        assert_eq!(classify("1=2"), Arg::Positional(Expr::Literal(Value::String("1=2".into()))));
        assert_eq!(classify("plain"), Arg::Positional(Expr::Literal(Value::String("plain".into()))));
    }

    #[test]
    fn typed_values_pass_through_as_literal_positionals() {
        // The whole point of the `&[Value]` signature: a non-string value is a
        // literal positional carrying the *exact* value, never stringified and
        // never flag-interpreted.
        let bytes = Value::Bytes(vec![0u8, 159, 146, 150]); // invalid UTF-8 on purpose
        assert_eq!(
            classify_argv_token(&bytes),
            Arg::Positional(Expr::Literal(bytes.clone()))
        );
        let json = Value::Json(serde_json::json!({"a": 1, "b": [2, 3]}));
        assert_eq!(
            classify_argv_token(&json),
            Arg::Positional(Expr::Literal(json.clone()))
        );
        // An integer token that *looks* like a flag is still a positional value
        // (only strings are inspected for a leading dash).
        assert_eq!(
            classify_argv_token(&Value::Int(-9)),
            Arg::Positional(Expr::Literal(Value::Int(-9)))
        );
    }

    #[test]
    fn double_dash_only_matches_exactly() {
        // `--` is the marker; `--x` is a long flag. `---` is not a flag word
        // (the lexer lexes it as one `DoubleDashBare` literal word, GH #137);
        // as a single argv token here it's likewise literal.
        assert_eq!(classify("--"), Arg::DoubleDash);
        assert_eq!(classify("--x"), Arg::LongFlag("x".into()));
        assert_eq!(classify("---"), Arg::Positional(Expr::Literal(Value::String("---".into()))));
    }

    #[test]
    fn malformed_flag_words_fall_back_to_literal_positionals() {
        // A token that isn't a well-formed flag word must NOT be silently misbound
        // into the arg binder (house rule: loud/visible over silent-wrong). Each
        // of these is a parse error or different tokenization in the string door,
        // so the argv door keeps them as literal positionals.
        let pos = |t: &str| Arg::Positional(Expr::Literal(Value::String(t.into())));
        // `=` is not in the short-flag char class (`-k=v` parse-errors in the
        // string door); don't emit `ShortFlag("k=v")` for the binder to mangle.
        assert_eq!(classify("-k=v"), pos("-k=v"));
        assert_eq!(classify("-="), pos("-="));
        // Empty long-flag key.
        assert_eq!(classify("--=v"), pos("--=v"));
        // `--` followed by a non-letter is not a long flag.
        assert_eq!(classify("--1"), pos("--1"));
        // A bare dash and a number-dash are positionals (covered above too).
        assert_eq!(classify("-"), pos("-"));
        assert_eq!(classify("-9"), pos("-9"));
        // A non-ASCII tail is not part of the lexer's short-flag char class
        // (`-[a-zA-Z][a-zA-Z0-9-]*`, plus the `:` the metachar-merge pass
        // absorbs) — classifying it as `ShortFlag` would hand the combined
        // short-flag binder a byte string it (correctly, for real ASCII flag
        // words) slices by *byte* index, panicking on a multi-byte char
        // boundary. Fall back to a literal positional instead.
        assert_eq!(classify("-lé"), pos("-lé"));
        assert_eq!(classify("-é"), pos("-é"));
    }

    #[tokio::test]
    async fn non_ascii_short_flag_bundle_does_not_panic() {
        // Regression: `execute_argv`'s combined-short-flag loop assumed the
        // flag body was ASCII (safe to byte-slice) because the lexer's
        // grammar guarantees that on the *string* door. The argv door's
        // classifier let a non-ASCII tail through as `ShortFlag`, so
        // `execute_argv("ls", &["-lé"])` sliced mid-codepoint and panicked.
        let kernel = Kernel::transient().expect("failed to create kernel");
        let result = kernel
            .execute_argv("ls", &[Value::String("-lé".into())])
            .await
            .expect("execute_argv must not panic on a non-ASCII short-flag token");
        // Not a well-formed flag word, so it's a literal positional — `ls`
        // then reports it as a missing path rather than mangling flags.
        assert_ne!(result.code, 0);
    }

    proptest::proptest! {
        /// The core correctness claim: the classifier mirrors the lexer/parser
        /// on metacharacter-free tokens. For any such single token, the `Arg`
        /// the classifier produces matches the one the real parser produces for
        /// the equivalent one-word command — so `execute_argv` reusing the
        /// string door's binder is sound. (First proptest in the workspace.)
        #[test]
        fn classifier_matches_parser_on_clean_tokens(
            // No digits: this property tests the *classification* boundary
            // (dash → flag, `--` → marker, `=` → assignment, colon-merge → one
            // positional), not numeric coercion. The lexer coerces digit runs to
            // `Int`/`Float` and drops the literal text (even inside a colon-merged
            // word: `00:` → `0:`); the classifier intentionally preserves the raw
            // string. Those numeric edges are pinned exactly by the unit tests.
            // Non-ASCII is a word character now, so the generator has to
            // reach it — an ASCII-only strategy tests a shrinking slice of
            // what the classifier actually sees.
            token in "[a-zA-Z_=./@:+\\-\u{00e9}\u{540d}\u{1f600}]{1,8}"
        ) {
            let parsed = match parse(&format!("cmd {token}")) {
                Ok(p) => p,
                Err(_) => return Ok(()), // parser rejects (e.g. empty `a=`) — not our concern
            };
            let [Stmt::Command(cmd)] = parsed.statements.as_slice() else {
                return Ok(());
            };
            // Only compare when the token lexed as exactly one argument.
            let [arg] = cmd.args.as_slice() else { return Ok(()); };

            let (Some(theirs), Some(ours)) = (canonical(arg), canonical(&classify(&token))) else {
                return Ok(()); // a non-literal parsed Expr we don't model — skip
            };
            proptest::prop_assert_eq!(
                ours, theirs,
                "classifier diverged from parser on token {:?}", token
            );
        }
    }
}

#[cfg(all(test, feature = "subprocess"))]
#[allow(clippy::expect_used)]
mod tests {
    use super::*;

    #[tokio::test]
    async fn test_kernel_transient() {
        let kernel = Kernel::transient().expect("failed to create kernel");
        assert_eq!(kernel.name(), "transient");
    }

    #[tokio::test]
    async fn test_kernel_execute_echo() {
        let kernel = Kernel::transient().expect("failed to create kernel");
        let result = kernel.execute("echo hello").await.expect("execution failed");
        assert!(result.ok());
        assert_eq!(result.text_out().trim(), "hello");
    }

    #[tokio::test]
    async fn test_multiple_statements_accumulate_output() {
        let kernel = Kernel::transient().expect("failed to create kernel");
        let result = kernel
            .execute("echo one\necho two\necho three")
            .await
            .expect("execution failed");
        assert!(result.ok());
        // Should have all three outputs separated by newlines
        assert!(result.text_out().contains("one"), "missing 'one': {}", result.text_out());
        assert!(result.text_out().contains("two"), "missing 'two': {}", result.text_out());
        assert!(result.text_out().contains("three"), "missing 'three': {}", result.text_out());
    }

    #[tokio::test]
    async fn test_and_chain_accumulates_output() {
        let kernel = Kernel::transient().expect("failed to create kernel");
        let result = kernel
            .execute("echo first && echo second")
            .await
            .expect("execution failed");
        assert!(result.ok());
        assert!(result.text_out().contains("first"), "missing 'first': {}", result.text_out());
        assert!(result.text_out().contains("second"), "missing 'second': {}", result.text_out());
    }

    #[tokio::test]
    async fn test_for_loop_accumulates_output() {
        let kernel = Kernel::transient().expect("failed to create kernel");
        let result = kernel
            .execute(r#"for X in a b c; do echo "item: ${X}"; done"#)
            .await
            .expect("execution failed");
        assert!(result.ok());
        assert!(result.text_out().contains("item: a"), "missing 'item: a': {}", result.text_out());
        assert!(result.text_out().contains("item: b"), "missing 'item: b': {}", result.text_out());
        assert!(result.text_out().contains("item: c"), "missing 'item: c': {}", result.text_out());
    }

    #[tokio::test]
    async fn test_while_loop_accumulates_output() {
        let kernel = Kernel::transient().expect("failed to create kernel");
        let result = kernel
            .execute(r#"
                N=3
                while [[ ${N} -gt 0 ]]; do
                    echo "N=${N}"
                    N=$((N - 1))
                done
            "#)
            .await
            .expect("execution failed");
        assert!(result.ok());
        assert!(result.text_out().contains("N=3"), "missing 'N=3': {}", result.text_out());
        assert!(result.text_out().contains("N=2"), "missing 'N=2': {}", result.text_out());
        assert!(result.text_out().contains("N=1"), "missing 'N=1': {}", result.text_out());
    }

    #[tokio::test]
    async fn test_kernel_set_var() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        kernel.execute("X=42").await.expect("set failed");

        let value = kernel.get_var("X").await;
        assert_eq!(value, Some(Value::Int(42)));
    }

    #[tokio::test]
    async fn test_kernel_var_expansion() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        kernel.execute("NAME=\"world\"").await.expect("set failed");
        let result = kernel.execute("echo \"hello ${NAME}\"").await.expect("echo failed");

        assert!(result.ok());
        assert_eq!(result.text_out().trim(), "hello world");
    }

    #[tokio::test]
    async fn test_kernel_last_result() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        kernel.execute("echo test").await.expect("echo failed");

        let last = kernel.last_result().await;
        assert!(last.ok());
        assert_eq!(last.text_out().trim(), "test");
    }

    #[tokio::test]
    async fn test_kernel_tool_not_found() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        let result = kernel.execute("nonexistent_tool").await.expect("execution failed");
        assert!(!result.ok());
        assert_eq!(result.code, 127);
        assert!(result.err.contains("command not found"));
    }

    #[tokio::test]
    async fn backend_tool_data_content_type_and_baggage_survive_into_exec_result() {
        // The embedder seam: a backend-registered tool (kaijutsu, an MCP
        // engine, …) returns a `ToolResult` with structured `data` — this
        // must reach the caller's `ExecResult` intact so `x=$(embedder_tool)`
        // and `for r in $(embedder_tool)` see the typed value, not just
        // stdout text.
        use crate::backend::testing::MockBackend;
        use crate::backend::ToolResult;
        let (mock, _calls) = MockBackend::new();
        let backend = mock.with_tool_result(|_name| {
            let mut baggage = std::collections::BTreeMap::new();
            baggage.insert("trace_id".to_string(), "abc123".to_string());
            // ToolResult is #[non_exhaustive] (GH #93 item 3/hygiene pass) —
            // construct via with_data + the with_* setters, not a struct literal.
            Ok(ToolResult::with_data("", serde_json::json!({"key": "value"}))
                .with_content_type("application/json")
                .with_baggage(baggage))
        });
        let backend: Arc<dyn crate::backend::KernelBackend> = Arc::new(backend);
        let kernel = Kernel::with_backend(backend, KernelConfig::isolated(), |_| {}, |_| {})
            .expect("with_backend kernel");

        let result = kernel
            .execute("embedder_tool")
            .await
            .expect("execution failed");
        assert!(result.ok(), "backend tool call should succeed: {result:?}");
        assert_eq!(
            result.data,
            Some(Value::Json(serde_json::json!({"key": "value"}))),
            "backend tool's structured data must survive into ExecResult, not be dropped"
        );
        assert_eq!(
            result.content_type.as_deref(),
            Some("application/json"),
            "backend tool's content_type must survive into ExecResult"
        );
        assert_eq!(
            result.baggage.get("trace_id").map(String::as_str),
            Some("abc123"),
            "backend tool's baggage must survive into ExecResult"
        );
    }

    #[tokio::test]
    async fn backend_tool_execution_error_is_not_reported_as_command_not_found() {
        // A backend tool that IS found but fails during execution (`Io`,
        // `PermissionDenied`, …) must surface its real error, not get
        // misreported as exit-127 "command not found" — that masks a genuine
        // failure as a lookup miss.
        use crate::backend::testing::MockBackend;
        let (mock, _calls) = MockBackend::new();
        let backend = mock.with_tool_result(|_name| Err(BackendError::Io("disk exploded".to_string())));
        let backend: Arc<dyn crate::backend::KernelBackend> = Arc::new(backend);
        let kernel = Kernel::with_backend(backend, KernelConfig::isolated(), |_| {}, |_| {})
            .expect("with_backend kernel");

        let result = kernel
            .execute("embedder_tool")
            .await
            .expect("execution failed");
        assert_ne!(result.code, 127, "a real execution error must not look like command-not-found: {result:?}");
        assert!(!result.ok());
        assert!(
            result.err.contains("disk exploded"),
            "the real backend error must be visible, not masked: {result:?}"
        );
    }

    #[tokio::test]
    async fn disabled_external_commands_still_resolve_a_backend_tool() {
        // Regression guard for the kaijutsu shape: a read-only shell sets
        // `allow_external_commands: false` (no host subprocess exec) but
        // still registers its own backend tools — e.g. a sandboxed `curl`
        // that reads the network without touching a host binary or the VFS.
        // Refusing external commands must NOT short-circuit the
        // backend-tool lookup that runs after it. If it did, that `curl`
        // would stop resolving and fail with a message claiming it isn't
        // available — the exact wrong belief this whole fix exists to
        // prevent, just relocated one layer down. Nothing stops a future
        // "simplification" of the disabled bail into a terminal branch;
        // this test is what catches that.
        use crate::backend::testing::MockBackend;
        let (mock, calls) = MockBackend::new();
        let backend: Arc<dyn crate::backend::KernelBackend> = Arc::new(mock);
        let kernel = Kernel::with_backend(backend, KernelConfig::isolated(), |_| {}, |_| {})
            .expect("with_backend kernel");
        assert!(!kernel.allow_external_commands, "isolated() must keep external commands off for this guard to mean anything");

        let result = kernel.execute("curl").await.expect("execution failed");
        assert!(
            result.ok(),
            "a backend-registered tool must still run with external commands disabled: {result:?}"
        );
        assert_eq!(
            calls.load(std::sync::atomic::Ordering::SeqCst),
            1,
            "the backend tool must actually have been invoked, not just assumed"
        );
    }

    #[tokio::test]
    async fn test_external_command_true() {
        // Use REPL config for passthrough filesystem access
        let kernel = Kernel::new(KernelConfig::repl()).expect("failed to create kernel");

        // /bin/true should be available on any Unix system
        let result = kernel.execute("true").await.expect("execution failed");
        // This should use the builtin true, which returns 0
        assert!(result.ok(), "true should succeed: {:?}", result);
    }

    #[tokio::test]
    async fn test_external_command_basic() {
        // Use REPL config for passthrough filesystem access
        let kernel = Kernel::new(KernelConfig::repl()).expect("failed to create kernel");

        // Test with /bin/echo which is external
        // Note: kaish has a builtin echo, so this will use the builtin
        // Let's test with a command that's not a builtin
        // Actually, let's just test that PATH resolution works by checking the PATH var
        let path_var = std::env::var("PATH").unwrap_or_default();
        eprintln!("System PATH: {}", path_var);

        // Set PATH in kernel to ensure it's available
        kernel.execute(&format!(r#"PATH="{}""#, path_var)).await.expect("set PATH failed");

        // Now try an external command like /usr/bin/env
        // But env is also a builtin... let's try uname
        let result = kernel.execute("uname").await.expect("execution failed");
        eprintln!("uname result: {:?}", result);
        // uname should succeed if external commands work
        assert!(result.ok() || result.code == 127, "uname: {:?}", result);
    }

    #[tokio::test]
    async fn test_kernel_reset() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        kernel.execute("X=1").await.expect("set failed");
        assert!(kernel.get_var("X").await.is_some());

        kernel.reset().await.expect("reset failed");
        assert!(kernel.get_var("X").await.is_none());
    }

    #[tokio::test]
    async fn test_kernel_reset_preserves_pid_and_initial_vars() {
        let kernel = Kernel::new(KernelConfig::transient().with_var("HOME", Value::String("/home/probe".into())))
            .expect("failed to create kernel");

        let pid_before = kernel.execute("echo $$").await.expect("execute failed").text_out().trim().to_string();
        assert_eq!(kernel.get_var("HOME").await, Some(Value::String("/home/probe".into())));

        kernel.reset().await.expect("reset failed");

        let pid_after = kernel.execute("echo $$").await.expect("execute failed").text_out().trim().to_string();
        assert_eq!(pid_before, pid_after, "$$ must stay stable across reset(), not silently renumber");
        assert_eq!(
            kernel.get_var("HOME").await,
            Some(Value::String("/home/probe".into())),
            "frontend-seeded initial vars (HOME/PATH) must survive reset(), not silently vanish"
        );
    }

    #[tokio::test]
    async fn test_kernel_cwd() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        // Transient kernel uses sandboxed mode with cwd=$HOME
        let cwd = kernel.cwd().await;
        let home = std::env::var("HOME")
            .map(PathBuf::from)
            .unwrap_or_else(|_| PathBuf::from("/"));
        assert_eq!(cwd, home);

        kernel.set_cwd(PathBuf::from("/tmp")).await;
        assert_eq!(kernel.cwd().await, PathBuf::from("/tmp"));
    }

    #[tokio::test]
    async fn test_kernel_list_vars() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        kernel.execute("A=1").await.ok();
        kernel.execute("B=2").await.ok();

        let vars = kernel.list_vars().await;
        assert!(vars.iter().any(|(n, v)| n == "A" && *v == Value::Int(1)));
        assert!(vars.iter().any(|(n, v)| n == "B" && *v == Value::Int(2)));
    }

    #[tokio::test]
    async fn test_is_truthy() {
        assert!(!is_truthy(&Value::Null));
        assert!(!is_truthy(&Value::Bool(false)));
        assert!(is_truthy(&Value::Bool(true)));
        assert!(!is_truthy(&Value::Int(0)));
        assert!(is_truthy(&Value::Int(1)));
        assert!(!is_truthy(&Value::String("".into())));
        assert!(is_truthy(&Value::String("x".into())));
    }

    #[tokio::test]
    async fn test_jq_in_pipeline() {
        let kernel = Kernel::transient().expect("failed to create kernel");
        // kaish uses double quotes only; escape inner quotes
        let result = kernel
            .execute(r#"echo "{\"name\": \"Alice\"}" | jq ".name" -r"#)
            .await
            .expect("execution failed");
        assert!(result.ok(), "jq pipeline failed: {}", result.err);
        assert_eq!(result.text_out().trim(), "Alice");
    }

    #[tokio::test]
    async fn test_user_defined_tool() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        // Define a function
        kernel
            .execute(r#"greet() { echo "Hello, $1!" }"#)
            .await
            .expect("function definition failed");

        // Call the function
        let result = kernel
            .execute(r#"greet "World""#)
            .await
            .expect("function call failed");

        assert!(result.ok(), "greet failed: {}", result.err);
        assert_eq!(result.text_out().trim(), "Hello, World!");
    }

    #[tokio::test]
    async fn test_user_tool_positional_args() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        // Define a function with positional param
        kernel
            .execute(r#"greet() { echo "Hi $1" }"#)
            .await
            .expect("function definition failed");

        // Call with positional argument
        let result = kernel
            .execute(r#"greet "Amy""#)
            .await
            .expect("function call failed");

        assert!(result.ok(), "greet failed: {}", result.err);
        assert_eq!(result.text_out().trim(), "Hi Amy");
    }

    #[tokio::test]
    async fn test_function_shared_scope() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        // Set a variable in parent scope
        kernel
            .execute(r#"SECRET="hidden""#)
            .await
            .expect("set failed");

        // Define a function that accesses and modifies parent variable
        kernel
            .execute(r#"access_parent() {
                echo "${SECRET}"
                SECRET="modified"
            }"#)
            .await
            .expect("function definition failed");

        // Call the function - it SHOULD see SECRET (shared scope like sh)
        let result = kernel.execute("access_parent").await.expect("function call failed");

        // Function should have access to parent scope
        assert!(
            result.text_out().contains("hidden"),
            "Function should access parent scope, got: {}",
            result.text_out()
        );

        // Function should have modified the parent variable
        let secret = kernel.get_var("SECRET").await;
        assert_eq!(
            secret,
            Some(Value::String("modified".into())),
            "Function should modify parent scope"
        );
    }

    #[tokio::test]
    #[ignore = "exec replaces the test binary via CommandExt::exec, hangs libtest; cannot be run under cargo test"]
    async fn test_exec_builtin() {
        let kernel = Kernel::transient().expect("failed to create kernel");
        // argv is now a space-separated string or JSON array string
        let result = kernel
            .execute(r#"exec command="/bin/echo" argv="hello world""#)
            .await
            .expect("exec failed");

        assert!(result.ok(), "exec failed: {}", result.err);
        assert_eq!(result.text_out().trim(), "hello world");
    }

    #[tokio::test]
    async fn test_while_false_never_runs() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        // A while loop with false condition should never run
        let result = kernel
            .execute(r#"
                while false; do
                    echo "should not run"
                done
            "#)
            .await
            .expect("while false failed");

        assert!(result.ok());
        assert!(result.text_out().is_empty(), "while false should not execute body: {}", result.text_out());
    }

    #[tokio::test]
    async fn test_while_string_comparison() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        // Set a flag
        kernel.execute(r#"FLAG="go""#).await.expect("set failed");

        // Use string comparison as condition (shell-compatible [[ ]] syntax)
        // Note: Put echo last so we can check the output
        let result = kernel
            .execute(r#"
                while [[ ${FLAG} == "go" ]]; do
                    FLAG="stop"
                    echo "running"
                done
            "#)
            .await
            .expect("while with string cmp failed");

        assert!(result.ok());
        assert!(result.text_out().contains("running"), "should have run once: {}", result.text_out());

        // Verify flag was changed
        let flag = kernel.get_var("FLAG").await;
        assert_eq!(flag, Some(Value::String("stop".into())));
    }

    #[tokio::test]
    async fn test_while_numeric_comparison() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        // Test > comparison (shell-compatible [[ ]] with -gt)
        kernel.execute("N=5").await.expect("set failed");

        // Note: Put echo last so we can check the output
        let result = kernel
            .execute(r#"
                while [[ ${N} -gt 3 ]]; do
                    N=3
                    echo "N was greater"
                done
            "#)
            .await
            .expect("while with > failed");

        assert!(result.ok());
        assert!(result.text_out().contains("N was greater"), "should have run once: {}", result.text_out());
    }

    #[tokio::test]
    async fn test_break_in_while_loop() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        let result = kernel
            .execute(r#"
                I=0
                while true; do
                    I=1
                    echo "before break"
                    break
                    echo "after break"
                done
            "#)
            .await
            .expect("while with break failed");

        assert!(result.ok());
        assert!(result.text_out().contains("before break"), "should see before break: {}", result.text_out());
        assert!(!result.text_out().contains("after break"), "should not see after break: {}", result.text_out());

        // Verify we exited the loop
        let i = kernel.get_var("I").await;
        assert_eq!(i, Some(Value::Int(1)));
    }

    #[tokio::test]
    async fn test_continue_in_while_loop() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        // Test continue in a while loop where variables persist
        // We use string state transition: "start" -> "middle" -> "end"
        // continue on "middle" should skip to next iteration
        // Shell-compatible: use [[ ]] for comparisons
        let result = kernel
            .execute(r#"
                STATE="start"
                AFTER_CONTINUE="no"
                while [[ ${STATE} != "done" ]]; do
                    if [[ ${STATE} == "start" ]]; then
                        STATE="middle"
                        continue
                        AFTER_CONTINUE="yes"
                    fi
                    if [[ ${STATE} == "middle" ]]; then
                        STATE="done"
                    fi
                done
            "#)
            .await
            .expect("while with continue failed");

        assert!(result.ok());

        // STATE should be "done" (we completed the loop)
        let state = kernel.get_var("STATE").await;
        assert_eq!(state, Some(Value::String("done".into())));

        // AFTER_CONTINUE should still be "no" (continue skipped the assignment)
        let after = kernel.get_var("AFTER_CONTINUE").await;
        assert_eq!(after, Some(Value::String("no".into())));
    }

    #[tokio::test]
    async fn test_break_with_level() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        // Nested loop with break 2 to exit both loops
        // We verify by checking OUTER value:
        // - If break 2 works, OUTER stays at 1 (set before for loop)
        // - If break 2 fails, OUTER becomes 2 (set after for loop)
        let result = kernel
            .execute(r#"
                OUTER=0
                while true; do
                    OUTER=1
                    for X in "1 2"; do
                        break 2
                    done
                    OUTER=2
                done
            "#)
            .await
            .expect("nested break failed");

        assert!(result.ok());

        // OUTER should be 1 (set before for loop), not 2 (would be set after for loop)
        let outer = kernel.get_var("OUTER").await;
        assert_eq!(outer, Some(Value::Int(1)), "break 2 should have skipped OUTER=2");
    }

    #[tokio::test]
    async fn test_return_from_tool() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        // Define a function that returns early
        kernel
            .execute(r#"early_return() {
                if [[ $1 == 1 ]]; then
                    return 42
                fi
                echo "not returned"
            }"#)
            .await
            .expect("function definition failed");

        // Call with arg=1 should return with exit code 42
        // (POSIX shell behavior: return N sets exit code, doesn't output N)
        let result = kernel
            .execute("early_return 1")
            .await
            .expect("function call failed");

        // Exit code should be 42 (non-zero, so not ok())
        assert_eq!(result.code, 42);
        // Output should be empty (we returned before echo)
        assert!(result.text_out().is_empty());
    }

    #[tokio::test]
    async fn test_return_without_value() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        // Define a function that returns without a value
        kernel
            .execute(r#"early_exit() {
                if [[ $1 == "stop" ]]; then
                    return
                fi
                echo "continued"
            }"#)
            .await
            .expect("function definition failed");

        // Call with arg="stop" should return early
        let result = kernel
            .execute(r#"early_exit "stop""#)
            .await
            .expect("function call failed");

        assert!(result.ok());
        assert!(result.text_out().is_empty() || result.text_out().trim().is_empty());
    }

    #[tokio::test]
    async fn test_exit_stops_execution() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        // exit should stop further execution
        kernel
            .execute(r#"
                BEFORE="yes"
                exit 0
                AFTER="yes"
            "#)
            .await
            .expect("execution failed");

        // BEFORE should be set, AFTER should not
        let before = kernel.get_var("BEFORE").await;
        assert_eq!(before, Some(Value::String("yes".into())));

        let after = kernel.get_var("AFTER").await;
        assert!(after.is_none(), "AFTER should not be set after exit");
    }

    #[tokio::test]
    async fn test_exit_with_code() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        // exit with code should propagate the exit code
        let result = kernel
            .execute("exit 42")
            .await
            .expect("exit failed");

        assert_eq!(result.code, 42);
        assert!(result.text_out().is_empty(), "exit should not produce stdout");
    }

    #[tokio::test]
    async fn test_set_e_stops_on_failure() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        // Enable error-exit mode
        kernel.execute("set -e").await.expect("set -e failed");

        // Run a sequence where the middle command fails
        kernel
            .execute(r#"
                STEP1="done"
                false
                STEP2="done"
            "#)
            .await
            .expect("execution failed");

        // STEP1 should be set, but STEP2 should NOT be set (exit on false)
        let step1 = kernel.get_var("STEP1").await;
        assert_eq!(step1, Some(Value::String("done".into())));

        let step2 = kernel.get_var("STEP2").await;
        assert!(step2.is_none(), "STEP2 should not be set after false with set -e");
    }

    #[tokio::test]
    async fn test_set_plus_e_disables_error_exit() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        // Enable then disable error-exit mode
        kernel.execute("set -e").await.expect("set -e failed");
        kernel.execute("set +e").await.expect("set +e failed");

        // Now failure should NOT stop execution
        kernel
            .execute(r#"
                STEP1="done"
                false
                STEP2="done"
            "#)
            .await
            .expect("execution failed");

        // Both should be set since +e disables error exit
        let step1 = kernel.get_var("STEP1").await;
        assert_eq!(step1, Some(Value::String("done".into())));

        let step2 = kernel.get_var("STEP2").await;
        assert_eq!(step2, Some(Value::String("done".into())));
    }

    #[tokio::test]
    async fn test_set_euo_pipefail_is_a_working_prelude() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        // `set -euo pipefail` is muscle memory for a lot of script authors.
        // kaish implements -e and pipefail, and silently ignores the bare -u
        // (no fixed set to check it against). It used to FAIL on -o pipefail,
        // which mattered well beyond tidiness: an embedder whose exit status
        // is a policy decision — kaijutsu gates a tool call on it — read a
        // habitual first line as a deny.
        let result = kernel
            .execute("set -euo pipefail")
            .await
            .expect("set -euo pipefail failed");
        assert!(result.ok(), "the prelude must succeed, err={}", result.err);

        // Both options really took effect, not just parsed.
        let result = kernel.execute("set -o").await.expect("set -o failed");
        let text = result.text_out();
        for row in text.lines() {
            if row.contains("pipefail") {
                assert!(row.contains("on"), "pipefail should read on: {row}");
            }
        }

        // -e is live: the statement after a failure never runs.
        kernel
            .execute(r#"
                BEFORE="yes"
                false
                AFTER="yes"
            "#)
            .await
            .ok();

        let after = kernel.get_var("AFTER").await;
        assert!(after.is_none(), "-e should be enabled by the prelude");
    }

    #[tokio::test]
    async fn test_set_no_args_shows_settings() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        // Enable -e
        kernel.execute("set -e").await.expect("set -e failed");

        // Call set with no args to see settings
        let result = kernel.execute("set").await.expect("set failed");

        assert!(result.ok());
        assert!(result.text_out().contains("set -e"), "should show -e is enabled: {}", result.text_out());
    }

    #[tokio::test]
    async fn test_set_e_in_pipeline() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        kernel.execute("set -e").await.expect("set -e failed");

        // Pipeline failure should trigger exit
        kernel
            .execute(r#"
                BEFORE="yes"
                false | cat
                AFTER="yes"
            "#)
            .await
            .ok();

        let before = kernel.get_var("BEFORE").await;
        assert_eq!(before, Some(Value::String("yes".into())));

        // AFTER should not be set if pipeline failure triggers exit
        // Note: The exit code of a pipeline is the exit code of the last command
        // So `false | cat` returns 0 (cat succeeds). This is bash-compatible behavior.
        // To test pipeline failure, we need the last command to fail.
    }

    #[tokio::test]
    async fn test_set_e_with_and_chain() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        kernel.execute("set -e").await.expect("set -e failed");

        // Commands in && chain should not trigger -e on the first failure
        // because && explicitly handles the error
        kernel
            .execute(r#"
                RESULT="initial"
                false && RESULT="chained"
                RESULT="continued"
            "#)
            .await
            .ok();

        // In bash, commands in && don't trigger -e. The chain handles the failure.
        // Our implementation may differ - let's verify current behavior.
        let result = kernel.get_var("RESULT").await;
        // If we follow bash semantics, RESULT should be "continued"
        // If we trigger -e on the false, RESULT stays "initial"
        assert!(result.is_some(), "RESULT should be set");
    }

    #[tokio::test]
    async fn test_set_e_exits_in_for_loop() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        kernel.execute("set -e").await.expect("set -e failed");

        kernel
            .execute(r#"
                REACHED="no"
                for x in 1 2 3; do
                    false
                    REACHED="yes"
                done
            "#)
            .await
            .ok();

        // With set -e, false should trigger exit; REACHED should remain "no"
        let reached = kernel.get_var("REACHED").await;
        assert_eq!(reached, Some(Value::String("no".into())),
            "set -e should exit on failure in for loop body");
    }

    #[tokio::test]
    async fn test_for_loop_continues_without_set_e() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        // Without set -e, for loop should continue normally
        kernel
            .execute(r#"
                COUNT=0
                for x in 1 2 3; do
                    false
                    COUNT=$((COUNT + 1))
                done
            "#)
            .await
            .ok();

        let count = kernel.get_var("COUNT").await;
        // Arithmetic produces Int values; accept either Int or String representation
        let count_val = match &count {
            Some(Value::Int(n)) => *n,
            Some(Value::String(s)) => s.parse().unwrap_or(-1),
            _ => -1,
        };
        assert_eq!(count_val, 3,
            "without set -e, loop should complete all iterations (got {:?})", count);
    }

    // ═══════════════════════════════════════════════════════════════════════════
    // Source Tests
    // ═══════════════════════════════════════════════════════════════════════════

    #[tokio::test]
    async fn test_source_sets_variables() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        // Write a script to the VFS
        kernel
            .execute(r#"write "/test.kai" 'FOO="bar"'"#)
            .await
            .expect("write failed");

        // Source the script
        let result = kernel
            .execute(r#"source "/test.kai""#)
            .await
            .expect("source failed");

        assert!(result.ok(), "source should succeed");

        // Variable should be set in current scope
        let foo = kernel.get_var("FOO").await;
        assert_eq!(foo, Some(Value::String("bar".into())));
    }

    #[tokio::test]
    async fn test_source_with_dot_alias() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        // Write a script to the VFS
        kernel
            .execute(r#"write "/vars.kai" 'X=42'"#)
            .await
            .expect("write failed");

        // Source using . alias
        let result = kernel
            .execute(r#". "/vars.kai""#)
            .await
            .expect(". failed");

        assert!(result.ok(), ". should succeed");

        // Variable should be set in current scope
        let x = kernel.get_var("X").await;
        assert_eq!(x, Some(Value::Int(42)));
    }

    #[tokio::test]
    async fn test_source_not_found() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        // Try to source a non-existent file
        let result = kernel
            .execute(r#"source "/nonexistent.kai""#)
            .await
            .expect("source should not fail with error");

        assert!(!result.ok(), "source of non-existent file should fail");
        assert!(result.err.contains("nonexistent.kai"), "error should mention filename");
    }

    #[tokio::test]
    async fn test_source_missing_filename() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        // Call source with no arguments
        let result = kernel
            .execute("source")
            .await
            .expect("source should not fail with error");

        assert!(!result.ok(), "source without filename should fail");
        assert!(result.err.contains("missing filename"), "error should mention missing filename");
    }

    #[tokio::test]
    async fn test_source_executes_multiple_statements() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        // Write a script with multiple statements
        kernel
            .execute(r#"write "/multi.kai" 'A=1
B=2
C=3'"#)
            .await
            .expect("write failed");

        // Source it
        kernel
            .execute(r#"source "/multi.kai""#)
            .await
            .expect("source failed");

        // All variables should be set
        assert_eq!(kernel.get_var("A").await, Some(Value::Int(1)));
        assert_eq!(kernel.get_var("B").await, Some(Value::Int(2)));
        assert_eq!(kernel.get_var("C").await, Some(Value::Int(3)));
    }

    #[tokio::test]
    async fn test_source_can_define_functions() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        // Write a script that defines a function
        kernel
            .execute(r#"write "/functions.kai" 'greet() {
    echo "Hello, $1!"
}'"#)
            .await
            .expect("write failed");

        // Source it
        kernel
            .execute(r#"source "/functions.kai""#)
            .await
            .expect("source failed");

        // Use the defined function
        let result = kernel
            .execute(r#"greet "World""#)
            .await
            .expect("greet failed");

        assert!(result.ok());
        assert!(result.text_out().contains("Hello, World!"));
    }

    #[tokio::test]
    async fn test_source_inherits_error_exit() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        // Enable error exit
        kernel.execute("set -e").await.expect("set -e failed");

        // Write a script that has a failure
        kernel
            .execute(r#"write "/fail.kai" 'BEFORE="yes"
false
AFTER="yes"'"#)
            .await
            .expect("write failed");

        // Source it (should exit on false due to set -e)
        kernel
            .execute(r#"source "/fail.kai""#)
            .await
            .ok();

        // BEFORE should be set, AFTER should NOT be set due to error exit
        let before = kernel.get_var("BEFORE").await;
        assert_eq!(before, Some(Value::String("yes".into())));

        // Note: This test depends on whether error exit is checked within source
        // Currently our implementation checks per-statement in the main kernel
    }

    // ═══════════════════════════════════════════════════════════════════════════
    // set -e with && / || chains
    // ═══════════════════════════════════════════════════════════════════════════

    #[tokio::test]
    async fn test_set_e_and_chain_left_fails() {
        // set -e; false && echo hi; REACHED=1 → REACHED should be set
        let kernel = Kernel::transient().expect("failed to create kernel");
        kernel.execute("set -e").await.expect("set -e failed");

        kernel
            .execute("false && echo hi; REACHED=1")
            .await
            .expect("execution failed");

        let reached = kernel.get_var("REACHED").await;
        assert_eq!(
            reached,
            Some(Value::Int(1)),
            "set -e should not trigger on left side of &&"
        );
    }

    #[tokio::test]
    async fn test_set_e_and_chain_right_fails() {
        // set -e; true && false; REACHED=1 → REACHED should NOT be set
        let kernel = Kernel::transient().expect("failed to create kernel");
        kernel.execute("set -e").await.expect("set -e failed");

        kernel
            .execute("true && false; REACHED=1")
            .await
            .expect("execution failed");

        let reached = kernel.get_var("REACHED").await;
        assert!(
            reached.is_none(),
            "set -e should trigger when right side of && fails"
        );
    }

    #[tokio::test]
    async fn test_set_e_or_chain_recovers() {
        // set -e; false || echo recovered; REACHED=1 → REACHED should be set
        let kernel = Kernel::transient().expect("failed to create kernel");
        kernel.execute("set -e").await.expect("set -e failed");

        kernel
            .execute("false || echo recovered; REACHED=1")
            .await
            .expect("execution failed");

        let reached = kernel.get_var("REACHED").await;
        assert_eq!(
            reached,
            Some(Value::Int(1)),
            "set -e should not trigger when || recovers the failure"
        );
    }

    #[tokio::test]
    async fn test_set_e_or_chain_both_fail() {
        // set -e; false || false; REACHED=1 → REACHED should NOT be set
        let kernel = Kernel::transient().expect("failed to create kernel");
        kernel.execute("set -e").await.expect("set -e failed");

        kernel
            .execute("false || false; REACHED=1")
            .await
            .expect("execution failed");

        let reached = kernel.get_var("REACHED").await;
        assert!(
            reached.is_none(),
            "set -e should trigger when || chain ultimately fails"
        );
    }

    // ═══════════════════════════════════════════════════════════════════════════
    // Cancellation Tests
    // ═══════════════════════════════════════════════════════════════════════════

    /// Schedule a cancel after a delay, from an OS thread because `cancel()`
    /// is sync and must run while the test runtime is inside `execute()`.
    ///
    /// The delay races `execute()`: a cancel firing before `reset_cancel()` is
    /// discarded. Tests that need it to land use an `interrupt` tripwire
    /// instead, as the loop tests below do.
    fn schedule_cancel(kernel: &Arc<Kernel>, delay: std::time::Duration) {
        let k = Arc::clone(kernel);
        std::thread::spawn(move || {
            std::thread::sleep(delay);
            k.cancel();
        });
    }

    #[tokio::test]
    async fn test_cancel_interrupts_for_loop() {
        let kernel = Arc::new(Kernel::transient().expect("failed to create kernel"));

        // A `sleep` body, per #149: a bare `X=$i` has no await point for the
        // per-iteration checkpoint to land on, and at this count natural
        // completion (~100s) stays far past the bound.
        //
        // The timer this used to use raced `execute()`: `reset_cancel()`
        // replaces an already-cancelled token, so a cancel firing first was
        // dropped and the loop ran all 2000 iterations. The `interrupt` slot is
        // installed after that line, so it cannot be dropped.
        // `Kernel::cancel()` still does the cancelling.
        const ITERATIONS: u32 = 2000;
        const PER_ITERATION_SLEEP_SECS: f64 = 0.05;
        let bound = std::time::Duration::from_secs(10);

        // Counted, not latched: the checkpoint polls before the body, so a
        // cancel released on the first poll can land before the body runs at
        // all. The second poll puts one completed iteration between them.
        let polls = Arc::new(std::sync::atomic::AtomicUsize::new(0));
        let tripwire = Arc::clone(&polls);
        let opts = ExecuteOptions::new().with_interrupt(Arc::new(move || {
            tripwire.fetch_add(1, Ordering::SeqCst);
            false
        }));

        // A background OS thread, not `tokio::spawn`: the cancel has to land
        // while the current-thread test runtime is busy inside the loop.
        {
            let k = Arc::clone(&kernel);
            let tripped = Arc::clone(&polls);
            std::thread::spawn(move || {
                let deadline = std::time::Instant::now() + bound;
                while tripped.load(Ordering::SeqCst) < 2 && std::time::Instant::now() < deadline {
                    std::thread::sleep(std::time::Duration::from_millis(1));
                }
                // Cancel even if the tripwire never tripped, so a loop that
                // never started fails on an assertion below instead of just
                // running out the bound.
                k.cancel();
            });
        }

        let script = format!("for i in $(seq 1 {ITERATIONS}); do X=$i; sleep {PER_ITERATION_SLEEP_SECS}; done");

        let result = tokio::time::timeout(bound, kernel.execute_with_options(&script, opts))
            .await
            .unwrap_or_else(|_| {
                panic!(
                    "for-loop did not return within {bound:?} — cancellation support looks \
                     broken (an uncancelled loop needs ~{:.0}s to finish on its own, far \
                     longer than this bound)",
                    ITERATIONS as f64 * PER_ITERATION_SLEEP_SECS
                )
            })
            .expect("execute failed");

        assert_eq!(result.code, 130, "cancelled execution should exit with code 130");

        // How far the loop got — the half of this test that reads no clock. A
        // loop ignoring cancellation reports 2000. Parsed from text because
        // `$(seq …)` binds the loop variable as a string; the `Value::Int` arm
        // this replaces never matched, so it asserted nothing.
        const MAX_REACHED: i64 = (ITERATIONS / 10) as i64;
        let reached = match kernel.get_var("X").await {
            Some(Value::Int(n)) => n,
            Some(Value::String(s)) => s
                .parse::<i64>()
                .unwrap_or_else(|e| panic!("loop variable X should be numeric, got {s:?}: {e}")),
            other => {
                panic!("loop variable X should record the last iteration reached, got {other:?}")
            }
        };
        assert!(
            reached <= MAX_REACHED,
            "cancellation should have stopped the loop within {MAX_REACHED} of {ITERATIONS} \
             iterations, but it reached {reached} — the per-iteration checkpoint is not \
             honoring the cancellation token"
        );
    }

    #[tokio::test]
    async fn test_cancel_interrupts_while_loop() {
        let kernel = Arc::new(Kernel::transient().expect("failed to create kernel"));
        kernel.execute("COUNT=0").await.expect("init failed");

        // Same swallowed cancel as the for-loop test, but this one HUNG
        // rather than failing: `while true` has no iteration count to run out
        // and there was no bound, so a dropped cancel burned a core until CI's
        // job timeout. Fixed the same way, plus a bound — which does fire here,
        // so each iteration yields to the runtime somewhere.
        let bound = std::time::Duration::from_secs(10);

        // Counted, not latched: the checkpoint polls before the body, so a
        // cancel released on the first poll can land before the body runs at
        // all. The second poll puts one completed iteration between them.
        let polls = Arc::new(std::sync::atomic::AtomicUsize::new(0));
        let tripwire = Arc::clone(&polls);
        let opts = ExecuteOptions::new().with_interrupt(Arc::new(move || {
            tripwire.fetch_add(1, Ordering::SeqCst);
            false
        }));

        {
            let k = Arc::clone(&kernel);
            let tripped = Arc::clone(&polls);
            std::thread::spawn(move || {
                let deadline = std::time::Instant::now() + bound;
                while tripped.load(Ordering::SeqCst) < 2 && std::time::Instant::now() < deadline {
                    std::thread::sleep(std::time::Duration::from_millis(1));
                }
                k.cancel();
            });
        }

        let result = tokio::time::timeout(
            bound,
            kernel.execute_with_options("while true; do COUNT=$((COUNT + 1)); done", opts),
        )
        .await
        .unwrap_or_else(|_| {
            panic!(
                "while-loop did not return within {bound:?} — `while true` never ends on \
                 its own, so the per-iteration cancellation checkpoint is not honoring the \
                 token and this loop would have spun forever"
            )
        })
        .expect("execute failed");

        assert_eq!(result.code, 130, "cancelled execution should exit with code 130");

        // A count above zero proves a *running* loop was interrupted, and it
        // holds by construction: the cancel waits for the second poll. No upper
        // bound — how far bare arithmetic gets is a function of host speed.
        match kernel.get_var("COUNT").await {
            Some(Value::Int(n)) => assert!(n > 0, "loop should have run at least once, got {n}"),
            other => panic!("COUNT should be an integer set by the loop body, got {other:?}"),
        }
    }

    #[tokio::test]
    async fn test_reset_after_cancel() {
        // After cancellation, the next execute() should work normally
        let kernel = Kernel::transient().expect("failed to create kernel");
        kernel.cancel(); // cancel with nothing running

        let result = kernel.execute("echo hello").await.expect("execute failed");
        assert!(result.ok(), "execute after cancel should succeed");
        assert_eq!(result.text_out().trim(), "hello");
    }

    #[tokio::test]
    async fn test_cancel_interrupts_statement_sequence() {
        let kernel = Arc::new(Kernel::transient().expect("failed to create kernel"));

        // Schedule cancel after the first statement runs but before sleep finishes
        schedule_cancel(&kernel, std::time::Duration::from_millis(50));

        let result = kernel
            .execute("STEP=1; sleep 5; STEP=2; sleep 5; STEP=3")
            .await
            .expect("execute failed");

        assert_eq!(result.code, 130);

        // STEP should be 1 (set before sleep), not 2 or 3
        let step = kernel.get_var("STEP").await;
        assert_eq!(step, Some(Value::Int(1)), "cancel should stop before STEP=2");
    }

    // ═══════════════════════════════════════════════════════════════════════════
    // Case Statement Tests
    // ═══════════════════════════════════════════════════════════════════════════

    #[tokio::test]
    async fn test_case_simple_match() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        let result = kernel
            .execute(r#"
                case "hello" in
                    hello) echo "matched hello" ;;
                    world) echo "matched world" ;;
                esac
            "#)
            .await
            .expect("case failed");

        assert!(result.ok());
        assert_eq!(result.text_out().trim(), "matched hello");
    }

    #[tokio::test]
    async fn test_case_wildcard_match() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        let result = kernel
            .execute(r#"
                case "main.rs" in
                    *.py) echo "Python" ;;
                    *.rs) echo "Rust" ;;
                    *) echo "Unknown" ;;
                esac
            "#)
            .await
            .expect("case failed");

        assert!(result.ok());
        assert_eq!(result.text_out().trim(), "Rust");
    }

    #[tokio::test]
    async fn test_case_default_match() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        let result = kernel
            .execute(r#"
                case "unknown.xyz" in
                    *.py) echo "Python" ;;
                    *.rs) echo "Rust" ;;
                    *) echo "Default" ;;
                esac
            "#)
            .await
            .expect("case failed");

        assert!(result.ok());
        assert_eq!(result.text_out().trim(), "Default");
    }

    #[tokio::test]
    async fn test_case_no_match() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        // Case with no default branch and no match
        let result = kernel
            .execute(r#"
                case "nope" in
                    "yes") echo "yes" ;;
                    "no") echo "no" ;;
                esac
            "#)
            .await
            .expect("case failed");

        assert!(result.ok());
        assert!(result.text_out().is_empty(), "no match should produce empty output");
    }

    #[tokio::test]
    async fn test_case_with_variable() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        kernel.execute(r#"LANG="rust""#).await.expect("set failed");

        let result = kernel
            .execute(r#"
                case ${LANG} in
                    python) echo "snake" ;;
                    rust) echo "crab" ;;
                    go) echo "gopher" ;;
                esac
            "#)
            .await
            .expect("case failed");

        assert!(result.ok());
        assert_eq!(result.text_out().trim(), "crab");
    }

    #[tokio::test]
    async fn test_case_multiple_patterns() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        let result = kernel
            .execute(r#"
                case "yes" in
                    "y"|"yes"|"Y"|"YES") echo "affirmative" ;;
                    "n"|"no"|"N"|"NO") echo "negative" ;;
                esac
            "#)
            .await
            .expect("case failed");

        assert!(result.ok());
        assert_eq!(result.text_out().trim(), "affirmative");
    }

    #[tokio::test]
    async fn test_case_glob_question_mark() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        let result = kernel
            .execute(r#"
                case "test1" in
                    test?) echo "matched test?" ;;
                    *) echo "default" ;;
                esac
            "#)
            .await
            .expect("case failed");

        assert!(result.ok());
        assert_eq!(result.text_out().trim(), "matched test?");
    }

    #[tokio::test]
    async fn test_case_char_class() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        let result = kernel
            .execute(r#"
                case "Yes" in
                    [Yy]*) echo "yes-like" ;;
                    [Nn]*) echo "no-like" ;;
                esac
            "#)
            .await
            .expect("case failed");

        assert!(result.ok());
        assert_eq!(result.text_out().trim(), "yes-like");
    }

    // ═══════════════════════════════════════════════════════════════════════════
    // Cat Stdin Tests
    // ═══════════════════════════════════════════════════════════════════════════

    #[tokio::test]
    async fn test_cat_from_pipeline() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        let result = kernel
            .execute(r#"echo "piped text" | cat"#)
            .await
            .expect("cat pipeline failed");

        assert!(result.ok(), "cat failed: {}", result.err);
        assert_eq!(result.text_out().trim(), "piped text");
    }

    #[tokio::test]
    async fn test_cat_from_pipeline_multiline() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        let result = kernel
            .execute(r#"echo "line1\nline2" | cat -n"#)
            .await
            .expect("cat pipeline failed");

        assert!(result.ok(), "cat failed: {}", result.err);
        assert!(result.text_out().contains("1\t"), "output: {}", result.text_out());
    }

    // ═══════════════════════════════════════════════════════════════════════════
    // Heredoc Tests
    // ═══════════════════════════════════════════════════════════════════════════

    #[tokio::test]
    async fn test_heredoc_basic() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        let result = kernel
            .execute("cat <<EOF\nhello\nEOF")
            .await
            .expect("heredoc failed");

        assert!(result.ok(), "cat with heredoc failed: {}", result.err);
        assert_eq!(result.text_out().trim(), "hello");
    }

    #[tokio::test]
    async fn test_arithmetic_in_string() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        let result = kernel
            .execute(r#"echo "result: $((1 + 2))""#)
            .await
            .expect("arithmetic in string failed");

        assert!(result.ok(), "echo failed: {}", result.err);
        assert_eq!(result.text_out().trim(), "result: 3");
    }

    #[tokio::test]
    async fn test_heredoc_multiline() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        let result = kernel
            .execute("cat <<EOF\nline1\nline2\nline3\nEOF")
            .await
            .expect("heredoc failed");

        assert!(result.ok(), "cat with heredoc failed: {}", result.err);
        assert!(result.text_out().contains("line1"), "output: {}", result.text_out());
        assert!(result.text_out().contains("line2"), "output: {}", result.text_out());
        assert!(result.text_out().contains("line3"), "output: {}", result.text_out());
    }

    #[tokio::test]
    async fn test_heredoc_variable_expansion() {
        // Bug N: unquoted heredoc should expand variables
        let kernel = Kernel::transient().expect("failed to create kernel");

        kernel.execute("GREETING=hello").await.expect("set var");

        let result = kernel
            .execute("cat <<EOF\n$GREETING world\nEOF")
            .await
            .expect("heredoc expansion failed");

        assert!(result.ok(), "heredoc expansion failed: {}", result.err);
        assert_eq!(result.text_out().trim(), "hello world");
    }

    #[tokio::test]
    async fn test_heredoc_quoted_no_expansion() {
        // Bug N: quoted heredoc (<<'EOF') should NOT expand variables
        let kernel = Kernel::transient().expect("failed to create kernel");

        kernel.execute("GREETING=hello").await.expect("set var");

        let result = kernel
            .execute("cat <<'EOF'\n$GREETING world\nEOF")
            .await
            .expect("quoted heredoc failed");

        assert!(result.ok(), "quoted heredoc failed: {}", result.err);
        assert_eq!(result.text_out().trim(), "$GREETING world");
    }

    #[tokio::test]
    async fn test_heredoc_default_value_expansion() {
        // Bug N: ${VAR:-default} should expand in unquoted heredocs
        let kernel = Kernel::transient().expect("failed to create kernel");

        let result = kernel
            .execute("cat <<EOF\n${UNSET:-fallback}\nEOF")
            .await
            .expect("heredoc default expansion failed");

        assert!(result.ok(), "heredoc default expansion failed: {}", result.err);
        assert_eq!(result.text_out().trim(), "fallback");
    }

    // ═══════════════════════════════════════════════════════════════════════════
    // Read Builtin Tests
    // ═══════════════════════════════════════════════════════════════════════════

    #[tokio::test]
    async fn test_read_from_pipeline() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        // Pipe input to read
        let result = kernel
            .execute(r#"echo "Alice" | read NAME; echo "Hello, ${NAME}""#)
            .await
            .expect("read pipeline failed");

        assert!(result.ok(), "read failed: {}", result.err);
        assert!(result.text_out().contains("Hello, Alice"), "output: {}", result.text_out());
    }

    #[tokio::test]
    async fn test_read_multiple_vars_from_pipeline() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        let result = kernel
            .execute(r#"echo "John Doe 42" | read FIRST LAST AGE; echo "${FIRST} is ${AGE}""#)
            .await
            .expect("read pipeline failed");

        assert!(result.ok(), "read failed: {}", result.err);
        assert!(result.text_out().contains("John is 42"), "output: {}", result.text_out());
    }

    // ═══════════════════════════════════════════════════════════════════════════
    // Shell-Style Function Tests
    // ═══════════════════════════════════════════════════════════════════════════

    #[tokio::test]
    async fn test_posix_function_with_positional_params() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        // Define POSIX-style function
        kernel
            .execute(r#"greet() { echo "Hello, $1!" }"#)
            .await
            .expect("function definition failed");

        // Call the function
        let result = kernel
            .execute(r#"greet "Amy""#)
            .await
            .expect("function call failed");

        assert!(result.ok(), "greet failed: {}", result.err);
        assert_eq!(result.text_out().trim(), "Hello, Amy!");
    }

    #[tokio::test]
    async fn test_posix_function_multiple_args() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        // Define function using $1 and $2
        kernel
            .execute(r#"add_greeting() { echo "$1 $2!" }"#)
            .await
            .expect("function definition failed");

        // Call the function
        let result = kernel
            .execute(r#"add_greeting "Hello" "World""#)
            .await
            .expect("function call failed");

        assert!(result.ok(), "function failed: {}", result.err);
        assert_eq!(result.text_out().trim(), "Hello World!");
    }

    #[tokio::test]
    async fn test_bash_function_with_positional_params() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        // Define bash-style function (function keyword, no parens)
        kernel
            .execute(r#"function greet { echo "Hi $1" }"#)
            .await
            .expect("function definition failed");

        // Call the function
        let result = kernel
            .execute(r#"greet "Bob""#)
            .await
            .expect("function call failed");

        assert!(result.ok(), "greet failed: {}", result.err);
        assert_eq!(result.text_out().trim(), "Hi Bob");
    }

    #[tokio::test]
    async fn test_shell_function_with_all_args() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        // Define function using $@ (all args)
        kernel
            .execute(r#"echo_all() { echo "args: $@" }"#)
            .await
            .expect("function definition failed");

        // Call with multiple args
        let result = kernel
            .execute(r#"echo_all "a" "b" "c""#)
            .await
            .expect("function call failed");

        assert!(result.ok(), "function failed: {}", result.err);
        assert_eq!(result.text_out().trim(), "args: a b c");
    }

    #[tokio::test]
    async fn test_shell_function_with_arg_count() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        // Define function using $# (arg count)
        kernel
            .execute(r#"count_args() { echo "count: $#" }"#)
            .await
            .expect("function definition failed");

        // Call with three args
        let result = kernel
            .execute(r#"count_args "x" "y" "z""#)
            .await
            .expect("function call failed");

        assert!(result.ok(), "function failed: {}", result.err);
        assert_eq!(result.text_out().trim(), "count: 3");
    }

    #[tokio::test]
    async fn test_shell_function_shared_scope() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        // Set a variable in parent scope
        kernel
            .execute(r#"PARENT_VAR="visible""#)
            .await
            .expect("set failed");

        // Define shell function that reads and writes parent variable
        kernel
            .execute(r#"modify_parent() {
                echo "saw: ${PARENT_VAR}"
                PARENT_VAR="changed by function"
            }"#)
            .await
            .expect("function definition failed");

        // Call the function - it SHOULD see PARENT_VAR (bash-compatible shared scope)
        let result = kernel.execute("modify_parent").await.expect("function failed");

        assert!(
            result.text_out().contains("visible"),
            "Shell function should access parent scope, got: {}",
            result.text_out()
        );

        // Parent variable should be modified
        let var = kernel.get_var("PARENT_VAR").await;
        assert_eq!(
            var,
            Some(Value::String("changed by function".into())),
            "Shell function should modify parent scope"
        );
    }

    // ═══════════════════════════════════════════════════════════════════════════
    // Script Execution via PATH Tests
    // ═══════════════════════════════════════════════════════════════════════════

    #[tokio::test]
    async fn test_script_execution_from_path() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        // Create /bin directory and script
        kernel.execute(r#"mkdir "/bin""#).await.ok();
        kernel
            .execute(r#"write "/bin/hello.kai" 'echo "Hello from script!"'"#)
            .await
            .expect("write script failed");

        // Set PATH to /bin
        kernel.execute(r#"PATH="/bin""#).await.expect("set PATH failed");

        // Call script by name (without .kai extension)
        let result = kernel
            .execute("hello")
            .await
            .expect("script execution failed");

        assert!(result.ok(), "script failed: {}", result.err);
        assert_eq!(result.text_out().trim(), "Hello from script!");
    }

    #[tokio::test]
    async fn test_script_with_args() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        // Create script that uses positional params
        kernel.execute(r#"mkdir "/bin""#).await.ok();
        kernel
            .execute(r#"write "/bin/greet.kai" 'echo "Hello, $1!"'"#)
            .await
            .expect("write script failed");

        // Set PATH
        kernel.execute(r#"PATH="/bin""#).await.expect("set PATH failed");

        // Call script with arg
        let result = kernel
            .execute(r#"greet "World""#)
            .await
            .expect("script execution failed");

        assert!(result.ok(), "script failed: {}", result.err);
        assert_eq!(result.text_out().trim(), "Hello, World!");
    }

    #[tokio::test]
    async fn test_script_not_found() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        // Set empty PATH
        kernel.execute(r#"PATH="/nonexistent""#).await.expect("set PATH failed");

        // Call non-existent script
        let result = kernel
            .execute("noscript")
            .await
            .expect("execution failed");

        assert!(!result.ok(), "should fail with command not found");
        assert_eq!(result.code, 127);
        assert!(result.err.contains("command not found"));
    }

    #[tokio::test]
    async fn test_script_path_search_order() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        // Create two directories with same-named script
        // Note: using "myscript" not "test" to avoid conflict with test builtin
        kernel.execute(r#"mkdir "/first""#).await.ok();
        kernel.execute(r#"mkdir "/second""#).await.ok();
        kernel
            .execute(r#"write "/first/myscript.kai" 'echo "from first"'"#)
            .await
            .expect("write failed");
        kernel
            .execute(r#"write "/second/myscript.kai" 'echo "from second"'"#)
            .await
            .expect("write failed");

        // Set PATH with first before second
        kernel.execute(r#"PATH="/first:/second""#).await.expect("set PATH failed");

        // Should find first one
        let result = kernel
            .execute("myscript")
            .await
            .expect("script execution failed");

        assert!(result.ok(), "script failed: {}", result.err);
        assert_eq!(result.text_out().trim(), "from first");
    }

    // ═══════════════════════════════════════════════════════════════════════════
    // Special Variable Tests ($?, $$, unset vars)
    // ═══════════════════════════════════════════════════════════════════════════

    #[tokio::test]
    async fn test_last_exit_code_success() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        // true exits with 0
        let result = kernel.execute("true; echo $?").await.expect("execution failed");
        assert!(result.text_out().contains("0"), "expected 0, got: {}", result.text_out());
    }

    #[tokio::test]
    async fn test_last_exit_code_failure() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        // false exits with 1
        let result = kernel.execute("false; echo $?").await.expect("execution failed");
        assert!(result.text_out().contains("1"), "expected 1, got: {}", result.text_out());
    }

    #[tokio::test]
    async fn test_current_pid() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        let result = kernel.execute("echo $$").await.expect("execution failed");
        // PID should be a positive number
        let pid: u32 = result.text_out().trim().parse().expect("PID should be a number");
        assert!(pid > 0, "PID should be positive");
    }

    #[tokio::test]
    async fn test_unset_variable_expands_to_empty() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        // Unset variable in interpolation should be empty
        let result = kernel.execute(r#"echo "prefix:${UNSET_VAR}:suffix""#).await.expect("execution failed");
        assert_eq!(result.text_out().trim(), "prefix::suffix");
    }

    #[tokio::test]
    async fn test_eq_ne_operators() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        // Test -eq operator
        let result = kernel.execute(r#"if [[ 5 -eq 5 ]]; then echo "eq works"; fi"#).await.expect("execution failed");
        assert_eq!(result.text_out().trim(), "eq works");

        // Test -ne operator
        let result = kernel.execute(r#"if [[ 5 -ne 3 ]]; then echo "ne works"; fi"#).await.expect("execution failed");
        assert_eq!(result.text_out().trim(), "ne works");

        // Test -eq with different values
        let result = kernel.execute(r#"if [[ 5 -eq 3 ]]; then echo "wrong"; else echo "correct"; fi"#).await.expect("execution failed");
        assert_eq!(result.text_out().trim(), "correct");
    }

    #[tokio::test]
    async fn test_escaped_dollar_in_string() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        // \$ should produce literal $
        let result = kernel.execute(r#"echo "\$100""#).await.expect("execution failed");
        assert_eq!(result.text_out().trim(), "$100");
    }

    #[tokio::test]
    async fn test_special_vars_in_interpolation() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        // Test $? in string interpolation
        let result = kernel.execute(r#"true; echo "exit: $?""#).await.expect("execution failed");
        assert_eq!(result.text_out().trim(), "exit: 0");

        // Test $$ in string interpolation
        let result = kernel.execute(r#"echo "pid: $$""#).await.expect("execution failed");
        assert!(result.text_out().starts_with("pid: "), "unexpected output: {}", result.text_out());
        let text = result.text_out();
        let pid_part = text.trim().strip_prefix("pid: ").unwrap();
        let _pid: u32 = pid_part.parse().expect("PID in string should be a number");
    }

    // ═══════════════════════════════════════════════════════════════════════════
    // Command Substitution Tests
    // ═══════════════════════════════════════════════════════════════════════════

    #[tokio::test]
    async fn test_command_subst_assignment() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        // Command substitution in assignment
        let result = kernel.execute(r#"X=$(echo hello); echo "$X""#).await.expect("execution failed");
        assert_eq!(result.text_out().trim(), "hello");
    }

    #[tokio::test]
    async fn test_command_subst_with_args() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        // Command substitution with string argument
        let result = kernel.execute(r#"X=$(echo "a b c"); echo "$X""#).await.expect("execution failed");
        assert_eq!(result.text_out().trim(), "a b c");
    }

    #[tokio::test]
    async fn test_command_subst_nested_vars() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        // Variables inside command substitution
        let result = kernel.execute(r#"Y=world; X=$(echo "hello $Y"); echo "$X""#).await.expect("execution failed");
        assert_eq!(result.text_out().trim(), "hello world");
    }

    #[tokio::test]
    async fn test_background_job_basic() {
        use std::time::Duration;

        let kernel = Kernel::new(KernelConfig::isolated()).expect("failed to create kernel");

        // Run a simple background command, redirecting its output to a
        // memory-backed file. `/v/jobs/{id}/stdout` would work too (and is
        // live); the redirect is what this test asserts on.
        let result = kernel.execute("echo hello > /tmp/basic_out.txt &").await.expect("execution failed");
        assert!(result.ok(), "background command should succeed: {}", result.err);
        assert!(result.err.contains("[1]"), "announcement rides stderr: {:?}", result.err);

        // Give the job time to complete
        tokio::time::sleep(Duration::from_millis(100)).await;

        // Check job status
        let status = kernel.execute("cat /v/jobs/1/status").await.expect("status check failed");
        assert!(status.ok(), "status should succeed: {}", status.err);
        assert!(
            status.text_out().contains("done:") || status.text_out().contains("running"),
            "should have valid status: {}",
            status.text_out()
        );

        // Check the redirected output
        let stdout = kernel.execute("cat /tmp/basic_out.txt").await.expect("output check failed");
        assert!(stdout.ok());
        assert!(stdout.text_out().contains("hello"));
    }

    #[tokio::test]
    async fn test_heredoc_piped_to_command() {
        // Bug 4: heredoc content should pipe through to next command
        let kernel = Kernel::transient().expect("kernel");
        let result = kernel.execute("cat <<EOF | cat\nhello world\nEOF").await.expect("exec");
        assert!(result.ok(), "heredoc | cat failed: {}", result.err);
        assert_eq!(result.text_out().trim(), "hello world");
    }

    /// A transient kernel paired with a real, auto-cleaning tempdir. The
    /// transient (Sandboxed) kernel mounts `/tmp` as a real `LocalFs`, so glob
    /// tests need actual files on disk. Hold the returned `TempDir` for the
    /// test's lifetime: it removes the directory tree on drop — including on
    /// panic — so no test scratch leaks into `/tmp` (the project's tmp-builder
    /// convention; never hardcode `/tmp/...` paths). Returns the absolute path
    /// as a string for interpolation into scripts.
    fn transient_with_tempdir() -> (Kernel, tempfile::TempDir, String) {
        let kernel = Kernel::transient().expect("kernel");
        let tmp = tempfile::tempdir().expect("tempdir");
        let dir = tmp.path().display().to_string();
        (kernel, tmp, dir)
    }

    #[tokio::test]
    async fn test_for_loop_glob_iterates() {
        // Bug 1: for F in $(glob ...) should iterate per file, not once
        let (kernel, _tmp, dir) = transient_with_tempdir();
        kernel.execute(&format!("echo a > {dir}/a.txt")).await.unwrap();
        kernel.execute(&format!("echo b > {dir}/b.txt")).await.unwrap();
        let result = kernel.execute(&format!(r#"
            N=0
            for F in $(glob "{dir}/*.txt"); do
                N=$((N + 1))
            done
            echo $N
        "#)).await.unwrap();
        assert!(result.ok(), "for glob failed: {}", result.err);
        assert_eq!(result.text_out().trim(), "2", "Should iterate 2 files, got: {}", result.text_out());
    }

    #[tokio::test]
    async fn test_bare_glob_expansion_echo() {
        let (kernel, _tmp, dir) = transient_with_tempdir();
        kernel.execute(&format!("echo a > {dir}/a.txt")).await.unwrap();
        kernel.execute(&format!("echo b > {dir}/b.txt")).await.unwrap();
        kernel.execute(&format!("echo c > {dir}/c.rs")).await.unwrap();
        kernel.execute(&format!("cd {dir}")).await.unwrap();
        let result = kernel.execute("echo *.txt").await.unwrap();
        assert!(result.ok(), "echo *.txt failed: {}", result.err);
        let out = result.text_out();
        let out = out.trim();
        // Should contain both .txt files (order may vary)
        assert!(out.contains("a.txt"), "missing a.txt in: {}", out);
        assert!(out.contains("b.txt"), "missing b.txt in: {}", out);
        assert!(!out.contains("c.rs"), "should not contain c.rs in: {}", out);
    }

    #[tokio::test]
    async fn test_bare_glob_no_matches_errors() {
        let (kernel, _tmp, dir) = transient_with_tempdir();
        kernel.execute(&format!("cd {dir}")).await.unwrap();
        let result = kernel.execute("echo *.nonexistent").await;
        match &result {
            Ok(exec) => {
                // No-match glob should produce a non-zero exit code
                assert!(!exec.ok(), "expected failure, got success: out={}, err={}", exec.text_out(), exec.err);
                assert!(exec.err.contains("no matches"), "error should say no matches: {}", exec.err);
            }
            Err(e) => {
                assert!(e.to_string().contains("no matches"), "error should say no matches: {}", e);
            }
        }
    }

    #[tokio::test]
    async fn test_bare_glob_disabled_with_set() {
        let (kernel, _tmp, dir) = transient_with_tempdir();
        kernel.execute(&format!("echo a > {dir}/a.txt")).await.unwrap();
        kernel.execute(&format!("cd {dir}")).await.unwrap();
        // Disable glob expansion
        kernel.execute("set +o glob").await.unwrap();
        let result = kernel.execute("echo *.txt").await.unwrap();
        // With glob disabled, *.txt should be passed as literal string
        assert!(result.ok(), "echo should succeed: {}", result.err);
        assert_eq!(result.text_out().trim(), "*.txt", "should be literal: {}", result.text_out());
    }

    #[tokio::test]
    async fn test_bare_glob_quoted_not_expanded() {
        let (kernel, _tmp, dir) = transient_with_tempdir();
        kernel.execute(&format!("echo a > {dir}/a.txt")).await.unwrap();
        kernel.execute(&format!("cd {dir}")).await.unwrap();
        // Quoted globs should NOT expand
        let result = kernel.execute("echo \"*.txt\"").await.unwrap();
        assert!(result.ok(), "echo should succeed: {}", result.err);
        assert_eq!(result.text_out().trim(), "*.txt", "quoted should be literal: {}", result.text_out());
    }

    #[tokio::test]
    async fn test_bare_glob_for_loop() {
        let (kernel, _tmp, dir) = transient_with_tempdir();
        kernel.execute(&format!("echo a > {dir}/a.txt")).await.unwrap();
        kernel.execute(&format!("echo b > {dir}/b.txt")).await.unwrap();
        kernel.execute(&format!("cd {dir}")).await.unwrap();
        let result = kernel.execute(r#"
            N=0
            for f in *.txt; do
                N=$((N + 1))
            done
            echo $N
        "#).await.unwrap();
        assert!(result.ok(), "for loop failed: {}", result.err);
        assert_eq!(result.text_out().trim(), "2", "should iterate 2 files: {}", result.text_out());
    }

    #[tokio::test]
    async fn test_glob_in_assignment_is_literal() {
        let kernel = Kernel::transient().expect("kernel");
        let result = kernel.execute("X=*.txt; echo $X").await.unwrap();
        assert!(result.ok());
        assert_eq!(result.text_out().trim(), "*.txt", "glob in assignment should be literal");
    }

    #[tokio::test]
    async fn test_glob_in_test_expr_is_literal() {
        let kernel = Kernel::transient().expect("kernel");
        let result = kernel.execute(r#"
            if [[ *.txt == "*.txt" ]]; then
                echo "match"
            else
                echo "no"
            fi
        "#).await.unwrap();
        assert!(result.ok());
        assert_eq!(result.text_out().trim(), "match", "glob in test expr should be literal");
    }

    #[tokio::test]
    async fn test_command_subst_echo_not_iterable() {
        // Regression guard: $(echo "a b c") must remain a single string
        let kernel = Kernel::transient().expect("kernel");
        let result = kernel.execute(r#"
            N=0
            for X in $(echo "a b c"); do N=$((N + 1)); done
            echo $N
        "#).await.unwrap();
        assert!(result.ok());
        assert_eq!(result.text_out().trim(), "1", "echo should be one item: {}", result.text_out());
    }

    // -- accumulate_result / newline tests --

    #[test]
    fn test_accumulate_preserves_own_newlines() {
        // Outputs concatenate verbatim — a command's own trailing newline is
        // kept, none is invented.
        let mut acc = ExecResult::success("line1\n");
        let new = ExecResult::success("line2\n");
        accumulate_result(&mut acc, &new);
        assert_eq!(&*acc.text_out(), "line1\nline2\n");
        assert!(!acc.text_out().contains("\n\n"), "should not have double newlines: {:?}", acc.text_out());
    }

    #[test]
    fn test_accumulate_inserts_no_separator() {
        // No artificial separator: `printf a; printf b` style concatenates to
        // `ab`, matching bash (regression for the 2026-06-09 finding).
        let mut acc = ExecResult::success("line1");
        let new = ExecResult::success("line2");
        accumulate_result(&mut acc, &new);
        assert_eq!(&*acc.text_out(), "line1line2");
    }

    #[test]
    fn test_accumulate_empty_into_nonempty() {
        let mut acc = ExecResult::success("");
        let new = ExecResult::success("hello\n");
        accumulate_result(&mut acc, &new);
        assert_eq!(&*acc.text_out(), "hello\n");
    }

    #[test]
    fn test_accumulate_nonempty_into_empty() {
        let mut acc = ExecResult::success("hello\n");
        let new = ExecResult::success("");
        accumulate_result(&mut acc, &new);
        assert_eq!(&*acc.text_out(), "hello\n");
    }

    #[test]
    fn test_accumulate_stderr_no_double_newlines() {
        let mut acc = ExecResult::failure(1, "err1\n");
        let new = ExecResult::failure(1, "err2\n");
        accumulate_result(&mut acc, &new);
        assert!(!acc.err.contains("\n\n"), "stderr should not have double newlines: {:?}", acc.err);
    }

    #[tokio::test]
    async fn test_multiple_echo_no_blank_lines() {
        let kernel = Kernel::transient().expect("kernel");
        let result = kernel
            .execute("echo one\necho two\necho three")
            .await
            .expect("execution failed");
        assert!(result.ok());
        assert_eq!(&*result.text_out(), "one\ntwo\nthree\n");
    }

    #[tokio::test]
    async fn test_for_loop_no_blank_lines() {
        let kernel = Kernel::transient().expect("kernel");
        let result = kernel
            .execute(r#"for X in a b c; do echo "item: ${X}"; done"#)
            .await
            .expect("execution failed");
        assert!(result.ok());
        assert_eq!(&*result.text_out(), "item: a\nitem: b\nitem: c\n");
    }

    #[tokio::test]
    async fn test_for_command_subst_no_blank_lines() {
        let kernel = Kernel::transient().expect("kernel");
        let result = kernel
            .execute(r#"for N in $(seq 1 3); do echo "n=${N}"; done"#)
            .await
            .expect("execution failed");
        assert!(result.ok());
        assert_eq!(&*result.text_out(), "n=1\nn=2\nn=3\n");
    }

    // ------------------------------------------------------------------
    // build_args_async: multi-consume flags (jq --arg NAME VALUE pattern)
    // ------------------------------------------------------------------

    /// Helper: a throwaway schema with one `--pair` param declared as
    /// consuming two positionals per occurrence. Modelled after what
    /// jq_native will declare for `--arg` / `--argjson`.
    fn multi_consume_schema() -> crate::tools::ToolSchema {
        use crate::tools::{ParamSchema, ToolSchema};
        ToolSchema::new("test", "multi-consume smoke")
            .param(
                ParamSchema::optional("pair", "array", Value::Null, "name+value pair")
                    .consumes(2),
            )
    }

    fn pos(s: &str) -> Arg {
        Arg::Positional(Expr::Literal(Value::String(s.to_string())))
    }

    #[tokio::test]
    async fn build_args_multi_consume_single_occurrence() {
        let kernel = Kernel::transient().expect("kernel");
        let schema = multi_consume_schema();
        // Simulates:  test --pair NAME VALUE filter
        let args = vec![
            Arg::LongFlag("pair".into()),
            pos("NAME"),
            pos("VALUE"),
            pos("filter"),
        ];
        let built = kernel
            .build_args_async(&args, Some(&schema))
            .await
            .expect("build_args should succeed");

        // `--pair` + its two positionals are consumed into named["pair"],
        // which becomes an outer array of one inner 2-element array.
        let pair = built.named.get("pair").expect("named[pair] missing");
        match pair {
            Value::Json(serde_json::Value::Array(occurrences)) => {
                assert_eq!(occurrences.len(), 1, "expected one occurrence");
                match &occurrences[0] {
                    serde_json::Value::Array(values) => {
                        assert_eq!(values.len(), 2, "pair must have 2 values");
                        assert_eq!(values[0], serde_json::Value::String("NAME".into()));
                        assert_eq!(values[1], serde_json::Value::String("VALUE".into()));
                    }
                    other => panic!("expected inner array, got {other:?}"),
                }
            }
            other => panic!("expected Json(Array(...)) for named[pair], got {other:?}"),
        }

        // The un-consumed positional ("filter") remains in `positional`.
        assert_eq!(built.positional.len(), 1);
        assert_eq!(built.positional[0], Value::String("filter".into()));
    }
    #[tokio::test]
    async fn build_args_multi_consume_two_occurrences_accumulate() {
        let kernel = Kernel::transient().expect("kernel");
        let schema = multi_consume_schema();
        // Simulates:  test --pair A 1 --pair B 2 filter
        let args = vec![
            Arg::LongFlag("pair".into()),
            pos("A"),
            pos("1"),
            Arg::LongFlag("pair".into()),
            pos("B"),
            pos("2"),
            pos("filter"),
        ];
        let built = kernel
            .build_args_async(&args, Some(&schema))
            .await
            .expect("build_args should succeed");

        let pair = built.named.get("pair").expect("named[pair] missing");
        match pair {
            Value::Json(serde_json::Value::Array(occurrences)) => {
                assert_eq!(occurrences.len(), 2, "expected two occurrences");
                // Preserved in invocation order.
                match &occurrences[0] {
                    serde_json::Value::Array(values) => {
                        assert_eq!(values[0], serde_json::Value::String("A".into()));
                        assert_eq!(values[1], serde_json::Value::String("1".into()));
                    }
                    other => panic!("expected inner array, got {other:?}"),
                }
                match &occurrences[1] {
                    serde_json::Value::Array(values) => {
                        assert_eq!(values[0], serde_json::Value::String("B".into()));
                        assert_eq!(values[1], serde_json::Value::String("2".into()));
                    }
                    other => panic!("expected inner array, got {other:?}"),
                }
            }
            other => panic!("expected Json(Array(...)), got {other:?}"),
        }
    }

    // ── undeclared space-form flag under map_positionals (kj --type val) ──
    //
    // A backend/MCP tool whose schema does NOT declare a flag must not let
    // `--flag value` (space form) silently divorce the value: that was a
    // privilege-escalation-by-typo against kaijutsu.
    // kaish fails loud rather than guessing.

    use crate::tools::{ParamSchema, ToolSchema};

    /// Backend-style schema (map_positionals) declaring only a `name`
    /// positional — `--type` is intentionally undeclared.
    fn kj_like_schema() -> ToolSchema {
        ToolSchema::new("kj", "incomplete backend schema")
            .param(ParamSchema::optional("name", "string", Value::Null, "context name"))
            .with_positional_mapping()
    }

    #[tokio::test]
    async fn build_args_undeclared_space_flag_errors_under_map_positionals() {
        let kernel = Kernel::transient().expect("kernel");
        let schema = kj_like_schema();
        // kj context create exp --type explorer
        let args = vec![
            pos("context"),
            pos("create"),
            pos("exp"),
            Arg::LongFlag("type".into()),
            pos("explorer"),
        ];
        let err = kernel
            .build_args_async(&args, Some(&schema))
            .await
            .expect_err("undeclared --type with a space value must fail loud");
        let msg = err.to_string();
        assert!(msg.contains("--type"), "message should name the flag: {msg}");
        assert!(msg.contains("--type=explorer"), "message should suggest the = form: {msg}");
        assert!(msg.contains("kj"), "message should name the tool: {msg}");
    }

    #[tokio::test]
    async fn build_args_declared_space_flag_still_binds() {
        let kernel = Kernel::transient().expect("kernel");
        // Same tool, but now the schema DECLARES --type as a string param.
        let schema = ToolSchema::new("kj", "complete schema")
            .param(ParamSchema::optional("name", "string", Value::Null, "context name"))
            .param(ParamSchema::optional("type", "string", Value::Null, "role type"))
            .with_positional_mapping();
        let args = vec![
            pos("exp"),
            Arg::LongFlag("type".into()),
            pos("explorer"),
        ];
        let built = kernel.build_args_async(&args, Some(&schema)).await.unwrap();
        assert_eq!(built.named.get("type"), Some(&Value::String("explorer".into())));
    }

    #[tokio::test]
    async fn build_args_equals_form_binds_for_undeclared_flag() {
        let kernel = Kernel::transient().expect("kernel");
        let schema = kj_like_schema();
        // The unambiguous `=` form must keep working even when undeclared.
        let args = vec![
            pos("exp"),
            Arg::Named { key: "type".into(), value: Expr::Literal(Value::String("explorer".into())) },
        ];
        let built = kernel.build_args_async(&args, Some(&schema)).await.unwrap();
        assert_eq!(built.named.get("type"), Some(&Value::String("explorer".into())));
    }

    #[tokio::test]
    async fn build_args_undeclared_bool_flag_at_end_is_ok() {
        let kernel = Kernel::transient().expect("kernel");
        let schema = kj_like_schema();
        // No positional follows --force → unambiguously a bare flag.
        let args = vec![pos("exp"), Arg::LongFlag("force".into())];
        let built = kernel.build_args_async(&args, Some(&schema)).await.unwrap();
        assert!(built.flags.contains("force"));
    }

    #[tokio::test]
    async fn build_args_undeclared_flag_before_another_flag_is_ok() {
        let kernel = Kernel::transient().expect("kernel");
        let schema = kj_like_schema();
        // --verbose is followed by a flag, not a positional → not ambiguous.
        let args = vec![
            Arg::LongFlag("verbose".into()),
            Arg::Named { key: "name".into(), value: Expr::Literal(Value::String("x".into())) },
        ];
        let built = kernel.build_args_async(&args, Some(&schema)).await.unwrap();
        assert!(built.flags.contains("verbose"));
    }

    #[tokio::test]
    async fn build_args_undeclared_space_flag_ok_for_builtin_schema() {
        let kernel = Kernel::transient().expect("kernel");
        // Builtins set map_positionals=false; the ambiguity guard must not
        // fire there (clap validates their flags separately).
        let schema = ToolSchema::new("frobnicate", "builtin-style")
            .param(ParamSchema::optional("name", "string", Value::Null, "name"));
        let args = vec![Arg::LongFlag("frob".into()), pos("value")];
        let built = kernel.build_args_async(&args, Some(&schema)).await.unwrap();
        assert!(built.flags.contains("frob"));
    }

    // ── GH #189 item 4: the short-flag half of the same ambiguity guard ──
    //
    // The long-flag guard above was closed by GH #188; an undeclared SHORT
    // flag under a map_positionals schema was still silently defaulting to
    // bare bool, divorcing a space-form value (`kj -t explorer`) exactly the
    // same way the long-flag case used to.

    #[tokio::test]
    async fn build_args_undeclared_short_space_flag_errors_under_map_positionals() {
        let kernel = Kernel::transient().expect("kernel");
        let schema = kj_like_schema();
        // kj exp -t explorer
        let args = vec![pos("exp"), Arg::ShortFlag("t".into()), pos("explorer")];
        let err = kernel
            .build_args_async(&args, Some(&schema))
            .await
            .expect_err("undeclared -t with a space value must fail loud");
        let msg = err.to_string();
        assert!(msg.contains("-t"), "message should name the flag: {msg}");
        assert!(msg.contains("kj"), "message should name the tool: {msg}");
    }

    #[tokio::test]
    async fn build_args_undeclared_short_space_flag_ok_for_builtin_schema() {
        let kernel = Kernel::transient().expect("kernel");
        // Builtins set map_positionals=false; the ambiguity guard must not
        // fire there.
        let schema = ToolSchema::new("frobnicate", "builtin-style")
            .param(ParamSchema::optional("name", "string", Value::Null, "name"));
        let args = vec![Arg::ShortFlag("t".into()), pos("value")];
        let built = kernel.build_args_async(&args, Some(&schema)).await.unwrap();
        assert!(built.flags.contains("t"));
    }

    // ── subcommand-aware binding (select_leaf wired into build_args_async) ──
    //
    // A tool exposing a subcommand tree binds flags against the *routed leaf's*
    // params, not the root's. The subcommand-path positionals stay positional
    // (kj re-parses them with its own clap), and a value flag declared only on
    // a deep leaf still binds in space form.

    /// kj → context (alias ctx) → create{--type value, --force bool}.
    /// map_positionals defaults false on every node (builtin/kj style).
    fn kj_tree_schema() -> ToolSchema {
        ToolSchema::new("kj", "subcommand tool").subcommand(
            ToolSchema::new("context", "context ops")
                .with_command_aliases(["ctx"])
                .subcommand(
                    ToolSchema::new("create", "create context")
                        .param(ParamSchema::new("type", "string").with_aliases(["t"]))
                        .param(ParamSchema::new("force", "bool")),
                ),
        )
    }

    #[tokio::test]
    async fn build_args_binds_deep_leaf_value_flag_space_form() {
        let kernel = Kernel::transient().expect("kernel");
        let schema = kj_tree_schema();
        // kj context create --type explorer
        let args = vec![
            pos("context"),
            pos("create"),
            Arg::LongFlag("type".into()),
            pos("explorer"),
        ];
        let built = kernel.build_args_async(&args, Some(&schema)).await.expect("build_args");
        // --type (declared only on the create leaf) binds in space form.
        assert_eq!(built.named.get("type"), Some(&Value::String("explorer".into())));
        // The subcommand path survives as positionals for kj to re-parse.
        let positionals: Vec<&str> = built
            .positional
            .iter()
            .filter_map(|v| if let Value::String(s) = v { Some(s.as_str()) } else { None })
            .collect();
        assert_eq!(positionals, vec!["context", "create"]);
    }

    #[tokio::test]
    async fn build_args_leaf_bool_flag_does_not_swallow_positional() {
        let kernel = Kernel::transient().expect("kernel");
        let schema = kj_tree_schema();
        // kj context create --force somearg  → --force is a leaf bool flag,
        // it must NOT consume `somearg`.
        let args = vec![
            pos("context"),
            pos("create"),
            Arg::LongFlag("force".into()),
            pos("somearg"),
        ];
        let built = kernel.build_args_async(&args, Some(&schema)).await.expect("build_args");
        assert!(built.flags.contains("force"), "force should be a bare flag");
        let positionals: Vec<&str> = built
            .positional
            .iter()
            .filter_map(|v| if let Value::String(s) = v { Some(s.as_str()) } else { None })
            .collect();
        assert_eq!(positionals, vec!["context", "create", "somearg"]);
    }

    #[tokio::test]
    async fn build_args_alias_routed_leaf_binds_value_flag() {
        let kernel = Kernel::transient().expect("kernel");
        let schema = kj_tree_schema();
        // kj ctx create -t explorer  → command alias + short flag alias.
        let args = vec![
            pos("ctx"),
            pos("create"),
            Arg::ShortFlag("t".into()),
            pos("explorer"),
        ];
        let built = kernel.build_args_async(&args, Some(&schema)).await.expect("build_args");
        assert_eq!(built.named.get("type"), Some(&Value::String("explorer".into())));
    }

    #[tokio::test]
    async fn build_args_computed_subcommand_selector_fails_loud() {
        let kernel = Kernel::transient().expect("kernel");
        let schema = kj_tree_schema();
        // kj $(echo context) — routing can't see the value; fail loud.
        let args = vec![Arg::Positional(Expr::CommandSubst(vec![Stmt::Command(
            crate::ast::Command { name: "echo".into(), args: vec![], redirects: vec![] },
        )]))];
        let err = kernel
            .build_args_async(&args, Some(&schema))
            .await
            .expect_err("computed subcommand selector must error");
        assert!(
            err.to_string().contains("subcommand name is required"),
            "got: {err}"
        );
    }

    // ── finalize_output: --json rendering vs. owns_output opt-out ───────────

    #[test]
    fn finalize_output_renders_when_kernel_owns_it() {
        use crate::interpreter::{OutputData, OutputFormat};
        let r = ExecResult::with_output(OutputData::text("RAW"));
        let out = finalize_output(r, Some(OutputFormat::Json), false);
        // Kernel renders the typed OutputData → JSON; text is no longer bare.
        assert_ne!(out.text_out(), "RAW", "kernel should reformat to JSON");
    }

    #[test]
    fn finalize_output_skips_when_tool_owns_output_and_succeeds() {
        use crate::interpreter::{OutputData, OutputFormat};
        let r = ExecResult::with_output(OutputData::text("RAW"));
        let out = finalize_output(r, Some(OutputFormat::Json), true);
        // owns_output + success: the tool already rendered; kernel leaves bytes
        // untouched.
        assert_eq!(out.text_out(), "RAW", "owned output must be left as-is");
    }

    #[test]
    fn finalize_output_renders_owns_output_failure() {
        // scatter/gather (the only owns_output tools) never render their own
        // JSONL/array on a FAILURE path — their error returns are plain-text
        // `ExecResult::failure(code, msg)`, identical in shape to any other
        // builtin's. owns_output means "the tool already rendered its own
        // SUCCESS output", not "never touch this tool's bytes" — a failure
        // must still get the uniform --json error envelope like every other
        // builtin (kaibo review finding on merged PR #215; confirmed
        // pre-existing for scatter/gather's whole error-path class, including
        // the clap-parse-failure path).
        use crate::interpreter::OutputFormat;
        let r = ExecResult::failure(2, "scatter: unexpected argument '--nope'");
        let out = finalize_output(r, Some(OutputFormat::Json), true);
        let parsed: serde_json::Value =
            serde_json::from_str(&out.text_out()).expect("--json must always parse as JSON");
        assert_eq!(parsed["error"], "scatter: unexpected argument '--nope'");
        assert_eq!(parsed["code"], 2);
    }

    #[test]
    fn finalize_output_no_format_is_noop() {
        use crate::interpreter::OutputData;
        let r = ExecResult::with_output(OutputData::text("RAW"));
        let out = finalize_output(r, None, false);
        assert_eq!(out.text_out(), "RAW");
    }

    // ── initial_vars + execute_with_vars + hermetic env ───────────────────

    #[tokio::test]
    async fn test_initial_vars_set_and_exported() {
        let config = KernelConfig::transient()
            .with_var("INIT_FOO", Value::String("bar".into()));
        let kernel = Kernel::new(config).expect("failed to create kernel");

        assert_eq!(
            kernel.get_var("INIT_FOO").await,
            Some(Value::String("bar".into()))
        );
        assert!(
            kernel.scope.read().await.is_exported("INIT_FOO"),
            "initial_vars entries must be marked exported"
        );
    }

    #[tokio::test]
    async fn test_execute_with_vars_overlay_visible() {
        let kernel = Kernel::transient().expect("failed to create kernel");
        let mut overlay = HashMap::new();
        overlay.insert("OVERLAY_X".to_string(), Value::String("yes".into()));

        let result = kernel
            .execute_with_options(r#"echo "${OVERLAY_X}""#, ExecuteOptions::new().with_vars(overlay))
            .await
            .expect("execute failed");

        assert!(result.ok());
        assert_eq!(result.text_out().trim(), "yes");
    }

    #[tokio::test]
    async fn test_execute_with_vars_overlay_cleanup() {
        let kernel = Kernel::transient().expect("failed to create kernel");
        let mut overlay = HashMap::new();
        overlay.insert("EPHEMERAL".to_string(), Value::String("transient".into()));

        kernel
            .execute_with_options("echo ignored", ExecuteOptions::new().with_vars(overlay))
            .await
            .expect("execute failed");

        assert_eq!(kernel.get_var("EPHEMERAL").await, None);
        assert!(
            !kernel.scope.read().await.is_exported("EPHEMERAL"),
            "overlay-only export must be cleared on return"
        );
    }

    #[tokio::test]
    async fn test_execute_with_vars_does_not_clobber_existing_export() {
        let kernel = Kernel::transient().expect("failed to create kernel");
        kernel
            .execute("export OUTER=outer")
            .await
            .expect("export failed");

        let mut overlay = HashMap::new();
        overlay.insert("OUTER".to_string(), Value::String("inner".into()));
        let result = kernel
            .execute_with_options(r#"echo "${OUTER}""#, ExecuteOptions::new().with_vars(overlay))
            .await
            .expect("execute failed");
        assert_eq!(result.text_out().trim(), "inner");

        assert_eq!(
            kernel.get_var("OUTER").await,
            Some(Value::String("outer".into())),
            "outer value must reappear after pop"
        );
        assert!(
            kernel.scope.read().await.is_exported("OUTER"),
            "outer export must survive overlay"
        );
    }

    #[tokio::test]
    async fn test_execute_with_vars_inner_assignment_is_local() {
        let kernel = Kernel::transient().expect("failed to create kernel");
        let mut overlay = HashMap::new();
        overlay.insert("LOCAL_FOO".to_string(), Value::String("from-overlay".into()));

        // Variable assignment inside a single statement uses set() (innermost
        // frame), not set_global() — this matches bash function-local semantics.
        // We explicitly use `local FOO=...` style by relying on the pushed
        // frame; the assignment in the script body modifies the same frame.
        let result = kernel
            .execute_with_options(
                r#"LOCAL_FOO="reassigned"; echo "${LOCAL_FOO}""#,
                ExecuteOptions::new().with_vars(overlay),
            )
            .await
            .expect("execute failed");
        assert!(result.ok());

        // After the call the frame is popped, so LOCAL_FOO is gone regardless
        // of how the script reassigned it.
        assert_eq!(kernel.get_var("LOCAL_FOO").await, None);
    }

    #[tokio::test]
    async fn test_external_command_sees_exported_var() {
        let kernel = Kernel::transient().expect("failed to create kernel");
        // PATH must be in scope to resolve the external `printenv` — the kernel
        // never falls back to OS PATH. Seeding it via a scope assignment mirrors
        // what a frontend does through initial_vars.
        let path = std::env::var("PATH").unwrap_or_default();
        let result = kernel
            .execute(&format!(
                "PATH=\"{path}\"; export EXT_FOO=bar; printenv EXT_FOO"
            ))
            .await
            .expect("execute failed");

        assert!(result.ok(), "printenv should succeed: stderr={}", result.err);
        assert_eq!(result.text_out().trim(), "bar");
    }

    #[tokio::test]
    async fn test_external_command_does_not_see_unexported_var() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        // Set without exporting; printenv must not see it (exit code != 0,
        // empty stdout per printenv semantics).
        let result = kernel
            .execute("EXT_BAR=hidden; printenv EXT_BAR")
            .await
            .expect("execute failed");

        assert!(!result.ok(), "printenv should fail when var is unexported");
        assert!(
            result.text_out().trim().is_empty(),
            "no stdout when var is missing, got: {}",
            result.text_out()
        );
    }

    #[tokio::test]
    async fn test_external_command_does_not_see_os_env() {
        // The kernel is hermetic: it never reads std::env::vars() and only
        // exports what it has been told to export. Cargo always sets PATH for
        // tests, so PATH is reliably present in the OS env — but a transient
        // kernel doesn't seed it into initial_vars, so `printenv PATH` from
        // inside the kernel must fail.
        assert!(
            std::env::var_os("PATH").is_some(),
            "test precondition: cargo should set PATH"
        );

        let kernel = Kernel::transient().expect("failed to create kernel");
        let result = kernel
            .execute("printenv PATH")
            .await
            .expect("execute failed");

        assert!(
            !result.ok(),
            "printenv PATH must fail in hermetic kernel, got stdout={:?}",
            result.text_out()
        );
        assert!(
            result.text_out().trim().is_empty(),
            "no PATH in subprocess env, got stdout={:?}",
            result.text_out()
        );
    }

    #[tokio::test]
    async fn test_execute_with_vars_overlay_reaches_subprocess() {
        let kernel = Kernel::transient().expect("failed to create kernel");
        let mut overlay = HashMap::new();
        overlay.insert("SUB_FOO".to_string(), Value::String("subproc".into()));
        // PATH in the overlay so the external `printenv` resolves (no OS fallback).
        overlay.insert(
            "PATH".to_string(),
            Value::String(std::env::var("PATH").unwrap_or_default()),
        );

        let result = kernel
            .execute_with_options("printenv SUB_FOO", ExecuteOptions::new().with_vars(overlay))
            .await
            .expect("execute failed");

        assert!(
            result.ok(),
            "printenv should succeed: code={} stdout={:?} stderr={:?}",
            result.code,
            result.text_out(),
            result.err
        );
        assert_eq!(result.text_out().trim(), "subproc");
    }

    #[tokio::test]
    async fn test_classify_command_builtin() {
        let kernel = Kernel::transient().expect("failed to create kernel");
        assert_eq!(kernel.classify_command("cat").await, CommandKind::Builtin);
        assert_eq!(kernel.classify_command("grep").await, CommandKind::Builtin);
    }

    #[tokio::test]
    async fn test_classify_command_special_forms() {
        let kernel = Kernel::transient().expect("failed to create kernel");
        for name in ["true", "false", "source", "."] {
            assert_eq!(
                kernel.classify_command(name).await,
                CommandKind::Special,
                "{name} should be a special-form",
            );
        }
    }

    #[tokio::test]
    async fn test_classify_command_dynamic() {
        let kernel = Kernel::transient().expect("failed to create kernel");
        assert_eq!(kernel.classify_command("$cmd").await, CommandKind::Dynamic);
        assert_eq!(
            kernel.classify_command("$(pick)").await,
            CommandKind::Dynamic
        );
    }

    #[tokio::test]
    async fn test_classify_command_external() {
        let kernel = Kernel::transient().expect("failed to create kernel");
        // Not a builtin, user function, or special-form → escapes to PATH.
        assert_eq!(
            kernel.classify_command("definitely_not_a_kaish_builtin").await,
            CommandKind::External
        );
        // `readonly` is *not* a kaish special-form despite the validator's
        // warning heuristic — at runtime it resolves to an external command, so
        // a consent gate must see it as External (regression guard against the
        // validator/runtime divergence).
        assert_eq!(
            kernel.classify_command("readonly").await,
            CommandKind::External
        );
        assert!(kernel.classify_command("readonly").await.escapes_kernel());
    }

    #[tokio::test]
    async fn test_classify_command_user_tool_shadows_builtin() {
        let kernel = Kernel::transient().expect("failed to create kernel");
        kernel
            .execute(r#"greet() { echo "hi" }"#)
            .await
            .expect("function definition failed");
        assert_eq!(
            kernel.classify_command("greet").await,
            CommandKind::UserTool
        );

        // A user function named after a builtin classifies as UserTool, matching
        // the interpreter's user-tools-first resolution.
        kernel
            .execute(r#"cat() { echo "shadowed" }"#)
            .await
            .expect("function definition failed");
        assert_eq!(kernel.classify_command("cat").await, CommandKind::UserTool);
    }

    #[tokio::test]
    async fn test_classify_command_alias_to_external_is_external() {
        let kernel = Kernel::transient().expect("failed to create kernel");
        // An alias whose head is an external binary must NOT report as the
        // builtin it shadows — execution expands the alias, so a consent gate
        // would otherwise be told an external command is internal.
        kernel
            .execute("alias cat='/usr/bin/whatever'")
            .await
            .expect("alias failed");
        assert_eq!(kernel.classify_command("cat").await, CommandKind::External);
        assert!(kernel.classify_command("cat").await.escapes_kernel());
    }

    #[tokio::test]
    async fn test_classify_command_alias_to_builtin() {
        let kernel = Kernel::transient().expect("failed to create kernel");
        kernel.execute("alias g=grep").await.expect("alias failed");
        assert_eq!(kernel.classify_command("g").await, CommandKind::Builtin);
    }

    #[tokio::test]
    async fn test_classify_command_alias_to_special_form() {
        let kernel = Kernel::transient().expect("failed to create kernel");
        kernel.execute("alias t=true").await.expect("alias failed");
        assert_eq!(kernel.classify_command("t").await, CommandKind::Special);
    }

    #[tokio::test]
    async fn test_classify_command_braced_var_is_dynamic() {
        let kernel = Kernel::transient().expect("failed to create kernel");
        // The string API can be handed a `${VAR}` head; it must not be mistaken
        // for an external named literally "${VAR}".
        assert_eq!(
            kernel.classify_command("${CMD}").await,
            CommandKind::Dynamic
        );
    }

    /// Drift guard: `classify_command` must agree with what the executor
    /// (`execute_command_depth`) actually resolves. The classifier duplicates the
    /// interpreter's resolution rules (special-form set, user-tools-before-builtins
    /// precedence, alias expansion); without this test those copies could diverge
    /// silently — the exact failure class `classify_command` exists to prevent,
    /// just moved inside the kernel. Each case asserts the classification AND
    /// observes the real resolution, so a future change to one side without the
    /// other fails here.
    #[tokio::test]
    async fn classify_command_matches_executor() {
        let kernel = Kernel::transient().expect("failed to create kernel");

        // (1) Special-forms. `SpecialForm::from_name` is the single source of
        // truth: classify reports Special via it, and the executor matches the
        // enum exhaustively, so const↔behavior parity is compile-enforced (a new
        // form won't build until both sides handle it). This test pins the other
        // half — that each form classifies Special AND actually short-circuits at
        // runtime rather than escaping to `PATH`. Every form is executed (not just
        // `true`/`false`): an external miss in this PATH-less kernel would be exit
        // 127, so a non-127 result that matches the form's own behavior proves the
        // short-circuit fired.
        for name in ["true", "false", "source", "."] {
            assert_eq!(
                kernel.classify_command(name).await,
                CommandKind::Special,
                "{name} should classify Special",
            );
        }
        assert_eq!(kernel.execute("true").await.expect("run true").code, 0);
        assert_eq!(kernel.execute("false").await.expect("run false").code, 1);
        // `source`/`.` short-circuit to execute_source, which (no filename) fails
        // with its own message — exit 1, never the 127 of an unresolved external.
        for name in ["source", "."] {
            let r = kernel.execute(name).await.expect("run source form");
            assert_ne!(r.code, 127, "{name} fell through to PATH instead of source");
            assert!(
                r.err.contains("source: missing filename"),
                "{name} did not route to execute_source: {:?}",
                r.err,
            );
        }

        // (2) Builtin: classify Builtin AND the executor runs the builtin.
        assert_eq!(kernel.classify_command("echo").await, CommandKind::Builtin);
        let r = kernel.execute("echo hi").await.expect("run echo");
        assert!(r.ok() && r.text_out().trim() == "hi", "echo builtin didn't run");

        // (3) User function shadows a builtin: classify UserTool AND the executor
        // runs the function body, not the `cat` builtin.
        kernel
            .execute(r#"cat() { echo SHADOWED }"#)
            .await
            .expect("define cat()");
        assert_eq!(kernel.classify_command("cat").await, CommandKind::UserTool);
        let r = kernel.execute("cat").await.expect("run shadowed cat");
        assert_eq!(
            r.text_out().trim(),
            "SHADOWED",
            "executor ran the builtin instead of the shadowing function",
        );

        // (4) Alias whose head is external: classify External AND the executor
        // resolves through the alias to a missing external (not a builtin).
        kernel
            .execute("alias x='/nonexistent/binary'")
            .await
            .expect("define alias x");
        assert_eq!(kernel.classify_command("x").await, CommandKind::External);
        let r = kernel.execute("x").await.expect("run alias x");
        assert!(
            !r.ok(),
            "alias to a missing external should fail, not resolve internally",
        );
    }

    /// `kill_grace` is the number the SIGTERM-to-SIGKILL cascade waits on, and
    /// the spawn path reads it off the execution context. Seeding it only on
    /// the `Kernel` would silently give every child the 2s default instead of
    /// the embedder's setting.
    #[tokio::test]
    async fn kill_grace_reaches_the_execution_context_and_its_forks() {
        let grace = Duration::from_millis(250);
        let kernel = Kernel::new(KernelConfig::transient().with_kill_grace(grace))
            .expect("build kernel");
        assert_eq!(
            kernel.exec_ctx.read().await.kill_grace,
            grace,
            "the configured kill grace never reached the execution context",
        );

        let fork = kernel.fork().await;
        assert_eq!(
            fork.exec_ctx.read().await.kill_grace,
            grace,
            "a fork's children would be killed on a different clock than the parent's",
        );
    }

    /// A child spawned under a background job records its process group on
    /// that job (for `kill -<sig> %N`) and tees its output into the job's
    /// streams. Both reads go through the execution context, so the job id has
    /// to survive `fork_for_background` and every sub-fork beneath it.
    #[tokio::test]
    async fn a_background_fork_stamps_its_job_on_the_execution_context() {
        let kernel = Kernel::transient().expect("build kernel").into_arc();
        assert_eq!(
            kernel.exec_ctx.read().await.background_job,
            None,
            "foreground execution must not claim a job",
        );

        let (_tx, rx) = tokio::sync::oneshot::channel();
        let job_id = kernel.jobs.register("sleep 60".to_string(), rx).await;
        let cancel = tokio_util::sync::CancellationToken::new();
        let background = kernel.fork_for_background(cancel, job_id).await;
        assert_eq!(
            background.exec_ctx.read().await.background_job,
            Some(job_id),
            "a background fork's children would never be registered on the job",
        );

        let stage = background.fork().await;
        assert_eq!(
            stage.exec_ctx.read().await.background_job,
            Some(job_id),
            "a pipeline stage under a background job lost the job id",
        );
    }
}