Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 6 additions & 6 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
14 changes: 14 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down
86 changes: 84 additions & 2 deletions crates/vfs-cli/src/cmd/run/darwin.rs
Original file line number Diff line number Diff line change
Expand Up @@ -293,6 +293,73 @@ pub(super) fn spawn_error_exit_code(error: &anyhow::Error) -> Option<i32> {
.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 {
Expand Down Expand Up @@ -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 {}: {}",
Expand Down Expand Up @@ -709,6 +787,10 @@ async fn run_command_in_mount(
args: Vec<String>,
) -> Result<ChildOutcome> {
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),
Expand Down
57 changes: 57 additions & 0 deletions crates/vfs-cli/src/cmd/run/tests.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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<i32> {
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;
Expand Down
7 changes: 7 additions & 0 deletions crates/vfs-cli/src/config.rs
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,13 @@ pub(crate) fn current_shell_path() -> Option<String> {
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<RemoteConfig> {
let reader = EnvReader::new();
let url = reader.string(REMOTE_URL_ENV)?;
Expand Down
22 changes: 13 additions & 9 deletions docs/TESTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 <missing-command>` 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.
82 changes: 82 additions & 0 deletions scripts/validation/macos-nfs-git-validation.sh
Original file line number Diff line number Diff line change
Expand Up @@ -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\}//'
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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"
Loading