diff --git a/crates/agentflare-shim/src/main.rs b/crates/agentflare-shim/src/main.rs
index 5094df05..92df7e07 100644
--- a/crates/agentflare-shim/src/main.rs
+++ b/crates/agentflare-shim/src/main.rs
@@ -109,3 +109,58 @@ fn main() {
         Err(_) => run_real(&tool, filtered_path.as_ref(), &args),
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::fs;
+
+    #[test]
+    fn finds_marker_in_start_dir() {
+        let tmp = std::env::temp_dir().join(format!("agentflare-shim-test-{}", std::process::id()));
+        fs::create_dir_all(&tmp).unwrap();
+        fs::write(tmp.join(PROJECT_MARKER), "").unwrap();
+        assert!(in_scoped_project(&tmp, None));
+        let _ = fs::remove_dir_all(&tmp);
+    }
+
+    #[test]
+    fn finds_marker_in_an_ancestor_dir() {
+        let tmp =
+            std::env::temp_dir().join(format!("agentflare-shim-test-anc-{}", std::process::id()));
+        let sub = tmp.join("a").join("b");
+        fs::create_dir_all(&sub).unwrap();
+        fs::write(tmp.join(PROJECT_MARKER), "").unwrap();
+        assert!(in_scoped_project(&sub, None));
+        let _ = fs::remove_dir_all(&tmp);
+    }
+
+    #[test]
+    fn stops_at_home_without_treating_agentflares_own_dir_as_a_project_marker() {
+        // ~/.agentflare is agentflare's own app-data dir, not a project
+        // marker -- walking past `home` (inclusive of home itself) must
+        // never false-positive on it. Regression for the bug the doc
+        // comment on `in_scoped_project` calls out.
+        let tmp =
+            std::env::temp_dir().join(format!("agentflare-shim-test-home-{}", std::process::id()));
+        let sub = tmp.join("sub");
+        fs::create_dir_all(&sub).unwrap();
+        fs::write(tmp.join(PROJECT_MARKER), "").unwrap();
+        assert!(!in_scoped_project(&sub, Some(&tmp)));
+        let _ = fs::remove_dir_all(&tmp);
+    }
+
+    #[test]
+    fn no_marker_anywhere_is_not_scoped() {
+        // Bound the walk-up with an explicit synthetic `home` one level
+        // above `tmp`, rather than `None` -- an unbounded walk from a real
+        // temp dir keeps climbing past this test's control (e.g. up into
+        // the real machine's actual `~/.agentflare`, giving a false pass/fail
+        // that has nothing to do with the logic under test).
+        let tmp =
+            std::env::temp_dir().join(format!("agentflare-shim-test-none-{}", std::process::id()));
+        fs::create_dir_all(&tmp).unwrap();
+        assert!(!in_scoped_project(&tmp, tmp.parent()));
+        let _ = fs::remove_dir_all(&tmp);
+    }
+}