From a34c41ec5cd74f392782a7d843b80ce00ffc4d73 Mon Sep 17 00:00:00 2001 From: factory-ain3sh Date: Mon, 10 Aug 2026 00:25:21 -0700 Subject: [PATCH 1/3] test(macos): fold the last manual Seatbelt spot-checks into the CI script "Real hardware" stopped being a meaningful distinction when the macos-runtime job started running this script on macos-latest: the runner is real macOS with real sandbox-exec and mount_nfs. The two remaining manual items were automation debt, not hardware requirements. Two new legs in macos-nfs-git-validation.sh: a session homed and based under directories with spaces and a double quote in their names must mount and run (every parameterized Seatbelt path exercised; a regression back to profile string interpolation fails), and vfs run must exit 127 for a missing command and 126 for a present but non-executable one, matching the Linux run path and the reserved-exit-status contract. The manual macOS list in TESTING.md and the AGENTS.md gotcha shrink to the one honest gap: shell suites other than the remote pair have no macOS runtime coverage until made platform-aware the same way. Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com> --- AGENTS.md | 12 +-- docs/TESTING.md | 22 +++-- .../validation/macos-nfs-git-validation.sh | 82 +++++++++++++++++++ 3 files changed, 101 insertions(+), 15 deletions(-) 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/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" From 731b45c92ddfc7b0de2fd2fda762a03b00726af5 Mon Sep 17 00:00:00 2001 From: factory-ain3sh Date: Mon, 10 Aug 2026 00:42:34 -0700 Subject: [PATCH 2/3] fix(darwin): honor the reserved 127/126 exit statuses for bad run commands MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The new CI exit-parity leg caught a real contract violation on its first run: vfs run of a missing command exited 71 on macOS. The sandbox wrapper always spawns because /usr/bin/sandbox-exec is a pinned system binary, so spawn_error_exit_code never fired; sandbox-exec itself failed to exec the target and reported EX_OSERR, which passed through as the session's exit status. Linux never had the problem because it execs the target directly and maps the io error. The darwin run path now resolves the target the way sandbox-exec's execvp will — bare names search PATH (read through the config edge), slashed paths resolve against the child's working directory, an empty PATH entry means the working directory — and exits with the reserved status before mounting a child: 127 not found, 126 present but not executable. Both the owner and joiner paths preflight; the owner unmounts before exiting so no stale mount is left behind. Unit tests cover the resolution table; the validation script leg asserts the end-to-end statuses in CI. Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com> --- CHANGELOG.md | 14 +++++ crates/vfs-cli/src/cmd/run/darwin.rs | 86 +++++++++++++++++++++++++++- crates/vfs-cli/src/cmd/run/tests.rs | 57 ++++++++++++++++++ crates/vfs-cli/src/config.rs | 7 +++ 4 files changed, 162 insertions(+), 2 deletions(-) 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..c168b099 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, &'static str) = (127, "command not found"); + const NOT_EXECUTABLE: (i32, &'static 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)?; From 9172d462bf3a2bce521e9987dedf53370a014154 Mon Sep 17 00:00:00 2001 From: factory-ain3sh Date: Mon, 10 Aug 2026 00:50:21 -0700 Subject: [PATCH 3/3] fix(darwin): drop redundant 'static from the preflight consts The macos-latest clippy wall denies redundant_static_lifetimes, and the darwin module only compiles there. Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com> --- crates/vfs-cli/src/cmd/run/darwin.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/crates/vfs-cli/src/cmd/run/darwin.rs b/crates/vfs-cli/src/cmd/run/darwin.rs index c168b099..131aafe0 100644 --- a/crates/vfs-cli/src/cmd/run/darwin.rs +++ b/crates/vfs-cli/src/cmd/run/darwin.rs @@ -311,8 +311,8 @@ pub(super) fn preflight_exec_exit_code( .unwrap_or(false) } - const NOT_FOUND: (i32, &'static str) = (127, "command not found"); - const NOT_EXECUTABLE: (i32, &'static str) = (126, "not executable"); + 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.