Function confine_path 

pub fn confine_path(
    root: &Path,
    candidate: &Path,
) -> Result<PathBuf, PathEscape>

Confine candidate to within root, returning the resolved absolute path or PathEscape if it lands outside.

This is the filesystem-jail primitive the flow-adapter-fs adapter calls on every read/write/edit/glob/grep so the on-device coding agent can only touch files inside the user-chosen workspace root.

Resolution rules:

• candidate may be absolute or relative; relative paths resolve against root.
• The root must exist and is canonicalized (symlinks resolved) so the prefix check compares real paths.
• For the candidate we canonicalize the longest existing ancestor and re-append the not-yet-existing tail (so writing a new file under the root is allowed while still resolving symlinks on the existing portion - this blocks a symlinked parent dir that points outside the root).
• .. components are normalized away before resolution so plain traversal (../../etc/passwd) is caught even when intermediate dirs don’t exist.