refactor(pi): PathResolver::new takes a required home argument

CHANGELOG.md

@@ -31,6 +31,27 @@ cache the same queries run ~4.7× faster (e.g. `length` 966 ms →
     drivers so the zero-file rule lives once.
   - The emscripten (playground) build keeps the sequential engine —
     no threads there.
+## `toolpath-pi`: the caller supplies the home directory — 2026-08-14
+
+- **`toolpath-pi`** (0.7.0): breaking. `PathResolver::new(home)` takes
+  the home directory as a required argument. The crate reads no
+  environment variable; it keeps the layout knowledge
+  (`<home>/.pi/agent/sessions`) and the caller owns "what is home".
+  `PiConvo::new(home)` takes the same argument.
+
+  Removed: the `Default` impls on `PathResolver` and `PiConvo`;
+  `PathResolver::with_home`. `with_sessions_dir` stays as the full
+  override, and it beats the home argument.
+
+  Behavior change: the resolver does not consult the current working
+  directory. It resolves the sessions directory from the home argument,
+  or from `with_sessions_dir`. The `./.pi/agent/sessions` fallback is
+  deleted.
+- **`path-cli`** (unreleased): `providers::pi_resolver` returns
+  `Option<PathResolver>`. `None` means the configuration carries no home
+  directory, so Pi is out of reach: the harness bundle omits it, and a
+  command that targets Pi reports "cannot determine the home
+  directory".
 ## `toolpath-cursor`: the caller supplies the home directory — 2026-08-14
 
 - **`toolpath-cursor`** (0.3.0): breaking. `PathResolver::new(home)`

Cargo.toml

@@ -36,7 +36,7 @@ toolpath-cursor = { version = "0.3.0", path = "crates/toolpath-cursor" }
 toolpath-github = { version = "0.6.0", path = "crates/toolpath-github" }
 toolpath-dot = { version = "0.5.0", path = "crates/toolpath-dot" }
 toolpath-md = { version = "0.7.0", path = "crates/toolpath-md" }
-toolpath-pi = { version = "0.6.1", path = "crates/toolpath-pi" }
+toolpath-pi = { version = "0.7.0", path = "crates/toolpath-pi" }
 path-cli = { version = "0.17.0", path = "crates/path-cli" }
 pathbase-client = { version = "0.2.0", path = "crates/pathbase-client" }
 

crates/path-cli/src/cmd_export.rs

@@ -1064,7 +1064,7 @@ fn write_into_pi_project(
     cwd: &str,
     config: &Config,
 ) -> Result<()> {
-    let resolver = providers::pi_resolver(config);
+    let resolver = providers::require_pi_resolver(config)?;
     let project_dir = resolver.project_dir(cwd);
     std::fs::create_dir_all(&project_dir)
         .with_context(|| format!("create {}", project_dir.display()))?;
@@ -2588,7 +2588,7 @@ mod tests {
         .expect("export pi");
 
         let canon_project = std::fs::canonicalize(&project_dir).unwrap();
-        let resolver = PathResolver::new().with_home(&fake_home);
+        let resolver = PathResolver::new(&fake_home);
         let project_dir_path = resolver.project_dir(canon_project.to_str().unwrap());
         let expected = project_dir_path.join(format!("{}.jsonl", session_uuid));
         assert!(expected.exists(), "expected JSONL at {:?}", expected);

crates/path-cli/src/cmd_import.rs

@@ -1310,7 +1310,7 @@ fn derive_pi(
     base: Option<PathBuf>,
     config: &Config,
 ) -> Result<Vec<DerivedDoc>> {
-    let mut resolver = providers::pi_resolver(config);
+    let mut resolver = providers::require_pi_resolver(config)?;
     if let Some(path) = base {
         resolver = resolver.with_sessions_dir(&path);
     }

crates/path-cli/src/cmd_list.rs

@@ -999,7 +999,11 @@ fn run_pi(
     fmt: ListFormat,
     config: &Config,
 ) -> Result<()> {
-    let manager = providers::pi_convo(config, base.as_deref());
+    let mut resolver = providers::require_pi_resolver(config)?;
+    if let Some(path) = base {
+        resolver = resolver.with_sessions_dir(&path);
+    }
+    let manager = toolpath_pi::PiConvo::with_resolver(resolver);
 
     match (project, fmt) {
         (None, ListFormat::Tsv) => list_pi_sessions_all(&manager, ListFormat::Tsv),
@@ -1416,7 +1420,7 @@ mod tests {
         )
         .unwrap();
 
-        let resolver = toolpath_pi::PathResolver::new().with_sessions_dir(&sessions_dir);
+        let resolver = toolpath_pi::PathResolver::new(temp.path());
         let manager = toolpath_pi::PiConvo::with_resolver(resolver);
         (temp, manager)
     }
@@ -1441,7 +1445,7 @@ mod tests {
         let sessions_dir = temp.path().join(".pi/agent/sessions");
         std::fs::create_dir_all(&sessions_dir).unwrap();
 
-        let resolver = toolpath_pi::PathResolver::new().with_sessions_dir(&sessions_dir);
+        let resolver = toolpath_pi::PathResolver::new(temp.path());
         let manager = toolpath_pi::PiConvo::with_resolver(resolver);
 
         let result = list_pi_projects(&manager, ListFormat::Pretty);

crates/path-cli/src/cmd_show.rs

@@ -199,7 +199,11 @@ fn derive_one(source: ShowSource, config: &Config) -> Result<toolpath::v1::Path>
             session,
             base,
         } => {
-            let manager = providers::pi_convo(config, base.as_deref());
+            let mut resolver = providers::require_pi_resolver(config)?;
+            if let Some(p) = base {
+                resolver = resolver.with_sessions_dir(&p);
+            }
+            let manager = toolpath_pi::PiConvo::with_resolver(resolver);
             let s = manager
                 .read_session(&project, &session)
                 .map_err(|e| anyhow::anyhow!("{}", e))?;

crates/path-cli/src/derive.rs

@@ -341,7 +341,7 @@ pub(crate) fn derive_pi_session(
     session: &str,
     base: Option<PathBuf>,
 ) -> Result<DerivedDoc> {
-    let mut resolver = providers::pi_resolver(config);
+    let mut resolver = providers::require_pi_resolver(config)?;
     if let Some(path) = base {
         resolver = resolver.with_sessions_dir(&path);
     }

crates/path-cli/src/providers.rs

@@ -24,7 +24,6 @@
 use crate::config::Config;
 #[cfg(not(target_os = "emscripten"))]
 use crate::harness::HarnessBundle;
-use std::path::Path;
 
 use anyhow::{Result, anyhow};
 
@@ -132,17 +131,13 @@ pub(crate) fn require_cursor_resolver(config: &Config) -> Result<toolpath_cursor
     cursor_resolver(config).ok_or_else(|| missing_home("Cursor"))
 }
 
-/// `base` replaces the sessions directory: `--base` wins over the
-/// config home.
-pub(crate) fn pi_convo(config: &Config, base: Option<&Path>) -> toolpath_pi::PiConvo {
-    let mut resolver = toolpath_pi::PathResolver::new();
-    if let Some(home) = config.home_dir() {
-        resolver = resolver.with_home(home);
-    }
-    if let Some(dir) = base {
-        resolver = resolver.with_sessions_dir(dir);
-    }
-    toolpath_pi::PiConvo::with_resolver(resolver)
+pub(crate) fn pi_resolver(config: &Config) -> Option<toolpath_pi::PathResolver> {
+    config.home_dir().map(toolpath_pi::PathResolver::new)
+}
+
+/// [`pi_resolver`] for a command that targets Pi.
+pub(crate) fn require_pi_resolver(config: &Config) -> Result<toolpath_pi::PathResolver> {
+    pi_resolver(config).ok_or_else(|| missing_home("Pi"))
 }
 
 /// The production [`HarnessBundle`], every provider built from
@@ -165,7 +160,7 @@ pub(crate) fn harness_bundle(config: &Config) -> HarnessBundle {
         }),
         opencode: opencode_resolver(config).map(toolpath_opencode::OpencodeConvo::with_resolver),
         cursor: cursor_resolver(config).map(toolpath_cursor::CursorConvo::with_resolver),
-        pi: Some(pi_convo(config, None)),
+        pi: pi_resolver(config).map(toolpath_pi::PiConvo::with_resolver),
     }
 }
 
@@ -361,21 +356,6 @@ mod tests {
         );
     }
 
-    #[test]
-    fn pi_convo_roots_at_config_home() {
-        let manager = pi_convo(&config_with_home(), None);
-        assert_eq!(
-            manager.resolver().sessions_dir(),
-            PathBuf::from("/home/jailed/.pi/agent/sessions")
-        );
-    }
-
-    #[test]
-    fn pi_convo_base_replaces_the_sessions_dir() {
-        let manager = pi_convo(&config_with_home(), Some(Path::new("/pi/base")));
-        assert_eq!(manager.resolver().sessions_dir(), PathBuf::from("/pi/base"));
-    }
-
     #[test]
     fn harness_bundle_roots_providers_at_config_home() {
         let bundle = harness_bundle(&config_with_home());
@@ -388,4 +368,20 @@ mod tests {
             PathBuf::from("/home/jailed/.pi/agent/sessions")
         );
     }
+
+    #[test]
+    fn pi_resolver_roots_at_config_home() {
+        let resolver = pi_resolver(&config_with_home()).unwrap();
+        assert_eq!(
+            resolver.sessions_dir(),
+            PathBuf::from("/home/jailed/.pi/agent/sessions")
+        );
+    }
+
+    #[test]
+    fn pi_resolver_is_none_without_a_home() {
+        assert!(pi_resolver(&Config::default()).is_none());
+        let err = require_pi_resolver(&Config::default()).unwrap_err();
+        assert!(err.to_string().contains("home directory"));
+    }
 }

crates/toolpath-pi/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "toolpath-pi"
-version = "0.6.1"
+version = "0.7.0"
 edition.workspace = true
 license.workspace = true
 repository = "https://github.com/empathic/toolpath"

crates/toolpath-pi/README.md

@@ -18,7 +18,7 @@ the shared derivation in [`toolpath_convo::derive_path`].
 ```rust,no_run
 use toolpath_pi::PiConvo;
 
-let manager = PiConvo::new();
+let manager = PiConvo::new("/Users/alex");
 let session = manager
     .most_recent_session("/Users/alex/project")
     .unwrap()
@@ -36,7 +36,7 @@ user-prompt text). The last field is what makes the listing useful for
 ```rust,no_run
 use toolpath_pi::PiConvo;
 
-let manager = PiConvo::new();
+let manager = PiConvo::new("/Users/alex");
 for meta in manager.list_sessions("/Users/alex/project").unwrap() {
     println!(
         "{}: {}",

crates/toolpath-pi/src/io.rs

@@ -255,7 +255,7 @@ mod tests {
     use tempfile::TempDir;
 
     fn resolver_with(sessions_dir: &Path) -> PathResolver {
-        PathResolver::new().with_sessions_dir(sessions_dir)
+        PathResolver::new("/tmp/fake-home").with_sessions_dir(sessions_dir)
     }
 
     #[test]

crates/toolpath-pi/src/lib.rs

@@ -22,16 +22,17 @@ pub use types::{
 use toolpath_convo::ConversationView;
 
 /// High-level interface for reading Pi sessions.
-#[derive(Debug, Clone, Default)]
+#[derive(Debug, Clone)]
 pub struct PiConvo {
     resolver: PathResolver,
 }
 
 impl PiConvo {
-    /// Build a manager with the default resolver (`~/.pi/agent/sessions/`).
-    pub fn new() -> Self {
+    /// Build a manager for `<home>/.pi/agent/sessions/`. The caller
+    /// supplies the home directory.
+    pub fn new(home: impl AsRef<std::path::Path>) -> Self {
         Self {
-            resolver: PathResolver::new(),
+            resolver: PathResolver::new(home),
         }
     }