harn_vm/stdlib/

process.rs

use crate::value::VmDictExt;
use std::cell::RefCell;
use std::collections::BTreeMap;
use std::io::Write as _;
use std::path::PathBuf;
use std::process::Stdio;
use std::time::{Duration, Instant};

use crate::orchestration::RunExecutionRecord;
use crate::stdlib::macros::{harn_builtin, VmBuiltinDef};
use crate::value::{VmError, VmValue};
use crate::vm::Vm;

const HARN_REPLAY_ENV: &str = "HARN_REPLAY";

thread_local! {
    pub(crate) static VM_SOURCE_DIR: RefCell<Option<PathBuf>> = const { RefCell::new(None) };
    static VM_EXECUTION_CONTEXT: RefCell<Option<RunExecutionRecord>> = const { RefCell::new(None) };
    /// The resolved environment for the current launched session. `None` means
    /// this thread is outside a session boundary. Held across a worker's `.await`s and
    /// so swapped per-task by the ambient scope; its `_CONTEXT` suffix enrolls it
    /// in the ambient-thread-local drift guard.
    static SESSION_ENVIRONMENT_CONTEXT: RefCell<Option<crate::security::SessionEnvironment>> =
        const { RefCell::new(None) };
}

/// Set the source directory for the current thread (called by VM on file execution).
pub(crate) fn set_thread_source_dir(dir: &std::path::Path) {
    set_thread_source_dir_option(Some(dir));
}

pub(crate) fn set_thread_source_dir_option(dir: Option<&std::path::Path>) {
    VM_SOURCE_DIR.with(|current| {
        *current.borrow_mut() = dir.map(normalize_context_path);
    });
}

pub(crate) fn normalize_context_path(path: &std::path::Path) -> PathBuf {
    if path.is_absolute() {
        return path.to_path_buf();
    }
    std::env::current_dir()
        .map(|cwd| cwd.join(path))
        .unwrap_or_else(|_| path.to_path_buf())
}

pub fn set_thread_execution_context(context: Option<RunExecutionRecord>) {
    VM_EXECUTION_CONTEXT.with(|current| *current.borrow_mut() = context);
}

pub(crate) fn current_execution_context() -> Option<RunExecutionRecord> {
    VM_EXECUTION_CONTEXT.with(|current| current.borrow().clone())
}

/// Install (or clear) the environment policy the current session runs under.
/// Called at the session launch boundary once the declared policy
/// and grants have been resolved into a [`crate::security::SessionEnvironment`].
pub fn set_session_environment(environment: Option<crate::security::SessionEnvironment>) {
    SESSION_ENVIRONMENT_CONTEXT.with(|current| *current.borrow_mut() = environment);
}

/// The environment policy governing subprocess env construction for the current
/// task, or `None` on the legacy non-session path.
pub(crate) fn current_session_environment() -> Option<crate::security::SessionEnvironment> {
    SESSION_ENVIRONMENT_CONTEXT.with(|current| current.borrow().clone())
}

/// Per-task ambient-scope swap of the session environment. Same rationale as
/// [`swap_thread_execution_context`]: a fan-out worker holds its session's
/// environment across `.await`s, so it must keep its own copy rather than read a
/// cooperatively-scheduled sibling's. `pub(crate)` — only the ambient combinator
/// moves whole environments; launch code uses [`set_session_environment`].
pub(crate) fn swap_session_environment(
    next: Option<crate::security::SessionEnvironment>,
) -> Option<crate::security::SessionEnvironment> {
    SESSION_ENVIRONMENT_CONTEXT.with(|current| std::mem::replace(&mut *current.borrow_mut(), next))
}

/// Per-task ambient-scope swap of the thread execution context. See
/// `orchestration::ambient_scope`: the execution context carries the running
/// task's cwd/env/source-dir AND anchors the capability path-scope workspace
/// root, so a worker holding it across an `.await` must keep its OWN copy rather
/// than read whatever a cooperatively-scheduled fan-out sibling left behind. The
/// helper is `pub(crate)` — only the ambient combinator moves whole contexts;
/// ordinary code uses `set_thread_execution_context`/`current_execution_context`.
pub(crate) fn swap_thread_execution_context(
    next: Option<RunExecutionRecord>,
) -> Option<RunExecutionRecord> {
    VM_EXECUTION_CONTEXT.with(|current| std::mem::replace(&mut *current.borrow_mut(), next))
}

/// Per-task ambient-scope swap of the VM source directory. Same rationale as
/// [`swap_thread_execution_context`]: it anchors source-relative path
/// resolution for the running task, so it must follow that task across `.await`.
pub(crate) fn swap_source_dir(next: Option<PathBuf>) -> Option<PathBuf> {
    VM_SOURCE_DIR.with(|current| std::mem::replace(&mut *current.borrow_mut(), next))
}

/// Anchor a synchronous call frame on the callee module's source dir, returning
/// the caller's dir for that frame to reinstall when it pops.
///
/// `None` in means the callee has no module of its own and keeps the caller's
/// anchor. `None` out means the frame has nothing to restore — either because
/// of that, or because the caller had no anchor either.
///
/// This is the *synchronous* half of the source-dir discipline: the write and
/// the restore both happen on one task, bracketed by one frame's lifetime. A
/// body that runs as its own task cannot use it, because the frame pops on that
/// task long after the caller resumed — see
/// [`crate::orchestration::scope_spawned_source_dir`].
pub(crate) fn enter_frame_source_dir(module_dir: Option<&std::path::Path>) -> Option<PathBuf> {
    let dir = module_dir?;
    let previous = VM_SOURCE_DIR.with(|sd| sd.borrow().clone());
    crate::stdlib::set_thread_source_dir(dir);
    previous
}

/// RAII guard that snapshots the thread-local VM source dir on creation and
/// restores it on drop.
///
/// Out-of-band module loads — a connector contract load, a dependency package
/// load — spin up their own isolated `Vm` but call `Vm::set_source_dir`, which
/// unconditionally writes the *shared* thread-local `VM_SOURCE_DIR`. Left
/// unrestored, that leaves the caller's resting source-dir context pointing at
/// the loaded dependency, so a subsequent top-level `render("@alias/...")` /
/// `render("relative/...")` in the entry module resolves against the
/// dependency's `harn.toml` instead of the project root. Holding this guard
/// across such a load keeps the load invisible to the caller's source-dir
/// context — mirroring the per-frame save/restore discipline in `vm::execution`.
pub(crate) struct SourceDirGuard {
    previous: Option<PathBuf>,
}

impl SourceDirGuard {
    /// Snapshot the current thread-local source dir.
    pub(crate) fn capture() -> Self {
        Self {
            previous: VM_SOURCE_DIR.with(|sd| sd.borrow().clone()),
        }
    }
}

impl Drop for SourceDirGuard {
    fn drop(&mut self) {
        let previous = self.previous.take();
        VM_SOURCE_DIR.with(|sd| *sd.borrow_mut() = previous);
    }
}

/// Reset thread-local process state (for test isolation).
pub(crate) fn reset_process_state() {
    VM_SOURCE_DIR.with(|sd| *sd.borrow_mut() = None);
    VM_EXECUTION_CONTEXT.with(|current| *current.borrow_mut() = None);
}

pub fn execution_root_path() -> PathBuf {
    current_execution_context()
        .and_then(|context| context.cwd.map(PathBuf::from))
        .or_else(|| std::env::current_dir().ok())
        .unwrap_or_else(|| PathBuf::from("."))
}

/// The form of `path` a child process can actually be started in.
///
/// Canonicalizing a path on Windows yields the extended-length `\\?\C:\...`
/// form. That form is correct for the Win32 file APIs and unusable as a
/// working directory for a shell: `cmd.exe` refuses it as a UNC path, prints
/// "UNC paths are not supported", and then starts anyway in the Windows
/// directory. The child is left running somewhere it was never asked to run,
/// so every workspace-relative path it is given is missing, and the failure
/// names the missing file rather than the wrong directory.
///
/// Stripping the prefix is a no-op on POSIX, where no path begins with it, so
/// this is applied on every platform rather than behind a `cfg` and the same
/// seam is exercised wherever the tests run. A true UNC path
/// (`\\?\UNC\server\share`) is left alone: there is no drive-letter form of
/// it to fall back to, and rewriting it would name a different location.
pub(crate) fn child_process_cwd(path: std::path::PathBuf) -> std::path::PathBuf {
    match path.to_str().and_then(strip_windows_verbatim_prefix) {
        Some(stripped) => std::path::PathBuf::from(stripped),
        None => path,
    }
}

/// Strip a `\\?\` verbatim-disk-path prefix from `path`, or return `None`
/// when `path` is not one. Split out from [`child_process_cwd`] so the rule
/// is testable as a pure string transformation on any platform.
///
/// Every `std/path` helper normalizes its output to forward slashes
/// (`stdlib/path.rs`'s `to_posix`, documented there as deliberate: Harn
/// scripts see one separator regardless of host OS). A `cwd` that reaches
/// here after passing through a Harn script — as `workspace_root(fs)` does
/// in `experiments/burin-mini` — therefore carries this same prefix spelled
/// `//?/C:/...`, not `\\?\C:\...`. Windows itself treats `/` and `\` as
/// interchangeable path separators, so both spellings name the same prefix
/// and both must be recognized here, or exactly the script-originated `cwd`
/// this function exists to fix keeps its un-stripped prefix and reproduces
/// the "UNC paths are not supported" failure one level removed.
#[expect(
    clippy::string_slice,
    reason = "the 4-byte prefix just matched is pure ASCII, so byte offset 4 is a guaranteed char boundary"
)]
fn strip_windows_verbatim_prefix(path: &str) -> Option<&str> {
    let bytes = path.as_bytes();
    let is_slash = |byte: u8| byte == b'\\' || byte == b'/';
    if bytes.len() < 4
        || !is_slash(bytes[0])
        || !is_slash(bytes[1])
        || bytes[2] != b'?'
        || !is_slash(bytes[3])
    {
        return None;
    }
    // The first four bytes matched are single-byte ASCII, so byte offset 4
    // is a valid char boundary to slice at.
    let rest = &path[4..];
    let mut chars = rest.chars();
    // A drive-letter path, and nothing else. `\\?\UNC\...` (and its
    // `//?/UNC/...` spelling) fails this and is deliberately left as it is.
    if !chars.next()?.is_ascii_alphabetic() {
        return None;
    }
    if chars.next()? != ':' {
        return None;
    }
    match chars.next() {
        Some('\\') | Some('/') | None => Some(rest),
        Some(_) => None,
    }
}

/// Resolve the directory an omitted process `cwd` inherits on the active path.
///
/// Sandboxed execution may deliberately choose the first launchable workspace
/// root when the host process cwd is outside the capability ceiling. Keep that
/// policy decision in the sandbox owner so process adapters can report the
/// exact cwd they will pass to the child without reimplementing it.
pub fn inherited_process_cwd() -> Result<PathBuf, VmError> {
    if let Some((policy, _profile)) = crate::stdlib::sandbox::active_sandbox_policy() {
        let preferred = current_execution_context()
            .and_then(|context| context.cwd)
            .filter(|cwd| !cwd.is_empty())
            .map(PathBuf::from);
        crate::stdlib::sandbox::policy_process_cwd(&policy, preferred.as_deref())
    } else {
        Ok(execution_root_path())
    }
}

pub fn project_root_path() -> Option<PathBuf> {
    current_execution_context().and_then(|context| {
        let project_root = context.project_root?;
        if project_root.trim().is_empty() {
            return None;
        }
        let path = PathBuf::from(project_root);
        if path.is_absolute() {
            Some(path)
        } else if let Some(cwd) = context.cwd {
            Some(PathBuf::from(cwd).join(path))
        } else {
            Some(normalize_context_path(&path))
        }
    })
}

pub fn source_root_path() -> PathBuf {
    VM_SOURCE_DIR
        .with(|sd| sd.borrow().clone())
        .or_else(|| {
            current_execution_context().and_then(|context| context.source_dir.map(PathBuf::from))
        })
        .or_else(|| current_execution_context().and_then(|context| context.cwd.map(PathBuf::from)))
        .or_else(|| std::env::current_dir().ok())
        .unwrap_or_else(|| PathBuf::from("."))
}

pub fn asset_root_path() -> PathBuf {
    source_root_path()
}

fn env_override(name: &str) -> Option<String> {
    (name == HARN_REPLAY_ENV && crate::triggers::dispatcher::current_dispatch_is_replay())
        .then(|| "1".to_string())
}

/// Runtime-owned environment projected into every child process.
///
/// These values are semantic execution context, not ambient host state. Keep
/// their construction here so `harness.env` reads and every process-launch
/// seam project the same values. Callers may still explicitly override or
/// remove a key at the process boundary.
pub(crate) fn runtime_child_env_overlay() -> Vec<(String, String)> {
    env_override(HARN_REPLAY_ENV)
        .map(|value| (HARN_REPLAY_ENV.to_string(), value))
        .into_iter()
        .collect()
}

pub(crate) fn read_env_value(name: &str) -> Option<String> {
    env_override(name)
        .or_else(|| current_execution_context().and_then(|context| context.env.get(name).cloned()))
        .or_else(|| session_env_var(name).ok().flatten())
}

pub fn runtime_root_base() -> PathBuf {
    project_root_path()
        .or_else(|| find_project_root(&execution_root_path()))
        .or_else(|| find_project_root(&source_root_path()))
        .unwrap_or_else(source_root_path)
}

/// Lexically collapse `..` components in `path`. Returns `None` if a
/// `..` would pop a non-Normal component (i.e. the path tries to walk
/// above its root anchor). This is a pure-string canonicalization that
/// does NOT hit the filesystem — symlinks are not followed.
fn lexically_collapse(path: &std::path::Path) -> Option<PathBuf> {
    use std::path::Component;
    let mut out: Vec<Component> = Vec::new();
    for component in path.components() {
        match component {
            Component::CurDir => {}
            Component::ParentDir => {
                let popped = out.pop();
                if !matches!(popped, Some(Component::Normal(_))) {
                    return None;
                }
            }
            other => out.push(other),
        }
    }
    Some(out.iter().collect())
}

pub fn resolve_source_relative_path(path: &str) -> PathBuf {
    let candidate = PathBuf::from(path);
    if candidate.is_absolute() {
        return candidate;
    }
    let root = execution_root_path();
    let joined = root.join(&candidate);
    // Defense-in-depth path-traversal check (paired with the deferred
    // F3 sandbox-by-default fix): refuse to resolve a path that
    // escapes the project root via `..` components. We anchor against
    // `runtime_root_base()` (the project root), which is broader than
    // `execution_root_path()` and lets benign sibling-dir walks like
    // `read_file("../fixtures/payload.json")` from `tests/` succeed.
    if path_escapes_project_root(&joined) {
        return root.join("__harn_rejected_parent_dir_traversal__");
    }
    joined
}

pub fn resolve_source_asset_path(path: &str) -> PathBuf {
    let candidate = PathBuf::from(path);
    if candidate.is_absolute() {
        return candidate;
    }
    let root = asset_root_path();
    let joined = root.join(&candidate);
    if path_escapes_project_root(&joined) {
        return root.join("__harn_rejected_parent_dir_traversal__");
    }
    joined
}

/// Returns `true` when `joined` (which may contain raw `..`
/// components) cannot be lexically collapsed without popping past its
/// root component — i.e. the relative input had more `..` than the
/// joined depth allows, escaping the filesystem root.
///
/// This is intentionally a narrow check: it doesn't try to enforce
/// that the path stays inside a logical "project root", because the
/// project root isn't always reliably resolvable (and benign uses
/// like `../fixtures/x.json` from a `tests/` subdir are legitimate).
/// The sandbox layer remains the authoritative defense for arbitrary
/// `..` traversal; this guard plugs the most egregious escapes
/// (`../../../../etc/passwd`) for the no-sandbox-by-default
/// `harn run` path.
fn path_escapes_project_root(joined: &std::path::Path) -> bool {
    lexically_collapse(joined).is_none()
}

pub(crate) fn register_process_builtins(vm: &mut Vm) {
    for def in PROCESS_BUILTINS {
        vm.register_builtin_def(def);
    }
}

#[harn_builtin(
    exposure = "runtime_internal",
    effects = [],
    sig = "env(name: string) -> string?", category = "process"
)]
fn env_impl(args: &[VmValue], _out: &mut String) -> Result<VmValue, VmError> {
    let name = args.first().map(|a| a.display()).unwrap_or_default();
    if let Some(value) = read_env_value(&name) {
        return Ok(VmValue::String(arcstr::ArcStr::from(value)));
    }
    Ok(VmValue::Nil)
}

#[harn_builtin(
    exposure = "runtime_internal",
    effects = [],
    sig = "env_or(name: string, default: any) -> any",
    category = "process"
)]
fn env_or_impl(args: &[VmValue], _out: &mut String) -> Result<VmValue, VmError> {
    let name = args.first().map(|a| a.display()).unwrap_or_default();
    let default = args.get(1).cloned().unwrap_or(VmValue::Nil);
    if let Some(value) = read_env_value(&name) {
        return Ok(VmValue::String(arcstr::ArcStr::from(value)));
    }
    Ok(default)
}

#[harn_builtin(
    exposure = "runtime_internal",
    effects = [],
    sig = "exit(code?: int) -> never", category = "process"
)]
fn exit_impl(args: &[VmValue], _out: &mut String) -> Result<VmValue, VmError> {
    let code = args.first().and_then(|a| a.as_int()).unwrap_or(0);
    Err(VmError::ProcessExit(code as i32))
}

#[harn_builtin(
    exposure = "runtime_internal",
    effects = [],
    sig = "exec(...command: string) -> dict", category = "process"
)]
fn exec_impl(args: &[VmValue], _out: &mut String) -> Result<VmValue, VmError> {
    if args.is_empty() {
        return Err(VmError::Thrown(VmValue::String(arcstr::ArcStr::from(
            "exec: command is required",
        ))));
    }
    let cmd = args[0].display();
    let cmd_args: Vec<String> = args[1..].iter().map(|a| a.display()).collect();
    let output = exec_command(None, &cmd, &cmd_args)?;
    Ok(vm_output_to_value(output))
}

#[harn_builtin(
    exposure = "runtime_internal",
    effects = [],
    sig = "shell(command: string) -> dict", category = "process"
)]
fn shell_impl(args: &[VmValue], _out: &mut String) -> Result<VmValue, VmError> {
    let cmd = args.first().map(|a| a.display()).unwrap_or_default();
    if cmd.is_empty() {
        return Err(VmError::Thrown(VmValue::String(arcstr::ArcStr::from(
            "shell: command string is required",
        ))));
    }
    let invocation = crate::shells::default_shell_invocation(&cmd)
        .map_err(|error| VmError::Runtime(format!("shell: {error}")))?;
    let output = exec_shell_args(None, &invocation.program, &invocation.args)?;
    Ok(vm_output_to_value(output))
}

#[harn_builtin(
    exposure = "runtime_internal",
    effects = [],
    sig = "exec_at(dir: string, ...command: string) -> dict",
    category = "process"
)]
fn exec_at_impl(args: &[VmValue], _out: &mut String) -> Result<VmValue, VmError> {
    if args.len() < 2 {
        return Err(VmError::Thrown(VmValue::String(arcstr::ArcStr::from(
            "exec_at: directory and command are required",
        ))));
    }
    let dir = args[0].display();
    let cmd = args[1].display();
    let cmd_args: Vec<String> = args[2..].iter().map(|a| a.display()).collect();
    let output = exec_command(Some(dir.as_str()), &cmd, &cmd_args)?;
    Ok(vm_output_to_value(output))
}

#[harn_builtin(
    exposure = "runtime_internal",
    effects = [],
    sig = "shell_at(dir: string, command: string) -> dict",
    category = "process"
)]
fn shell_at_impl(args: &[VmValue], _out: &mut String) -> Result<VmValue, VmError> {
    if args.len() < 2 {
        return Err(VmError::Thrown(VmValue::String(arcstr::ArcStr::from(
            "shell_at: directory and command string are required",
        ))));
    }
    let dir = args[0].display();
    let cmd = args[1].display();
    if cmd.is_empty() {
        return Err(VmError::Thrown(VmValue::String(arcstr::ArcStr::from(
            "shell_at: command string is required",
        ))));
    }
    let invocation = crate::shells::default_shell_invocation(&cmd)
        .map_err(|error| VmError::Runtime(format!("shell_at: {error}")))?;
    let output = exec_shell_args(Some(dir.as_str()), &invocation.program, &invocation.args)?;
    Ok(vm_output_to_value(output))
}

#[harn_builtin(
    exposure = "runtime_internal",
    effects = [],
    sig = "username(...args: any) -> string", category = "process"
)]
fn username_impl(_args: &[VmValue], _out: &mut String) -> Result<VmValue, VmError> {
    let user = std::env::var("USER")
        .or_else(|_| std::env::var("USERNAME"))
        .unwrap_or_default();
    Ok(VmValue::String(arcstr::ArcStr::from(user)))
}

#[harn_builtin(
    exposure = "runtime_internal",
    effects = [],
    sig = "hostname() -> string", category = "process"
)]
fn hostname_impl(_args: &[VmValue], _out: &mut String) -> Result<VmValue, VmError> {
    let name = std::env::var("HOSTNAME")
        .or_else(|_| std::env::var("COMPUTERNAME"))
        .or_else(|_| {
            std::process::Command::new("hostname")
                .output()
                .ok()
                .map(|o| String::from_utf8_lossy(&o.stdout).trim().to_string())
                .ok_or(std::env::VarError::NotPresent)
        })
        .unwrap_or_default();
    Ok(VmValue::String(arcstr::ArcStr::from(name)))
}

#[harn_builtin(
    exposure = "runtime_internal",
    effects = [],
    sig = "platform(...args: any) -> string", category = "process"
)]
fn platform_impl(_args: &[VmValue], _out: &mut String) -> Result<VmValue, VmError> {
    let os = if cfg!(target_os = "macos") {
        "darwin"
    } else if cfg!(target_os = "linux") {
        "linux"
    } else if cfg!(target_os = "windows") {
        "windows"
    } else {
        std::env::consts::OS
    };
    Ok(VmValue::String(arcstr::ArcStr::from(os)))
}

#[harn_builtin(
    exposure = "runtime_internal",
    effects = [],
    sig = "arch() -> string", category = "process"
)]
fn arch_impl(_args: &[VmValue], _out: &mut String) -> Result<VmValue, VmError> {
    Ok(VmValue::String(arcstr::ArcStr::from(
        std::env::consts::ARCH,
    )))
}

#[harn_builtin(
    exposure = "runtime_internal",
    effects = [],
    sig = "home_dir() -> string", category = "process"
)]
fn home_dir_impl(_args: &[VmValue], _out: &mut String) -> Result<VmValue, VmError> {
    let home = crate::user_dirs::home_dir()
        .map(|home| home.to_string_lossy().into_owned())
        .unwrap_or_default();
    Ok(VmValue::String(arcstr::ArcStr::from(home)))
}

#[harn_builtin(
    exposure = "runtime_internal",
    effects = [],
    sig = "pid(...args: any) -> int", category = "process"
)]
fn pid_impl(_args: &[VmValue], _out: &mut String) -> Result<VmValue, VmError> {
    Ok(VmValue::Int(std::process::id() as i64))
}

#[harn_builtin(
    exposure = "runtime_internal",
    effects = [],
    sig = "date_iso() -> string", category = "process"
)]
fn date_iso_impl(_args: &[VmValue], _out: &mut String) -> Result<VmValue, VmError> {
    // `date_iso` reads the OS wall clock directly (it predates the
    // unified `clock_mock`). Routing through `leak_audit::wall_now`
    // keeps the production behavior unchanged but surfaces the call
    // in `testbench_clock_leaks()` whenever a script invokes it
    // under a paused testbench session, so fidelity hazards are
    // visible instead of silently corrupting tapes.
    let now = crate::clock_mock::leak_audit::wall_now("stdlib/date_iso");
    let dt: chrono::DateTime<chrono::Utc> = now.into();
    Ok(VmValue::String(arcstr::ArcStr::from(
        dt.to_rfc3339_opts(chrono::SecondsFormat::Millis, true),
    )))
}

#[harn_builtin(
    exposure = "runtime_internal",
    effects = [],
    sig = "cwd() -> string", category = "process"
)]
fn cwd_impl(_args: &[VmValue], _out: &mut String) -> Result<VmValue, VmError> {
    let dir = current_execution_context()
        .and_then(|context| context.cwd)
        .or_else(|| {
            std::env::current_dir()
                .ok()
                .map(|p| p.to_string_lossy().into_owned())
        })
        .unwrap_or_default();
    Ok(VmValue::String(arcstr::ArcStr::from(dir)))
}

#[harn_builtin(
    exposure = "runtime_internal",
    effects = [],
    sig = "execution_root() -> string", category = "process"
)]
fn execution_root_impl(_args: &[VmValue], _out: &mut String) -> Result<VmValue, VmError> {
    Ok(VmValue::String(arcstr::ArcStr::from(
        execution_root_path().to_string_lossy().into_owned(),
    )))
}

#[harn_builtin(
    exposure = "runtime_internal",
    effects = [],
    sig = "asset_root() -> string", category = "process"
)]
fn asset_root_impl(_args: &[VmValue], _out: &mut String) -> Result<VmValue, VmError> {
    Ok(VmValue::String(arcstr::ArcStr::from(
        asset_root_path().to_string_lossy().into_owned(),
    )))
}

/// The single owner of Harn's runtime path model for scripts.
///
/// The three roots below resolve through [`crate::runtime_paths`], so they
/// honor `HARN_STATE_DIR` / `HARN_RUN_DIR` / `HARN_WORKTREE_DIR` and no script
/// needs to know that the default segment is spelled `.harn`. Every script
/// that wants Harn's own runtime state should ask here rather than rebuild
/// the path from a literal, which silently ignores those overrides.
///
/// These are the *ambient* roots — the ones belonging to the run in progress.
/// A helper acting on a directory handed to it by its caller (a repository
/// named in an argument, say) wants that directory joined explicitly instead:
/// an absolute `HARN_STATE_DIR` deliberately discards the base, which is right
/// for the current run and wrong for an arbitrary one.
#[harn_builtin(
    exposure = "runtime_internal",
    effects = [],
    sig = "runtime_paths() -> {execution_root: string, asset_root: string, state_root: string, run_root: string, worktree_root: string}",
    category = "process"
)]
fn runtime_paths_impl(_args: &[VmValue], _out: &mut String) -> Result<VmValue, VmError> {
    let runtime_base = runtime_root_base();
    let mut paths = BTreeMap::new();
    paths.put_str("execution_root", execution_root_path().to_string_lossy());
    paths.put_str("asset_root", asset_root_path().to_string_lossy());
    paths.put_str(
        "state_root",
        crate::runtime_paths::state_root(&runtime_base).to_string_lossy(),
    );
    paths.put_str(
        "run_root",
        crate::runtime_paths::run_root(&runtime_base).to_string_lossy(),
    );
    paths.put_str(
        "worktree_root",
        crate::runtime_paths::worktree_root(&runtime_base).to_string_lossy(),
    );
    Ok(VmValue::dict(paths))
}

// `term_width()` / `term_height()` return the current terminal
// dimensions in columns and rows. Reads `COLUMNS` / `LINES` env vars
// first (so test harnesses can pin a value), falls back to the
// platform `ioctl` size, and finally defaults to 80x24 when neither
// is available (e.g. when stdout is not a TTY). These are the
// free-builtin aliases for `harness.term.width()` /
// `harness.term.height()`. `std/tui` already exposes
// `__tui_terminal_width` for its renderer; these aliases keep
// ported subcommands working without importing the tui module.
#[harn_builtin(
    exposure = "runtime_internal",
    effects = [],
    sig = "term_width() -> int", category = "process"
)]
fn term_width_impl(_args: &[VmValue], _out: &mut String) -> Result<VmValue, VmError> {
    Ok(VmValue::Int(crate::term::width() as i64))
}

#[harn_builtin(
    exposure = "runtime_internal",
    effects = [],
    sig = "term_height() -> int", category = "process"
)]
fn term_height_impl(_args: &[VmValue], _out: &mut String) -> Result<VmValue, VmError> {
    Ok(VmValue::Int(crate::term::height() as i64))
}

const PROCESS_BUILTINS: &[&VmBuiltinDef] = &[
    &ENV_IMPL_DEF,
    &ENV_OR_IMPL_DEF,
    &EXIT_IMPL_DEF,
    &EXEC_IMPL_DEF,
    &EXEC_OPTS_IMPL_DEF,
    &SHELL_IMPL_DEF,
    &EXEC_AT_IMPL_DEF,
    &EXEC_AT_OPTS_IMPL_DEF,
    &SHELL_AT_IMPL_DEF,
    &USERNAME_IMPL_DEF,
    &HOSTNAME_IMPL_DEF,
    &PLATFORM_IMPL_DEF,
    &ARCH_IMPL_DEF,
    &HOME_DIR_IMPL_DEF,
    &PID_IMPL_DEF,
    &DATE_ISO_IMPL_DEF,
    &CWD_IMPL_DEF,
    &EXECUTION_ROOT_IMPL_DEF,
    &ASSET_ROOT_IMPL_DEF,
    &RUNTIME_PATHS_IMPL_DEF,
    &TERM_WIDTH_IMPL_DEF,
    &TERM_HEIGHT_IMPL_DEF,
];

/// Parameters for [`run_captured_spawn`]: a single synchronous subprocess
/// spawn that captures stdout/stderr, optionally feeds stdin, optionally
/// enforces a wall-clock timeout, and either merges (`env_clear == false`)
/// or replaces (`env_clear == true`) the parent environment with `env`.
struct CapturedSpawn<'a> {
    label: &'static str,
    cmd: &'a str,
    args: &'a [String],
    cwd: Option<&'a str>,
    env: &'a [(String, String)],
    env_clear: bool,
    stdin: Option<Vec<u8>>,
    timeout: Option<Duration>,
}

/// Result of [`run_captured_spawn`].
struct CapturedRun {
    output: std::process::Output,
    timed_out: bool,
    interrupted: bool,
    duration_ms: i64,
}

#[path = "process_program_resolution.rs"]
mod program_resolution;
pub(crate) use program_resolution::{resolve_program_path, resolve_program_path_for_spawn};

/// Shared synchronous spawn-and-capture core used by `harness.process.run` and
/// the `exec_opts`/`exec_at_opts` internal builtins. Honors cwd, an env
/// overlay (merge or replace via `env_clear`), the live session environment's
/// closed environment, optional stdin, and an optional wall-clock timeout
/// (after which the child is killed and `timed_out` is set).
///
/// The child runs in its own process group and the wait polls
/// [`crate::op_interrupt::requested`], so scope cancellation, `deadline`
/// expiry, and VM drop gracefully terminate the whole child tree
/// (SIGTERM, grace, SIGKILL) instead of orphaning it. See
/// `crate::op_interrupt` for the mechanism.
fn run_captured_spawn(spec: CapturedSpawn<'_>) -> Result<CapturedRun, VmError> {
    let label = spec.label;
    // A `replace` request (`env_clear`) is already closed — only the caller's
    // keys survive — so it needs no further narrowing. A `merge` request would
    // otherwise inherit the parent environment wholesale, which under a session
    // environment means credentials crossing into the child. Route it through the
    // same resolver `process_command_config` uses so both seams close together.
    let resolved_environment = if spec.env_clear {
        None
    } else {
        session_closed_env_for_command(spec.cmd, spec.env.iter().cloned())?
    };
    // Resolve a bare program name to an absolute path using the EXACT `PATH`
    // the child is about to receive, searched here in the parent (harn#7993).
    let resolved_cmd =
        resolve_program_path(spec.cmd, &resolved_environment, spec.env_clear, spec.env);
    let mut command = std::process::Command::new(&resolved_cmd);
    command.args(spec.args);
    if let Some(cwd) = spec.cwd {
        // Every child-process seam starts the child through `child_process_cwd`
        // so a canonicalized (verbatim-prefixed) directory from `cwd()` or
        // `canonicalize` is a directory Windows will actually start a process
        // in. This seam had no such step, so `process.run(cmd, {cwd: cwd()})`
        // failed with ERROR_DIRECTORY (os error 267) on Windows while the same
        // call through `process.exec` succeeded.
        command.current_dir(child_process_cwd(PathBuf::from(cwd)));
    }
    if spec.env_clear || resolved_environment.is_some() {
        command.env_clear();
    }
    for (key, value) in resolved_environment.as_deref().unwrap_or(spec.env) {
        command.env(key, value);
    }
    command.stdout(Stdio::piped()).stderr(Stdio::piped());
    if spec.stdin.is_some() {
        command.stdin(Stdio::piped());
    } else {
        command.stdin(Stdio::null());
    }
    crate::op_interrupt::configure_kill_group(&mut command);
    let cleanup_token = crate::op_interrupt::new_process_cleanup_token();
    command.env(
        crate::op_interrupt::PROCESS_CLEANUP_TOKEN_ENV,
        &cleanup_token,
    );
    crate::op_interrupt::preserve_process_owner_token(&mut command);

    let started = Instant::now();
    let cmd = spec.cmd;
    let mut child = command.spawn().map_err(|error| {
        VmError::Thrown(VmValue::String(arcstr::ArcStr::from(format!(
            "{label}: failed to spawn '{cmd}': {error}"
        ))))
    })?;
    if let Err(error) = crate::op_interrupt::record_current_process_owner_group(child.id()) {
        let _ = crate::op_interrupt::terminate_child_group_with_cleanup_token_report(
            &mut child,
            Some(&cleanup_token),
        );
        return Err(VmError::Runtime(format!(
            "{label}: record process owner group: {error}"
        )));
    }

    if let (Some(payload), Some(mut stdin)) = (spec.stdin, child.stdin.take()) {
        // Children may close stdin early while still producing useful output.
        let _ = stdin.write_all(&payload);
    }

    // Drain pipes on dedicated threads so >64 KB of output never deadlocks
    // the wait loop below (which must keep polling for interrupts instead of
    // blocking in `wait_with_output`).
    let rx_out = child
        .stdout
        .take()
        .map(crate::op_interrupt::spawn_pipe_drain);
    let rx_err = child
        .stderr
        .take()
        .map(crate::op_interrupt::spawn_pipe_drain);

    let child_pid = child.id();
    let wait_end = crate::op_interrupt::wait_child_interruptible_with_cleanup_token(
        &mut child,
        spec.timeout,
        Some(&cleanup_token),
    )
    .map_err(|error| {
        VmError::Thrown(VmValue::String(arcstr::ArcStr::from(format!(
            "{label}: wait failed: {error}"
        ))))
    })?;
    let (status, timed_out, interrupted, killed) = match wait_end {
        crate::op_interrupt::ChildWait::Exited(status) => (status, false, false, false),
        crate::op_interrupt::ChildWait::TimedOut(_) => {
            (std::process::ExitStatus::default(), true, false, true)
        }
        // Interrupted: the reaped status (or a synthetic fallback) is
        // returned so the builtin completes; the VM raises the pending
        // cancellation / deadline error at the next op boundary.
        crate::op_interrupt::ChildWait::Interrupted(status, _) => {
            (status.unwrap_or_default(), false, true, true)
        }
    };

    let stdout = rx_out
        .map(|rx| crate::op_interrupt::drain_captured_pipe(&rx, killed, child_pid))
        .unwrap_or_default();
    let stderr = rx_err
        .map(|rx| crate::op_interrupt::drain_captured_pipe(&rx, killed, child_pid))
        .unwrap_or_default();

    Ok(CapturedRun {
        output: std::process::Output {
            status,
            stdout,
            stderr,
        },
        timed_out,
        interrupted,
        duration_ms: started.elapsed().as_millis() as i64,
    })
}

/// Parsed `exec_opts` / `exec_at_opts` options, ready to populate a
/// [`CapturedSpawn`].
#[derive(Default)]
struct ExecOptions {
    env: Vec<(String, String)>,
    env_clear: bool,
    cwd: Option<String>,
    timeout: Option<Duration>,
}

/// Extract `exec_opts` / `exec_at_opts` options into an [`ExecOptions`].
///
/// `env_mode` mirrors the `process.exec` host op (and the env-clear footgun
/// fix): the default is `"merge"` (overlay `env` keys on the ambient
/// environment, keeping PATH/HOME/etc.); `"replace"` clears that environment
/// first so only the provided keys remain. Under a session environment the ambient
/// base a `"merge"` sees is the resolver's allowlist + grants, not the raw
/// parent env — see [`session_closed_env`].
fn exec_options(label: &str, options: Option<&VmValue>) -> Result<ExecOptions, VmError> {
    let opts = match options {
        None | Some(VmValue::Nil) => return Ok(ExecOptions::default()),
        Some(VmValue::Dict(opts)) => opts.clone(),
        Some(other) => {
            return Err(VmError::Thrown(VmValue::String(arcstr::ArcStr::from(
                format!("{label}: options must be a dict, got {}", other.type_name()),
            ))));
        }
    };
    let env: Vec<(String, String)> = match opts.get("env") {
        Some(VmValue::Dict(env)) => env
            .iter()
            .map(|(k, v)| (k.to_string(), v.display()))
            .collect(),
        None | Some(VmValue::Nil) => Vec::new(),
        Some(other) => {
            return Err(VmError::Thrown(VmValue::String(arcstr::ArcStr::from(
                format!(
                    "{label}: options.env must be a dict, got {}",
                    other.type_name()
                ),
            ))));
        }
    };
    let env_clear = match opts.get("env_mode").map(|v| v.display()).as_deref() {
        None | Some("merge") => false,
        Some("replace") => true,
        Some(other) => {
            return Err(VmError::Thrown(VmValue::String(arcstr::ArcStr::from(
                format!(
                    "{label}: options.env_mode must be \"merge\" or \"replace\", got {other:?}"
                ),
            ))));
        }
    };
    let cwd = opts
        .get("cwd")
        .map(|v| v.display())
        .filter(|s| !s.is_empty());
    // Accept both `timeout` and `timeout_ms` (millis), matching the
    // `process.exec` host op's tolerance.
    let timeout = opts
        .get("timeout")
        .or_else(|| opts.get("timeout_ms"))
        .and_then(|v| v.as_int())
        .filter(|n| *n > 0)
        .map(|n| Duration::from_millis(n as u64));
    Ok(ExecOptions {
        env,
        env_clear,
        cwd,
        timeout,
    })
}

/// Build the `exec`-shaped result dict (`stdout`/`stderr`/`status`/`success`)
/// and additionally surface `timed_out` so options-form callers can detect a
/// timeout kill without inspecting the exit status.
fn captured_run_to_value(run: &CapturedRun) -> VmValue {
    let status = if run.timed_out || run.interrupted {
        -1
    } else {
        run.output.status.code().unwrap_or(-1) as i64
    };
    let success = !run.timed_out && !run.interrupted && run.output.status.success();
    let mut result = BTreeMap::new();
    result.put_str(
        "stdout",
        String::from_utf8_lossy(&run.output.stdout).as_ref(),
    );
    result.put_str(
        "stderr",
        String::from_utf8_lossy(&run.output.stderr).as_ref(),
    );
    result.insert("status".to_string(), VmValue::Int(status));
    result.insert("success".to_string(), VmValue::Bool(success));
    result.insert("timed_out".to_string(), VmValue::Bool(run.timed_out));
    result.insert("duration_ms".to_string(), VmValue::Int(run.duration_ms));
    VmValue::dict(result)
}

#[harn_builtin(
    exposure = "runtime_internal",
    effects = [],
    sig = "exec_opts(command: list, options: dict?) -> dict",
    category = "process"
)]
fn exec_opts_impl(args: &[VmValue], _out: &mut String) -> Result<VmValue, VmError> {
    let command = exec_opts_command("exec_opts", args.first())?;
    let opts = exec_options("exec_opts", args.get(1))?;
    let run = run_captured_spawn(CapturedSpawn {
        label: "exec_opts",
        cmd: &command[0],
        args: &command[1..],
        cwd: opts.cwd.as_deref(),
        env: &opts.env,
        env_clear: opts.env_clear,
        stdin: None,
        timeout: opts.timeout,
    })?;
    Ok(captured_run_to_value(&run))
}

#[harn_builtin(
    exposure = "runtime_internal",
    effects = [],
    sig = "exec_at_opts(dir: string, command: list, options: dict?) -> dict",
    category = "process"
)]
fn exec_at_opts_impl(args: &[VmValue], _out: &mut String) -> Result<VmValue, VmError> {
    let dir = match args.first() {
        Some(value) if !value.display().is_empty() => value.display(),
        _ => {
            return Err(VmError::Thrown(VmValue::String(arcstr::ArcStr::from(
                "exec_at_opts: directory is required",
            ))));
        }
    };
    let command = exec_opts_command("exec_at_opts", args.get(1))?;
    let opts = exec_options("exec_at_opts", args.get(2))?;
    // The positional `dir` argument is the working directory; an explicit
    // `options.cwd` (rare) overrides it so callers retain full control.
    let resolved_cwd = opts.cwd.unwrap_or(dir);
    let run = run_captured_spawn(CapturedSpawn {
        label: "exec_at_opts",
        cmd: &command[0],
        args: &command[1..],
        cwd: Some(resolved_cwd.as_str()),
        env: &opts.env,
        env_clear: opts.env_clear,
        stdin: None,
        timeout: opts.timeout,
    })?;
    Ok(captured_run_to_value(&run))
}

/// Validate the `command` argument shared by `exec_opts`/`exec_at_opts`: a
/// non-empty list whose first element is a non-empty program name.
fn exec_opts_command(label: &str, value: Option<&VmValue>) -> Result<Vec<String>, VmError> {
    let items = match value {
        Some(VmValue::List(items)) => items,
        _ => {
            return Err(VmError::Thrown(VmValue::String(arcstr::ArcStr::from(
                format!("{label}: command must be a non-empty list of strings"),
            ))));
        }
    };
    let command: Vec<String> = items.iter().map(|v| v.display()).collect();
    if command.is_empty() || command[0].is_empty() {
        return Err(VmError::Thrown(VmValue::String(arcstr::ArcStr::from(
            format!("{label}: command must be a non-empty list of strings"),
        ))));
    }
    Ok(command)
}

/// Find the project root by walking up from a base directory looking for
/// `harn.toml`, via the shared `harn-modules` walk so the in-VM resolver agrees
/// with the CLI and LSP on where a project starts.
pub fn find_project_root(base: &std::path::Path) -> Option<std::path::PathBuf> {
    harn_modules::manifest_walk::find_project_root(base)
}

/// Register builtins that depend on source directory context.
pub(crate) fn register_path_builtins(vm: &mut Vm) {
    for def in PATH_BUILTINS {
        vm.register_builtin_def(def);
    }
}

#[harn_builtin(
    exposure = "runtime_internal",
    effects = [],
    sig = "source_dir(...args: any) -> string", category = "process"
)]
fn source_dir_impl(_args: &[VmValue], _out: &mut String) -> Result<VmValue, VmError> {
    let dir = VM_SOURCE_DIR.with(|sd| sd.borrow().clone());
    match dir {
        Some(d) => Ok(VmValue::String(arcstr::ArcStr::from(
            d.to_string_lossy().into_owned(),
        ))),
        None => {
            let cwd = std::env::current_dir()
                .map(|p| p.to_string_lossy().into_owned())
                .unwrap_or_default();
            Ok(VmValue::String(arcstr::ArcStr::from(cwd)))
        }
    }
}

#[harn_builtin(
    exposure = "runtime_internal",
    effects = [],
    sig = "project_root() -> string?", category = "process"
)]
fn project_root_impl(_args: &[VmValue], _out: &mut String) -> Result<VmValue, VmError> {
    if let Some(root) = project_root_path() {
        return Ok(VmValue::String(arcstr::ArcStr::from(
            root.to_string_lossy().as_ref(),
        )));
    }
    let base = current_execution_context()
        .and_then(|context| context.cwd.map(PathBuf::from))
        .or_else(|| VM_SOURCE_DIR.with(|sd| sd.borrow().clone()))
        .or_else(|| std::env::current_dir().ok())
        .unwrap_or_else(|| PathBuf::from("."));
    match find_project_root(&base) {
        Some(root) => Ok(VmValue::String(arcstr::ArcStr::from(
            root.to_string_lossy().into_owned(),
        ))),
        None => Ok(VmValue::Nil),
    }
}

const PATH_BUILTINS: &[&VmBuiltinDef] = &[&SOURCE_DIR_IMPL_DEF, &PROJECT_ROOT_IMPL_DEF];

fn vm_output_to_value(output: std::process::Output) -> VmValue {
    let mut result = BTreeMap::new();
    result.put_str("stdout", String::from_utf8_lossy(&output.stdout).as_ref());
    result.put_str("stderr", String::from_utf8_lossy(&output.stderr).as_ref());
    result.insert(
        "status".to_string(),
        VmValue::Int(output.status.code().unwrap_or(-1) as i64),
    );
    result.insert(
        "success".to_string(),
        VmValue::Bool(output.status.success()),
    );
    VmValue::dict(result)
}

fn exec_command(
    dir: Option<&str>,
    cmd: &str,
    args: &[String],
) -> Result<std::process::Output, VmError> {
    let config = process_command_config(dir)?;
    crate::stdlib::sandbox::command_output(cmd, args, &config)
        .map_err(|error| prefix_process_error(error, "exec"))
}

fn exec_shell_args(
    dir: Option<&str>,
    shell: &str,
    args: &[String],
) -> Result<std::process::Output, VmError> {
    let config = process_command_config(dir)?;
    crate::stdlib::sandbox::command_output(shell, args, &config)
        .map_err(|error| prefix_process_error(error, "shell"))
}

fn process_command_config(
    dir: Option<&str>,
) -> Result<crate::stdlib::sandbox::ProcessCommandConfig, VmError> {
    let mut config = crate::stdlib::sandbox::ProcessCommandConfig::default();
    if let Some(dir) = dir {
        let resolved = resolve_command_dir(dir);
        crate::stdlib::sandbox::enforce_process_cwd(&resolved)?;
        config.cwd = Some(child_process_cwd(resolved));
    } else {
        config.cwd = Some(child_process_cwd(inherited_process_cwd()?));
        if let Some(context) = current_execution_context() {
            if !context.env.is_empty() {
                config.env.extend(context.env);
            }
        }
    }
    config.env.extend(runtime_child_env_overlay());
    // `iter().cloned()`, not `drain(..)`: `Drain`'s destructor removes the
    // range even when the iterator is never consumed, so draining here would
    // silently empty `config.env` on the non-session path.
    if let Some(env) = session_closed_env(config.env.iter().cloned())? {
        config.env = env;
        config.closed_env = true;
    }
    Ok(config)
}

/// The single place a live session environment becomes a child environment
/// when the spawn target is not yet known (or is irrelevant).
///
/// Returns `None` when no session environment governs this session — the legacy path, where
/// children inherit the parent environment and `overlay` is layered on top.
/// Returns `Some(env)` when a session environment is active: `resolve_env` composes the
/// allowlisted subset of the parent env plus the policy's *session-scoped*
/// granted exposure, and `overlay` (worktree paths, `HARN_REPLAY`,
/// caller-supplied `env`, ...) wins over that base. Command-bound grants are
/// not included; use [`session_closed_env_for_command`] at a spawn seam that
/// knows the executable. The caller must hand the result to the child with the
/// inherited environment CLEARED — a closed env is only closed if nothing
/// leaks in behind it. An isolated policy contributes no grants, so its child
/// sees the allowlist alone.
///
/// Every spawn seam that knows its executable must route through
/// [`session_closed_env_for_command`]. `resolve_env` / `resolve_env_for_command`
/// are the single environment builders, and a seam that skips them silently
/// reopens the credential boundary the policy exists to close (harn#5011).
pub(crate) fn session_closed_env(
    overlay: impl Iterator<Item = (String, String)>,
) -> Result<Option<Vec<(String, String)>>, VmError> {
    let Some(mut env) = session_env()? else {
        return Ok(None);
    };
    env.extend(overlay);
    Ok(Some(env.into_iter().collect()))
}

/// Close a child environment for one spawn of `program`.
///
/// Like [`session_closed_env`], but also admits grants whose `for_command`
/// matches the executable basename (harn#5549).
pub(crate) fn session_closed_env_for_command(
    program: &str,
    overlay: impl Iterator<Item = (String, String)>,
) -> Result<Option<Vec<(String, String)>>, VmError> {
    let Some(mut env) = session_env_for_command(program)? else {
        return Ok(None);
    };
    env.extend(overlay);
    Ok(Some(env.into_iter().collect()))
}

/// The current session's whole effective environment, or `None` on the legacy
/// non-session path. The base [`session_closed_env`] layers a caller overlay onto.
/// Session-scoped grants only — command-bound exposures are invisible here.
pub(crate) fn session_env() -> Result<Option<BTreeMap<String, String>>, VmError> {
    session_env_with(
        |grant| grant.for_command().is_none(),
        |environment, lookup| {
            crate::security::resolve_env(environment, lookup, &resolve_grant_secret)
        },
    )
}

/// The environment a spawn of `program` should see under the live session
/// policy: session-scoped grants plus any `for_command` binding that matches.
pub(crate) fn session_env_for_command(
    program: &str,
) -> Result<Option<BTreeMap<String, String>>, VmError> {
    let basename = crate::security::command_basename(program).to_string();
    session_env_with(
        move |grant| match grant.for_command() {
            None => true,
            Some(expected) => expected == basename,
        },
        |environment, lookup| {
            crate::security::resolve_env_for_command(
                environment,
                program,
                lookup,
                &resolve_grant_secret,
            )
        },
    )
}

fn session_env_with(
    grant_owns_key: impl Fn(&crate::security::SessionGrant) -> bool,
    resolve: impl FnOnce(
        &crate::security::SessionEnvironment,
        &dyn Fn(&str) -> Option<String>,
    )
        -> Result<BTreeMap<String, String>, crate::security::EnvironmentPolicyError>,
) -> Result<Option<BTreeMap<String, String>>, VmError> {
    let Some(environment) = current_session_environment() else {
        return Ok(None);
    };
    let workspace_defaults = workspace_env_defaults();
    let mut env =
        resolve(&environment, &session_env_lookup(&workspace_defaults)).map_err(grant_env_error)?;
    // Workspace defaults overwrite the allowlist (so toolchain caches stay
    // workspace-local) but never overwrite a grant that applies to this view.
    for (key, value) in workspace_defaults {
        let grant_owns = environment
            .grants()
            .iter()
            .any(|grant| grant.exposed_env_var() == Some(key.as_str()) && grant_owns_key(grant));
        if !grant_owns {
            env.insert(key, value);
        }
    }
    Ok(Some(env))
}

/// The session-governed value of one environment variable.
///
/// This is the in-process counterpart of [`session_closed_env`], and it is the
/// read every *credential* consumer inside harn's own process must use. Reading
/// `std::env::var` for a provider key instead would make an isolated session
/// isolated only for its children while harn itself still saw the launcher's
/// key, and would leave a granted policy unable to use the very credential it was granted
/// (harn#4992). `security::lookup_env` gives the same answer `resolve_env` puts
/// in the map, so the in-process and subprocess views cannot drift.
///
/// With no session environment installed this is exactly `std::env::var(name).ok()` — the
/// legacy path, unchanged. Folding that fallback in here rather than at each
/// call site means a caller cannot accidentally keep reading the raw
/// environment when a profile *is* active.
pub(crate) fn session_env_var(name: &str) -> Result<Option<String>, VmError> {
    let Some(environment) = current_session_environment() else {
        return Ok(std::env::var(name).ok());
    };
    let workspace_defaults = workspace_env_defaults();
    let is_grant_target = environment
        .grants()
        .iter()
        .any(|grant| grant.exposed_env_var() == Some(name));
    if !is_grant_target {
        if let Some(value) = workspace_defaults.get(name) {
            return Ok(Some(value.clone()));
        }
    }
    let resolved = crate::security::lookup_env(
        &environment,
        name,
        &session_env_lookup(&workspace_defaults),
        &resolve_grant_secret,
    )
    .map_err(grant_env_error)?;
    Ok(resolved)
}

/// Best-effort adapter for configuration paths whose existing API is
/// infallible. Execution paths that can surface a policy error should call
/// [`session_env_var`] directly.
pub(crate) fn session_env_value(name: &str) -> Option<String> {
    if current_session_environment().is_none() {
        return crate::test_env::env_var_seamed(name);
    }
    session_env_var(name).ok().flatten()
}

/// Sandbox-preset environment defaults for the active workspace. These are
/// process-shaping facts set by the run's own policy, never launcher
/// credentials. They override the launch snapshot, while an explicit grant
/// targeting the same name remains the highest-precedence value.
fn workspace_env_defaults() -> BTreeMap<String, String> {
    crate::process_sandbox::active_workspace_process_env()
        .into_iter()
        .collect()
}

/// The session-environment reader resolve against: the
/// workspace preset first, then the real process environment.
fn session_env_lookup(
    workspace_defaults: &BTreeMap<String, String>,
) -> impl Fn(&str) -> Option<String> + '_ {
    |name: &str| {
        workspace_defaults
            .get(name)
            .cloned()
            .or_else(|| std::env::var(name).ok())
    }
}

fn grant_env_error(error: crate::security::EnvironmentPolicyError) -> VmError {
    VmError::Thrown(VmValue::String(arcstr::ArcStr::from(format!(
        "session grant env resolution failed: {error}"
    ))))
}

/// Resolve a `secret_store` grant pointer to its value through the crate's
/// configured secret chain. Env-snapshot grants never reach this — their value
/// was captured at launch — so this only runs for a granted policy that exposes a
/// `secret_store` grant to the process env. Any resolution failure yields `None`,
/// which surfaces as a loud `MissingSecret` at the spawn boundary rather than a
/// silently-empty credential.
fn resolve_grant_secret(account: &str, key: &str) -> Option<String> {
    let reference = format!("{}{}/{}", crate::secrets::SECRET_REF_SCHEME, account, key);
    crate::secrets::resolve_secret_ref_to_string(&reference)
        .ok()
        .flatten()
}

fn prefix_process_error(error: VmError, prefix: &str) -> VmError {
    match error {
        VmError::Thrown(VmValue::String(message)) => VmError::Thrown(VmValue::String(
            arcstr::ArcStr::from(format!("{prefix} failed: {message}")),
        )),
        VmError::Thrown(VmValue::Dict(fields))
            if matches!(
                fields.get("error"),
                Some(VmValue::String(family)) if family.as_str() == "io_error"
            ) =>
        {
            let mut prefixed = (*fields).clone();
            if let Some(VmValue::String(message)) = fields.get("message") {
                prefixed.put_str("message", format!("{prefix} failed: {message}"));
            }
            VmError::Thrown(VmValue::dict(prefixed))
        }
        other => other,
    }
}

fn resolve_command_dir(dir: &str) -> PathBuf {
    let candidate = PathBuf::from(dir);
    if candidate.is_absolute() {
        return candidate;
    }
    if let Some(cwd) = current_execution_context().and_then(|context| context.cwd) {
        return PathBuf::from(cwd).join(candidate);
    }
    if let Some(source_dir) = VM_SOURCE_DIR.with(|sd| sd.borrow().clone()) {
        return source_dir.join(candidate);
    }
    candidate
}

#[cfg(test)]
#[path = "process_tests.rs"]
mod tests;