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

CHANGELOG.md

@@ -31,6 +31,39 @@ 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-cursor`: the caller supplies the home directory — 2026-08-14
+
+- **`toolpath-cursor`** (0.3.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>/.cursor`
+  and the per-platform Electron user-data root) and the caller owns
+  "what is home". `CursorConvo::new(home)` and `CursorIO::new(home)`
+  take the same argument.
+
+  Removed: the `Default` impls on `PathResolver`, `CursorIO`, and
+  `CursorConvo`; `PathResolver::with_home`; the `NoHomeDirectory` error
+  variant. `with_anysphere_dir` and `with_user_data_dir` stay as the
+  full overrides.
+
+  `PathResolver::with_appdata(appdata)` sets the Windows
+  roaming-application-data root: the Windows default user-data
+  directory is `<appdata>/Cursor`. Every other platform ignores the
+  value.
+
+  The home directory is always present, so `home_dir()`,
+  `anysphere_dir()`, `projects_dir()`, `project_transcripts_dir()`,
+  `transcript_path()`, `user_data_dir()`, `user_dir()`,
+  `global_storage_dir()`, `db_path()`, `workspace_storage_dir()`, and
+  `CursorIO::db_path()` return a value instead of a `Result`.
+  `find_workspace_id` and `ensure_workspace_storage_entry` keep their
+  `Result`. Their error is a failed directory read or write, not a
+  missing home.
+- **`path-cli`** (unreleased): `providers::cursor_resolver` returns
+  `Option<PathResolver>`. `None` means the configuration carries no home
+  directory, so Cursor is out of reach: the harness bundle omits it, and
+  a command that targets Cursor reports "cannot determine the home
+  directory". `Config` reads `$APPDATA` and passes it to the resolver on
+  Windows.
 ## `toolpath-opencode`: the caller supplies the home directory — 2026-08-14
 
 - **`toolpath-opencode`** (0.6.0): breaking. `PathResolver::new(home)`

Cargo.toml

@@ -32,7 +32,7 @@ toolpath-gemini = { version = "0.7.0", path = "crates/toolpath-gemini", default-
 toolpath-codex = { version = "0.7.0", path = "crates/toolpath-codex" }
 toolpath-copilot = { version = "0.2.0", path = "crates/toolpath-copilot" }
 toolpath-opencode = { version = "0.6.0", path = "crates/toolpath-opencode" }
-toolpath-cursor = { version = "0.2.0", path = "crates/toolpath-cursor" }
+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" }

crates/path-cli/src/cmd_export.rs

@@ -1721,7 +1721,7 @@ fn build_cursor_session(
         // Cursor filters sidebar composers by `workspaceIdentifier.id`.
         // Reuse the existing id when present, otherwise pre-create a
         // workspaceStorage entry so Cursor adopts ours on next open.
-        let resolver = providers::cursor_resolver(config);
+        let resolver = providers::require_cursor_resolver(config)?;
         if let Ok(ensured) =
             resolver.ensure_workspace_storage_entry(&canonical, stable_workspace_id_for)
         {
@@ -1758,10 +1758,7 @@ fn write_into_cursor_db(
     let project_dir = std::fs::canonicalize(project_dir)
         .with_context(|| format!("resolve project path {}", project_dir.display()))?;
 
-    let resolver = providers::cursor_resolver(config);
-    let db_path = resolver
-        .db_path()
-        .map_err(|e| anyhow::anyhow!("Cannot resolve Cursor state.vscdb path: {}", e))?;
+    let db_path = providers::require_cursor_resolver(config)?.db_path();
     if !db_path.exists() {
         anyhow::bail!(
             "Cursor state.vscdb not found at {} — has Cursor.app been run on this machine?",

crates/path-cli/src/cmd_import.rs

@@ -1165,8 +1165,9 @@ fn derive_cursor(
 
     #[cfg(not(target_os = "emscripten"))]
     {
-        let manager =
-            toolpath_cursor::CursorConvo::with_resolver(providers::cursor_resolver(config));
+        let manager = toolpath_cursor::CursorConvo::with_resolver(
+            providers::require_cursor_resolver(config)?,
+        );
         let derive_one = |sid: &str| derive_cursor_session_with(&manager, sid);
 
         let workspace_filter = project

crates/path-cli/src/cmd_list.rs

@@ -887,7 +887,9 @@ fn run_cursor(project: Option<String>, fmt: ListFormat, config: &Config) -> Resu
 
     #[cfg(not(target_os = "emscripten"))]
     {
-        let manager = providers::cursor_convo(config);
+        let manager = toolpath_cursor::CursorConvo::with_resolver(
+            providers::require_cursor_resolver(config)?,
+        );
         let mut metas = manager
             .io()
             .list_session_metadata()

crates/path-cli/src/cmd_share.rs

@@ -744,12 +744,10 @@ fn harness_status_cursor(bundle: &HarnessBundle, home: Option<&std::path::Path>)
     let Some(mgr) = &bundle.cursor else {
         return HarnessStatus::unresolved();
     };
-    match mgr.resolver().db_path() {
-        Ok(p) => HarnessStatus {
-            path: crate::config::home_relative(&p, home),
-            exists: p.exists(),
-        },
-        Err(_) => HarnessStatus::unresolved(),
+    let p = mgr.resolver().db_path();
+    HarnessStatus {
+        path: crate::config::home_relative(&p, home),
+        exists: p.exists(),
     }
 }
 

crates/path-cli/src/cmd_show.rs

@@ -185,7 +185,9 @@ fn derive_one(source: ShowSource, config: &Config) -> Result<toolpath::v1::Path>
             session,
             project: _,
         } => {
-            let manager = providers::cursor_convo(config);
+            let manager = toolpath_cursor::CursorConvo::with_resolver(
+                providers::require_cursor_resolver(config)?,
+            );
             let s = manager
                 .read_session(&session)
                 .map_err(|e| anyhow::anyhow!("{}", e))?;

crates/path-cli/src/derive.rs

@@ -294,7 +294,7 @@ pub(crate) fn derive_opencode_session_with(
 #[cfg(not(target_os = "emscripten"))]
 pub(crate) fn derive_cursor_session(config: &Config, session: &str) -> Result<DerivedDoc> {
     derive_cursor_session_with(
-        &toolpath_cursor::CursorConvo::with_resolver(providers::cursor_resolver(config)),
+        &toolpath_cursor::CursorConvo::with_resolver(providers::require_cursor_resolver(config)?),
         session,
     )
 }

crates/path-cli/src/harness.rs

@@ -128,7 +128,6 @@ pub(crate) fn is_not_found_opencode(err: &toolpath_opencode::ConvoError) -> bool
 pub(crate) fn is_not_found_cursor(err: &toolpath_cursor::CursorError) -> bool {
     use toolpath_cursor::CursorError;
     matches!(err, CursorError::Io(e) if e.kind() == std::io::ErrorKind::NotFound)
-        || matches!(err, CursorError::NoHomeDirectory)
         || matches!(err, CursorError::CursorDataDirectoryNotFound(_))
         || matches!(err, CursorError::DatabaseNotFound(_))
 }

crates/path-cli/src/providers.rs

@@ -17,9 +17,9 @@
 //! `$COPILOT_HOME` replaces the whole Copilot root, so the injected
 //! directory wins against the home-derived default.
 //!
-//! cursor (Windows) gets its directory injected, not just the home:
-//! its resolver reads `$APPDATA` internally, and that read wins
-//! against `with_home`. The injected directory wins against both.
+//! cursor takes `$APPDATA` as an argument next to the home directory.
+//! Only its Windows default user-data directory consults the value, so
+//! the injection is gated to Windows.
 
 use crate::config::Config;
 #[cfg(not(target_os = "emscripten"))]
@@ -114,18 +114,22 @@ pub(crate) fn require_opencode_resolver(
 }
 
 #[cfg(not(target_os = "emscripten"))]
-pub(crate) fn cursor_convo(config: &Config) -> toolpath_cursor::CursorConvo {
-    let mut resolver = toolpath_cursor::PathResolver::new();
-    if let Some(home) = config.home_dir() {
-        resolver = resolver.with_home(home);
-    }
-    // The resolver consults $APPDATA only on Windows; injecting it on
+pub(crate) fn cursor_resolver(config: &Config) -> Option<toolpath_cursor::PathResolver> {
+    let resolver = toolpath_cursor::PathResolver::new(config.home_dir()?);
+    // The resolver applies $APPDATA only on Windows; injecting it on
     // other platforms would change resolution there.
     #[cfg(windows)]
-    if let Some(appdata) = &config.appdata {
-        resolver = resolver.with_user_data_dir(appdata.join("Cursor"));
-    }
-    toolpath_cursor::CursorConvo::with_resolver(resolver)
+    let resolver = match &config.appdata {
+        Some(appdata) => resolver.with_appdata(appdata),
+        None => resolver,
+    };
+    Some(resolver)
+}
+
+/// [`cursor_resolver`] for a command that targets Cursor.
+#[cfg(not(target_os = "emscripten"))]
+pub(crate) fn require_cursor_resolver(config: &Config) -> Result<toolpath_cursor::PathResolver> {
+    cursor_resolver(config).ok_or_else(|| missing_home("Cursor"))
 }
 
 /// `base` replaces the sessions directory: `--base` wins over the
@@ -160,7 +164,7 @@ pub(crate) fn harness_bundle(config: &Config) -> HarnessBundle {
             toolpath_copilot::CopilotConvo::with_resolver(r).with_strict(copilot_strict(config))
         }),
         opencode: opencode_resolver(config).map(toolpath_opencode::OpencodeConvo::with_resolver),
-        cursor: Some(cursor_convo(config)),
+        cursor: cursor_resolver(config).map(toolpath_cursor::CursorConvo::with_resolver),
         pi: Some(pi_convo(config, None)),
     }
 }
@@ -314,14 +318,21 @@ mod tests {
     }
 
     #[test]
-    fn cursor_convo_roots_at_config_home() {
-        let manager = cursor_convo(&config_with_home());
+    fn cursor_resolver_roots_at_config_home() {
+        let resolver = cursor_resolver(&config_with_home()).unwrap();
         assert_eq!(
-            manager.resolver().anysphere_dir().unwrap(),
+            resolver.anysphere_dir(),
             PathBuf::from("/home/jailed/.cursor")
         );
     }
 
+    #[test]
+    fn cursor_resolver_is_none_without_a_home() {
+        assert!(cursor_resolver(&Config::default()).is_none());
+        let err = require_cursor_resolver(&Config::default()).unwrap_err();
+        assert!(err.to_string().contains("home directory"));
+    }
+
     #[test]
     fn claude_resolver_falls_back_to_config_userprofile() {
         let config = Config {
@@ -337,15 +348,15 @@ mod tests {
 
     #[cfg(windows)]
     #[test]
-    fn cursor_convo_injects_user_data_dir_from_appdata() {
+    fn cursor_resolver_injects_appdata() {
         let config = Config {
             home: Some(PathBuf::from("/home/jailed")),
             appdata: Some(PathBuf::from("/appdata/roaming")),
             ..Config::default()
         };
-        let manager = cursor_convo(&config);
+        let resolver = cursor_resolver(&config).unwrap();
         assert_eq!(
-            manager.resolver().db_path().unwrap(),
+            resolver.db_path(),
             PathBuf::from("/appdata/roaming/Cursor/User/globalStorage/state.vscdb")
         );
     }

crates/toolpath-cursor/Cargo.toml

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

crates/toolpath-cursor/README.md

@@ -61,7 +61,7 @@ IR has no `Turn.extra` slot. They round-trip to nothing.
 ```rust,no_run
 use toolpath_cursor::{CursorConvo, derive::{DeriveConfig, derive_path}};
 
-let manager = CursorConvo::new();
+let manager = CursorConvo::new("/Users/alex");
 let composer_id = "724686cd-875e-47da-a90b-dbc3e523efb8";
 let session = manager.read_session(composer_id)?;
 let path = derive_path(&session, &DeriveConfig::default());

crates/toolpath-cursor/examples/dump_fixture.rs

@@ -76,7 +76,7 @@ fn capture_from_db(
     composer_override: Option<String>,
     bubble_limit: Option<usize>,
 ) -> CursorSession {
-    let mgr = CursorConvo::new();
+    let mgr = CursorConvo::new(home_dir().expect("$HOME (or $USERPROFILE) must be set"));
     let ids = mgr.io().list_composer_ids().expect("list composer ids");
     let chosen_id = composer_override.unwrap_or_else(|| {
         let mut chosen: Option<(String, usize)> = None;
@@ -145,6 +145,14 @@ fn referenced_blob_hashes(session: &CursorSession) -> std::collections::HashSet<
     needed
 }
 
+/// The home directory this example reads Cursor state under. The
+/// library takes it as an argument, so the caller supplies it.
+fn home_dir() -> Option<PathBuf> {
+    std::env::var_os("HOME")
+        .or_else(|| std::env::var_os("USERPROFILE"))
+        .map(PathBuf::from)
+}
+
 // ── Mode 2: from a cursor-agent CLI JSONL transcript ──────────────────
 
 fn capture_from_jsonl(path: &str) -> CursorSession {

crates/toolpath-cursor/src/derive.rs

@@ -65,8 +65,7 @@ mod tests {
         fs::create_dir_all(&global).unwrap();
         let src = fixture_db(BASIC_FIXTURE);
         fs::copy(src.path(), global.join("state.vscdb")).unwrap();
-        let resolver = crate::PathResolver::new()
-            .with_home(temp.path())
+        let resolver = crate::PathResolver::new(temp.path())
             .with_anysphere_dir(temp.path().join(".cursor"))
             .with_user_data_dir(user_data);
         (temp, CursorConvo::with_resolver(resolver))

crates/toolpath-cursor/src/error.rs

@@ -14,9 +14,6 @@ pub enum CursorError {
     #[error("JSON parsing error: {0}")]
     Json(#[from] serde_json::Error),
 
-    #[error("Home directory not found")]
-    NoHomeDirectory,
-
     #[error("Cursor data directory not found at path: {0}")]
     CursorDataDirectoryNotFound(PathBuf),
 

crates/toolpath-cursor/src/io.rs

@@ -13,17 +13,11 @@ pub struct CursorIO {
     resolver: PathResolver,
 }
 
-impl Default for CursorIO {
-    fn default() -> Self {
-        Self::new()
-    }
-}
-
 impl CursorIO {
-    pub fn new() -> Self {
-        Self {
-            resolver: PathResolver::new(),
-        }
+    /// Reads Cursor state under `home`, so the Anysphere directory is
+    /// `<home>/.cursor`.
+    pub fn new<P: Into<PathBuf>>(home: P) -> Self {
+        Self::with_resolver(PathResolver::new(home))
     }
 
     pub fn with_resolver(resolver: PathResolver) -> Self {
@@ -38,12 +32,12 @@ impl CursorIO {
         self.resolver.db_exists()
     }
 
-    pub fn db_path(&self) -> Result<PathBuf> {
+    pub fn db_path(&self) -> PathBuf {
         self.resolver.db_path()
     }
 
     fn open_db(&self) -> Result<DbReader> {
-        DbReader::open(self.resolver.db_path()?)
+        DbReader::open(self.resolver.db_path())
     }
 
     /// Read `composer.composerHeaders` verbatim.
@@ -135,7 +129,7 @@ impl CursorIO {
             return None;
         }
         let slug = paths::slug_from_abs_path(&abs);
-        let p = self.resolver.transcript_path(&slug, session.id()).ok()?;
+        let p = self.resolver.transcript_path(&slug, session.id());
         p.exists().then_some(p)
     }
 }
@@ -182,13 +176,23 @@ mod tests {
         // Pre-populate the DB.
         let src = fixture_db(BASIC_FIXTURE);
         fs::copy(src.path(), global.join("state.vscdb")).unwrap();
-        let resolver = PathResolver::new()
-            .with_home(temp.path())
+        let resolver = PathResolver::new(temp.path())
             .with_anysphere_dir(temp.path().join(".cursor"))
             .with_user_data_dir(user_data);
         (temp, CursorIO::with_resolver(resolver))
     }
 
+    #[test]
+    fn new_roots_at_home() {
+        let temp = TempDir::new().unwrap();
+        let io = CursorIO::new(temp.path());
+        assert_eq!(
+            io.db_path(),
+            io.resolver().user_dir().join("globalStorage/state.vscdb")
+        );
+        assert_eq!(io.resolver().home_dir(), temp.path());
+    }
+
     #[test]
     fn lists_composers_with_has_bubbles_flag() {
         let (_t, io) = setup();