diff --git a/AGENTS.md b/AGENTS.md index 36d20c72..e393f971 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -231,12 +231,12 @@ Not regressions — deliberate, documented state. Don't "fix" them by accident. invisible until the gate runs somewhere unusual. * **macOS runtime coverage is CI-real but narrower than Linux.** The macos-latest jobs run clippy, the workspace tests, the NFS + Seatbelt - runtime validation script, and both remote-tier suites over the NFS mount - path. The session control socket and the chunk streamer exist only in the - Linux mount owner, so the live-checkpoint and streamer legs never run on a - Mac, and the rest of the shell suite plus the Seatbelt spot-checks in - docs/TESTING.md still need a manual hardware run before a release that - advertises macOS. + runtime validation script (including the quoted-path and 127/126 + exit-parity legs), and both remote-tier suites over the NFS mount path. + The session control socket and the chunk streamer exist only in the Linux + mount owner, so the live-checkpoint and streamer legs never run on a Mac, + and the rest of the shell suite has no macOS coverage until each suite is + made platform-aware like the remote pair. * **NFS `UNSTABLE`+`COMMIT` is deliberately unimplemented.** Every WRITE is `FILE_SYNC`-honest and `NFSPROC3_COMMIT` returns `PROC_UNAVAIL`. Implementing it with imperfect verifier semantics reintroduces the data-loss class diff --git a/CHANGELOG.md b/CHANGELOG.md index 07ee0c90..236a951f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,19 @@ # Changelog +## [Unreleased] + +### Fixed + +- macOS `vfs run` now honors the reserved startup exit statuses for a bad + command: `127` when it is missing and `126` when it is present but not + executable. The sandbox wrapper always spawns (`/usr/bin/sandbox-exec` is + a pinned system binary), so a missing *target* previously surfaced as + sandbox-exec's own `EX_OSERR` exit 71. The run path now resolves the + target execvp-style before spawning and exits with the reserved status, + matching `vfs exec` and the Linux run path. Caught by the new CI + exit-parity leg in `macos-nfs-git-validation.sh`, which also gained a + quoted-profile-path leg; both were previously manual release spot-checks. + ## [1.1.0] - 2026-08-09 - Replayable history, session branching, and the remote tier This release builds one time-travel path from content-addressed storage through diff --git a/crates/vfs-cli/src/cmd/run/darwin.rs b/crates/vfs-cli/src/cmd/run/darwin.rs index 6ff70cb4..131aafe0 100644 --- a/crates/vfs-cli/src/cmd/run/darwin.rs +++ b/crates/vfs-cli/src/cmd/run/darwin.rs @@ -293,6 +293,73 @@ pub(super) fn spawn_error_exit_code(error: &anyhow::Error) -> Option { .and_then(exit_code_for_spawn_error) } +/// Resolve the target command the way sandbox-exec's execvp will, before +/// spawning. The spawn itself always succeeds because sandbox-exec is a +/// pinned system binary; when the *target* is missing or non-executable, +/// sandbox-exec exits EX_OSERR (71), which would violate the reserved +/// 127/126 startup-status contract. Returns the reserved exit code and a +/// message when the command cannot execute. +pub(super) fn preflight_exec_exit_code( + command: &Path, + child_cwd: &Path, +) -> Option<(i32, &'static str)> { + use std::os::unix::fs::PermissionsExt; + + fn executable(path: &Path) -> bool { + path.metadata() + .map(|meta| meta.is_file() && meta.permissions().mode() & 0o111 != 0) + .unwrap_or(false) + } + + const NOT_FOUND: (i32, &str) = (127, "command not found"); + const NOT_EXECUTABLE: (i32, &str) = (126, "not executable"); + + // A command containing a slash is used as a path, resolved against the + // child's working directory; only a bare name searches PATH. + if command.components().count() > 1 { + let target = if command.is_absolute() { + command.to_path_buf() + } else { + child_cwd.join(command) + }; + if executable(&target) { + return None; + } + return Some(if target.exists() { + NOT_EXECUTABLE + } else { + NOT_FOUND + }); + } + + let mut found_non_executable = false; + for dir in std::env::split_paths(&crate::config::host_path_var()) { + // An empty PATH entry means the working directory, per execvp. + let candidate = if dir.as_os_str().is_empty() { + child_cwd.join(command) + } else { + dir.join(command) + }; + if executable(&candidate) { + return None; + } + if candidate.exists() { + found_non_executable = true; + } + } + Some(if found_non_executable { + NOT_EXECUTABLE + } else { + NOT_FOUND + }) +} + +/// An exited wait status carrying `code`, for exits decided without a child. +fn synthesized_exit_status(code: i32) -> std::process::ExitStatus { + use std::os::unix::process::ExitStatusExt; + std::process::ExitStatus::from_raw(code << 8) +} + /// Run the command in a Darwin sandbox. pub async fn run(options: RunOptions) -> Result<()> { let RunOptions { @@ -456,8 +523,19 @@ pub async fn run(options: RunOptions) -> Result<()> { print_welcome_banner(&session, encrypted); let command_display = command.display().to_string(); - let child_command = command_in_mount(&session, command, args); - let status = run_supervised(mount_handle, child_command).await; + let status = match preflight_exec_exit_code(&command, &session.mountpoint) { + Some((code, reason)) => { + eprintln!("Error: Failed to execute: {command_display}: {reason}"); + mount_handle + .unmount() + .await + .map(|()| synthesized_exit_status(code)) + } + None => { + let child_command = command_in_mount(&session, command, args); + run_supervised(mount_handle, child_command).await + } + }; if let Err(e) = std::fs::remove_dir(&session.mountpoint) { eprintln!( "Warning: Failed to clean up mountpoint {}: {}", @@ -709,6 +787,10 @@ async fn run_command_in_mount( args: Vec, ) -> Result { let command_display = command.display().to_string(); + if let Some((code, reason)) = preflight_exec_exit_code(&command, &session.mountpoint) { + eprintln!("Error: Failed to execute: {command_display}: {reason}"); + return Ok(ChildOutcome::Exited(synthesized_exit_status(code))); + } let child_command = command_in_mount(session, command, args); match supervise_command(child_command).await { Ok(outcome) => Ok(outcome), diff --git a/crates/vfs-cli/src/cmd/run/tests.rs b/crates/vfs-cli/src/cmd/run/tests.rs index ef134e4b..2e84c96c 100644 --- a/crates/vfs-cli/src/cmd/run/tests.rs +++ b/crates/vfs-cli/src/cmd/run/tests.rs @@ -673,6 +673,63 @@ mod darwin_spawn_exit_codes { } } +#[cfg(target_os = "macos")] +mod darwin_exec_preflight { + use super::super::darwin::preflight_exec_exit_code; + use std::os::unix::fs::PermissionsExt; + use std::path::Path; + + fn code(command: &Path, cwd: &Path) -> Option { + preflight_exec_exit_code(command, cwd).map(|(code, _)| code) + } + + #[test] + fn missing_absolute_command_is_127() { + let dir = tempfile::tempdir().unwrap(); + assert_eq!( + code(&dir.path().join("does-not-exist"), dir.path()), + Some(127) + ); + } + + #[test] + fn present_non_executable_is_126() { + let dir = tempfile::tempdir().unwrap(); + let target = dir.path().join("not-executable"); + std::fs::write(&target, "#!/bin/sh\n").unwrap(); + std::fs::set_permissions(&target, std::fs::Permissions::from_mode(0o644)).unwrap(); + assert_eq!(code(&target, dir.path()), Some(126)); + } + + #[test] + fn executable_paths_pass() { + let dir = tempfile::tempdir().unwrap(); + assert_eq!(code(Path::new("/bin/sh"), dir.path()), None); + } + + #[test] + fn bare_names_search_path() { + let dir = tempfile::tempdir().unwrap(); + // `sh` resolves through PATH on every runner; a name that cannot + // exist anywhere on PATH is not found. + assert_eq!(code(Path::new("sh"), dir.path()), None); + assert_eq!( + code(Path::new("vfs-preflight-test-missing-cmd"), dir.path()), + Some(127) + ); + } + + #[test] + fn relative_paths_resolve_against_the_child_cwd() { + let dir = tempfile::tempdir().unwrap(); + let target = dir.path().join("tool.sh"); + std::fs::write(&target, "#!/bin/sh\n").unwrap(); + std::fs::set_permissions(&target, std::fs::Permissions::from_mode(0o755)).unwrap(); + assert_eq!(code(Path::new("./tool.sh"), dir.path()), None); + assert_eq!(code(Path::new("./absent.sh"), dir.path()), Some(127)); + } +} + #[cfg(target_os = "linux")] mod skip_mount { use super::super::linux::skip_mount; diff --git a/crates/vfs-cli/src/config.rs b/crates/vfs-cli/src/config.rs index ac5c33dd..037dce14 100644 --- a/crates/vfs-cli/src/config.rs +++ b/crates/vfs-cli/src/config.rs @@ -42,6 +42,13 @@ pub(crate) fn current_shell_path() -> Option { EnvReader::new().string(SHELL_ENV) } +/// PATH as a spawned child inherits it, for execvp-style spawn preflight. +/// The fallback mirrors execvp's behavior when PATH is unset. +#[cfg(target_os = "macos")] +pub(crate) fn host_path_var() -> std::ffi::OsString { + std::env::var_os("PATH").unwrap_or_else(|| std::ffi::OsString::from("/usr/bin:/bin")) +} + pub fn remote_config() -> Option { let reader = EnvReader::new(); let url = reader.string(REMOTE_URL_ENV)?; diff --git a/docs/TESTING.md b/docs/TESTING.md index 32eef6d1..cc271669 100644 --- a/docs/TESTING.md +++ b/docs/TESTING.md @@ -481,12 +481,16 @@ also exercises the `/System/Volumes/Preboot` metadata literal that lets path resolution reach the dyld cryptex root, which used to be a manual spot-check. -What still needs a manual run on real hardware before a release that -advertises macOS: the rest of the shell suite (CI runs only the two remote -suites there), and two Seatbelt spot-checks the suites do not reach — -dynamic profile paths travel as Seatbelt `(param "NAME")` references with -`-D NAME=value` definitions on the `/usr/bin/sandbox-exec` command line, so -confirm a session under a directory with spaces or quotes in its name still -mounts and runs; and `vfs run ` must exit `127` (`126` for -a present but non-executable file), matching `vfs exec` and the Linux run -path. +The former manual Seatbelt spot-checks are legs of this script now, so CI +covers them: a session homed and based under directories with spaces and a +double quote in their names must mount and run (dynamic profile paths +travel as Seatbelt `(param "NAME")` references with `-D NAME=value` +definitions on the `/usr/bin/sandbox-exec` command line, and a regression +back to string interpolation fails here), and `vfs run` must exit `127` for +a missing command and `126` for a present but non-executable one, matching +`vfs exec` and the Linux run path. + +What macOS CI still does not cover: the rest of the shell suite — only the +two remote-tier suites run on macos-latest, so a change touching mount +lifecycle, MCP, or CLI surfaces beyond those suites has no macOS runtime +coverage until its owning suite is made platform-aware the same way. diff --git a/scripts/validation/macos-nfs-git-validation.sh b/scripts/validation/macos-nfs-git-validation.sh index fef54c03..a233b2ed 100755 --- a/scripts/validation/macos-nfs-git-validation.sh +++ b/scripts/validation/macos-nfs-git-validation.sh @@ -27,6 +27,8 @@ RUN_WORK_DIR="" SECRET_DIR="" RUN_SESSION_DENY="" RUN_SESSION_ALLOW="" +RUN_SESSION_MISSING="" +RUN_SESSION_NOEXEC="" usage() { sed -n '2,14p' "$0" | sed 's/^# \{0,1\}//' @@ -128,6 +130,8 @@ cleanup() { safe_rm_secret_dir "$SECRET_DIR" safe_rm_run_session "$RUN_SESSION_DENY" safe_rm_run_session "$RUN_SESSION_ALLOW" + safe_rm_run_session "$RUN_SESSION_MISSING" + safe_rm_run_session "$RUN_SESSION_NOEXEC" elif [[ -n "$WORK_DIR" || -n "$MOUNT_DIR" ]]; then printf 'Kept work directory: %s\n' "$WORK_DIR" >&2 printf 'Kept mount directory: %s\n' "$MOUNT_DIR" >&2 @@ -323,4 +327,82 @@ if [[ "$allow_status" -ne 0 ]] || ! grep -q 'vfs-read-scope-secret' "$REPORT_DIR fi printf 'Read of --allow path succeeded as expected.\n' +# --- seatbelt profile paths with spaces and quotes -------------------------- +# Dynamic profile paths travel as Seatbelt `(param "NAME")` references with +# -D NAME=value definitions on the sandbox-exec command line. Homing the +# session store and the base directory under names containing spaces and a +# double quote exercises every parameterized path; a regression back to +# string interpolation fails to mount or run. + +printf 'Running seatbelt quoted-path checks...\n' + +QUOTE_HOME="$RUN_WORK_DIR/home with \"quote\"" +QUOTE_BASE="$RUN_WORK_DIR/base with \"quote\" dir" +mkdir -p "$QUOTE_HOME" "$QUOTE_BASE" +RUN_SESSION_QUOTES="macos-read-scope-quotes-$$-$(date +%s)" + +set +e +( + cd "$QUOTE_BASE" + HOME="$QUOTE_HOME" \ + XDG_CACHE_HOME="$QUOTE_HOME/.cache" \ + XDG_CONFIG_HOME="$QUOTE_HOME/.config" \ + "$VFS_RESOLVED" run --session "$RUN_SESSION_QUOTES" \ + /bin/sh -c 'printf quoted-path-ok >probe.txt && /bin/cat probe.txt' +) >"$REPORT_DIR/quoted-paths.log" 2>&1 +quotes_status=$? +set -e + +if ! grep -q 'Welcome to Vfs' "$REPORT_DIR/quoted-paths.log"; then + printf 'FAILED: vfs run never reached the sandbox under a quoted path. See %s/quoted-paths.log\n' "$REPORT_DIR" >&2 + exit 1 +fi +if [[ "$quotes_status" -ne 0 ]] || ! grep -q 'quoted-path-ok' "$REPORT_DIR/quoted-paths.log"; then + printf 'FAILED: session under a directory with spaces/quotes did not mount and run (exit %s). See %s/quoted-paths.log\n' "$quotes_status" "$REPORT_DIR" >&2 + exit 1 +fi +printf 'Session under spaced/quoted directories mounted and ran.\n' + +# --- run exit-status parity -------------------------------------------------- +# The reserved startup exit statuses are a daemon contract: 127 for a missing +# command and 126 for a present but non-executable one, matching vfs exec and +# the Linux run path. + +printf 'Running exit-status parity checks...\n' + +RUN_SESSION_MISSING="macos-read-scope-missing-$$-$(date +%s)" +RUN_SESSION_NOEXEC="macos-read-scope-noexec-$$-$(date +%s)" + +set +e +( + cd "$RUN_WORK_DIR" + "$VFS_RESOLVED" run --session "$RUN_SESSION_MISSING" \ + /nonexistent-vfs-validation-command +) >"$REPORT_DIR/exit-missing.log" 2>&1 +missing_status=$? +set -e + +if [[ "$missing_status" -ne 127 ]]; then + printf 'FAILED: run of a missing command exited %s, expected 127. See %s/exit-missing.log\n' "$missing_status" "$REPORT_DIR" >&2 + exit 1 +fi + +printf '#!/bin/sh\n' >"$RUN_WORK_DIR/not-executable" +chmod 0644 "$RUN_WORK_DIR/not-executable" + +set +e +( + cd "$RUN_WORK_DIR" + "$VFS_RESOLVED" run --session "$RUN_SESSION_NOEXEC" \ + "$RUN_WORK_DIR/not-executable" +) >"$REPORT_DIR/exit-noexec.log" 2>&1 +noexec_status=$? +set -e + +if [[ "$noexec_status" -ne 126 ]]; then + printf 'FAILED: run of a non-executable file exited %s, expected 126. See %s/exit-noexec.log\n' "$noexec_status" "$REPORT_DIR" >&2 + exit 1 +fi +printf 'Exit-status parity held (127 missing, 126 non-executable).\n' + printf 'macOS NFS git + run read-scoping validation passed. Logs: %s\n' "$REPORT_DIR"