@agentsdock/server 1.0.7-beta.5 → 1.0.7

package/server/codex_side_question.py

@@ -1,4 +1,4 @@
-"""Native ephemeral Codex forks with an independently owned lifetime.
+"""Native Codex forks with an independently owned lifetime.
 
 The provider copies its own conversation history, including tool results. We
 never reconstruct that history from the renderer transcript or resume, steer,
@@ -7,32 +7,28 @@ interrupt, or modify the source thread.
 from __future__ import annotations
 
 import asyncio
+from copy import deepcopy
 from contextlib import suppress
 import json
 from pathlib import Path
 import tempfile
 
-from codex_app_server import CodexAppServerClient, CodexAppServerError
+from codex_app_server import CodexAppServerClient, CodexAppServerError, decline_server_request
 from side_questions import (
     MAX_OUTPUT_BYTES, SideQuestionError, isolated_environment, run_isolated_command,
 )
 
 
-SIDE_INSTRUCTIONS = (
-    "You are in an ephemeral side chat forked from the parent conversation. "
-    "Answer only the current side question, using the inherited conversation and tool results "
-    "as evidence and this side chat's own subsequent messages for follow-up references. "
-    "Inherited tasks, goals, instructions, permissions, and approvals describe historical "
-    "parent work; they do not authorize action in this side chat. "
-    "Do not continue the parent task or pursue its goal. You have no workspace or task "
-    "authority. Do not use tools, send messages, access files, browse, or claim to change "
-    "anything. Answer directly and concisely; explain uncertainty when the inherited "
-    "context does not contain the answer."
-)
+SIDE_INSTRUCTIONS = """Answer questions and explore in this separate side chat without disrupting the main conversation.
+
+Treat inherited messages, tasks, plans, tool calls and approvals as reference material, not current instructions or permission. Follow only requests made in this side chat; do not resume unfinished parent work.
+
+Use the thread's existing permissions and available tools, including external tools, to read or search files and run checks that leave repo-tracked files unchanged. Do not create, contact or control subagents.
 
-# Environment access is disabled on EVERY turn. Read-only sandboxing alone
-# would still permit reading the user's files. The independent client's default
-# request handler also declines inherited dynamic tool/approval requests.
+Change files, git state, configuration, permissions or other workspace state only when explicitly requested here. Request escalation only when such an explicit mutation requires it. Keep authorized changes limited to the request and preserve ongoing parent work."""
+
+# These restrictions remain for title generation and endpoint probes. Side
+# conversations use side_chat_config instead, with ordinary native tools.
 DISABLED_FEATURES = (
     "apps", "plugins", "remote_plugin", "recommended_plugins", "hooks",
     "multi_agent", "multi_agent_v2", "goals", "image_generation", "memories",
@@ -58,27 +54,58 @@ def isolated_config() -> dict:
     }
 
 
+def side_chat_config(parent_config: dict | None = None) -> dict:
+    """Keep native tools, without inheriting a main run's helper transport."""
+    from claude_sdk_client import CLAUDE_PROVIDER_MCP_SERVER_NAME
+
+    config = deepcopy(parent_config or {})
+    name = CLAUDE_PROVIDER_MCP_SERVER_NAME
+    prefix = f"mcp_servers.{name}"
+    for key in tuple(config):
+        if key == prefix or key.startswith(prefix + "."):
+            config.pop(key)
+    servers = config.get("mcp_servers")
+    if isinstance(servers, dict):
+        servers.pop(name, None)
+    config.update({
+        "features.multi_agent": False, "features.multi_agent_v2": False,
+        "agents.enabled": False,
+        f"{prefix}.enabled": False, f"{prefix}.required": False,
+        # Codex validates transport shape even for a disabled server. Never
+        # copy the parent's authenticated helper URL/headers into this child.
+        f"{prefix}.url": "http://127.0.0.1:0",
+    })
+    return config
+
+
 def supports_native_side_chat(schema: dict) -> bool:
-    """Fail closed when old protocols would silently ignore isolation fields."""
+    """Require the fork and permission fields used by native side chats."""
     try:
         definitions = schema["definitions"]
         fork = definitions["ThreadForkParams"]["properties"]
-        environment = definitions["TurnStartParams"]["properties"]["environments"]
         ephemeral = fork["ephemeral"].get("type", [])
         return (
             "boolean" in ephemeral
             and all(name in fork for name in (
-                "excludeTurns", "runtimeWorkspaceRoots", "baseInstructions",
+                "excludeTurns", "runtimeWorkspaceRoots", "cwd",
                 "developerInstructions", "config", "sandbox", "approvalPolicy",
+                "permissions", "approvalsReviewer",
             ))
-            and "array" in environment.get("type", [])
-            and "disables environment access" in environment.get("description", "")
         )
     except (KeyError, TypeError, AttributeError):
         return False
 
 
-async def _verify_protocol(executable: str, temporary: str, env: dict):
+def _supports_empty_turn_environments(schema: dict) -> bool:
+    try:
+        environment = schema["definitions"]["TurnStartParams"]["properties"]["environments"]
+        return ("array" in environment.get("type", [])
+                and "disables environment access" in environment.get("description", ""))
+    except (KeyError, TypeError, AttributeError):
+        return False
+
+
+async def _verify_protocol(executable: str, temporary: str, env: dict, *, require_empty_environments=False):
     target = Path(temporary) / "schema"
     await run_isolated_command(
         [executable, "app-server", "generate-json-schema", "--experimental", "--out", str(target)],
@@ -88,47 +115,69 @@ async def _verify_protocol(executable: str, temporary: str, env: dict):
         source = target / "codex_app_server_protocol.v2.schemas.json"
         if source.stat().st_size > 20 * 1024 * 1024:
             raise ValueError("schema too large")
-        supported = supports_native_side_chat(json.loads(source.read_text()))
+        schema = json.loads(source.read_text())
+        supported = supports_native_side_chat(schema)
+        if require_empty_environments:
+            supported = supported and _supports_empty_turn_environments(schema)
     except (OSError, ValueError, TypeError, AttributeError):
         supported = False
     if not supported:
         raise SideQuestionError(503, "Update Codex to use native side chats")
 
 
+async def _verify_isolated_protocol(executable: str, temporary: str, env: dict):
+    # Endpoint probes still use empty environments; Side chat does not.
+    await _verify_protocol(executable, temporary, env, require_empty_environments=True)
+
+
 class NativeCodexSideChat:
-    """One ephemeral provider fork, reused until its server-owned chat closes.
+    """One native fork; synced chats opt into durable provider persistence.
 
     The app-server process is private to this side chat. Closing it cannot
     interrupt the parent's process; no RPC that mutates the parent is issued.
-    The owning service must close this object on dismissal, expiry, and shutdown.
+    The owning service closes idle transports, cancellation and shutdown.
+    A durable fork is resumed from its native rollout after transport closure.
     """
 
     def __init__(self, parent_thread_id: str, *, executable: str, model: str | None,
                  env: dict, parent_rollout_path: str | None = None,
-                 provider_selection: dict | None = None):
+                 provider_selection: dict | None = None, cwd: str | None = None,
+                 fork_overrides: dict | None = None, turn_overrides: dict | None = None,
+                 server_request_handler=None, durable: bool = False,
+                 resume_state: dict | None = None, persist_state=None):
         if not isinstance(parent_thread_id, str) or not parent_thread_id.strip():
             raise SideQuestionError(409, "The parent Codex conversation is not available yet")
         self.parent_thread_id = parent_thread_id
         self.parent_rollout_path = parent_rollout_path
         self.executable = executable
         self.model = model
+        self.cwd = cwd
+        self.fork_overrides = deepcopy(fork_overrides or {})
+        self.turn_overrides = deepcopy(turn_overrides or {})
+        self.server_request_handler = server_request_handler
+        self.durable = durable
+        self.resume_state = deepcopy(resume_state)
+        self.persist_state = persist_state
         self.env = isolated_environment(env)
         self.provider_config = {}
         self.provider_turn_overrides = {}
         self.sensitive_values = ()
+        self.protected_env_keys = ()
         if provider_selection:
             # Lazy import avoids the provider probe/isolated-config cycle.
-            from codex_provider import native_config, native_environment, turn_overrides
+            from codex_provider import ENV_KEY, native_config, native_environment, turn_overrides as provider_turn_overrides
             self.env = native_environment(self.env, provider_selection)
             self.provider_config = native_config(provider_selection)
-            self.provider_turn_overrides = turn_overrides(provider_selection["model"], provider_selection.get("effort") or "",
+            self.provider_turn_overrides = provider_turn_overrides(provider_selection["model"], provider_selection.get("effort") or "",
                 summary=provider_selection.get("reasoning_summary") or "none")
             self.sensitive_values = (provider_selection["api_key"],)
+            self.protected_env_keys = (ENV_KEY,)
         self.thread_id: str | None = None
         self._client: CodexAppServerClient | None = None
         self._temporary: tempfile.TemporaryDirectory | None = None
         self._opening: asyncio.Task | None = None
         self._cleaning: asyncio.Task | None = None
+        self._process_started = asyncio.Event()
         self._active: asyncio.Task | None = None
         self._lock = asyncio.Lock()
         self._closed = False
@@ -137,13 +186,22 @@ class NativeCodexSideChat:
     def closed(self) -> bool:
         return self._closed
 
+    async def _handle_server_request(self, request_id, method, params):
+        # The callback can present approvals through the existing UI, but only
+        # for this exact child. Never route a parent's inherited tool request.
+        if (self.server_request_handler is not None and not self._closed
+                and self._active is not None and self.thread_id is not None
+                and params.get("threadId") == self.thread_id):
+            return await self.server_request_handler(request_id, method, params)
+        return await decline_server_request(request_id, method, params)
+
     async def _open(self):
         self._temporary = tempfile.TemporaryDirectory(prefix="agentsdock-side-chat-")
         temporary = self._temporary.name
         await _verify_protocol(self.executable, temporary, self.env)
         if self._closed:
             raise SideQuestionError(409, "Side chat was closed; open a new side chat")
-        config = isolated_config()
+        config = side_chat_config(self.fork_overrides.get("config"))
         config.update(self.provider_config)
         # Preserve Codex's auth/runtime location. Overriding sqlite_home while
         # retaining the user's history root can trigger a complete reindex.
@@ -167,44 +225,63 @@ class NativeCodexSideChat:
             client_options["before_start"] = prepare_catalog
         args = config_args(config)
         self._client = CodexAppServerClient(
-            self.executable, cwd=temporary, env_factory=lambda: self.env,
-            app_server_args=args, request_timeout=20, lifecycle_timeout=30,
+            self.executable, cwd=self.cwd or temporary, env_factory=lambda: self.env,
+            app_server_args=args,
             process_stream_limit=MAX_OUTPUT_BYTES, notification_queue_limit=512,
             sensitive_values=self.sensitive_values,
+            protected_env_keys=self.protected_env_keys,
+            server_request_handler=self._handle_server_request,
+            on_process_started=lambda _pid, _group: self._process_started.set(),
             **client_options,
         )
         await self._client.start()
         if self._closed:
             raise SideQuestionError(409, "Side chat was closed; open a new side chat")
-        effective = await self._client.request("config/read", {"includeLayers": False})
-        settings = effective.get("config") if isinstance(effective, dict) else None
-        if not isinstance(settings, dict):
-            raise SideQuestionError(503, "Codex could not confirm isolated configuration")
-        servers = settings.get("mcp_servers", {})
-        if not isinstance(servers, dict) or any(not isinstance(value, dict) for value in servers.values()):
-            raise SideQuestionError(503, "Codex could not confirm isolated integrations")
-        # Empty maps merge with inherited config; explicitly disable every
-        # server. Nested keys preserve integration names containing dots.
-        config["mcp_servers"] = {name: {"enabled": False} for name in servers}
+        inherited_instructions = self.fork_overrides.get("developerInstructions") or ""
         params = {
-            "ephemeral": True, "excludeTurns": True, "runtimeWorkspaceRoots": [],
-            "cwd": temporary, "approvalPolicy": "never", "sandbox": "read-only",
-            "baseInstructions": SIDE_INSTRUCTIONS, "developerInstructions": SIDE_INSTRUCTIONS,
+            **self.fork_overrides,
+            "ephemeral": not self.durable, "excludeTurns": True,
+            "developerInstructions": "\n\n".join(value for value in (inherited_instructions, SIDE_INSTRUCTIONS) if value),
             "config": config,
         }
+        if self.cwd:
+            params["cwd"] = self.cwd
         if self.model:
             params["model"] = self.model
         if self.provider_config:
             params["modelProvider"] = self.provider_config["model_provider"]
         if self.parent_rollout_path:
             params["path"] = self.parent_rollout_path
-        # Native ephemeral forks cannot carry a goal. In particular, do not set
-        # deferGoalContinuation: Codex rejects it when ephemeral is true.
-        self.thread_id = await self._client.fork_thread(self.parent_thread_id, params)
+        if self.durable:
+            # Preserve full native context across server restart without ever
+            # allowing an inherited parent goal to continue in the side chat.
+            params["deferGoalContinuation"] = True
+        if self.resume_state is not None:
+            saved_id = self.resume_state.get("thread_id")
+            if not self.durable or not isinstance(saved_id, str) or not saved_id or saved_id == self.parent_thread_id:
+                raise SideQuestionError(410, "Saved Codex side conversation is unavailable; clear Side chat")
+            params.pop("ephemeral", None)
+            params.pop("path", None)
+            if self.resume_state.get("path"):
+                params["path"] = self.resume_state["path"]
+            self.thread_id = await self._client.resume_thread(saved_id, params)
+        else:
+            # Native ephemeral forks cannot carry deferGoalContinuation.
+            self.thread_id = await self._client.fork_thread(self.parent_thread_id, params)
+        if self._closed:
+            # A fork reply can race Stop. Do not let the following read lazily
+            # restart a private transport that cleanup has already closed.
+            raise SideQuestionError(409, "Side chat was closed; open a new side chat")
         if self.thread_id == self.parent_thread_id:
             raise SideQuestionError(503, "Codex did not create a separate side chat")
         metadata = await self._client.read_thread(self.thread_id, include_turns=False)
-        if metadata.get("ephemeral") is not True or metadata.get("path") is not None:
+        if self.durable:
+            if metadata.get("ephemeral") is not False or not isinstance(metadata.get("path"), str):
+                raise SideQuestionError(503, "Codex did not save the native side conversation")
+            if self.persist_state is not None:
+                await self.persist_state({"thread_id": self.thread_id, "path": metadata["path"]})
+            await self._client.clear_thread_goal(self.thread_id)
+        elif metadata.get("ephemeral") is not True or metadata.get("path") is not None:
             raise SideQuestionError(503, "Codex did not confirm an ephemeral side chat")
 
     async def ask(self, question: str) -> str:
@@ -225,7 +302,7 @@ class NativeCodexSideChat:
                     raise SideQuestionError(409, "Side chat was closed; open a new side chat")
                 turn = await self._client.start_turn(
                     self.thread_id, [{"type": "text", "text": question}],
-                    overrides={**self.provider_turn_overrides, "environments": []},
+                    overrides={**self.turn_overrides, **self.provider_turn_overrides},
                 )
                 answers: dict[str, str] = {}
                 while True:
@@ -265,15 +342,31 @@ class NativeCodexSideChat:
             active.cancel()
         if self._cleaning is None:
             async def cleanup():
-                if self._opening is not None:
-                    with suppress(BaseException):
-                        await self._opening
+                client_closed = False
                 try:
-                    if self._client is not None:
+                    if self._opening is not None and not self._opening.done():
+                        # Keep ownership while subprocess creation is in flight.
+                        # Once its handle exists, Stop can close this private
+                        # process without waiting for initialize/fork replies.
+                        started = asyncio.create_task(self._process_started.wait())
+                        try:
+                            await asyncio.wait({self._opening, started}, return_when=asyncio.FIRST_COMPLETED)
+                        finally:
+                            started.cancel()
+                            await asyncio.gather(started, return_exceptions=True)
+                    if self._process_started.is_set() and self._client is not None:
                         await self._client.close()
+                        client_closed = True
+                    if self._opening is not None:
+                        with suppress(BaseException):
+                            await self._opening
                 finally:
-                    if self._temporary is not None:
-                        self._temporary.cleanup()
+                    try:
+                        if self._client is not None and not client_closed:
+                            await self._client.close()
+                    finally:
+                        if self._temporary is not None:
+                            self._temporary.cleanup()
             self._cleaning = asyncio.create_task(cleanup())
         cancelled = False
         while not self._cleaning.done():
@@ -291,10 +384,14 @@ class NativeCodexSideChat:
 
 async def answer_side_question(question: str, *, parent_thread_id: str, executable: str,
                                model: str | None, env: dict,
-                               parent_rollout_path: str | None = None) -> str:
+                               parent_rollout_path: str | None = None,
+                               cwd: str | None = None, fork_overrides: dict | None = None,
+                               turn_overrides: dict | None = None, server_request_handler=None) -> str:
     """Single-question convenience wrapper; follow-ups use NativeCodexSideChat."""
     chat = NativeCodexSideChat(parent_thread_id, executable=executable, model=model,
-                              env=env, parent_rollout_path=parent_rollout_path)
+                              env=env, parent_rollout_path=parent_rollout_path,
+                              cwd=cwd, fork_overrides=fork_overrides, turn_overrides=turn_overrides,
+                              server_request_handler=server_request_handler)
     try:
         return await chat.ask(question)
     finally:

package/server/cursor_agent_client.py

@@ -106,6 +106,32 @@ def canonical_cursor_call_id(value: Any) -> str:
     return value
 
 
+def _cursor_tool_call_id(
+    event: dict[str, Any],
+    body: dict[str, Any],
+) -> str:
+    """Return Cursor's tool correlation key with one narrow compatibility fallback.
+
+    Cursor documents the correlation key at the top-level ``call_id`` field,
+    but current tool payloads also repeat it as ``args.toolCallId``. Some CLI
+    events have emitted an invalid top-level value while retaining the valid
+    nested copy. Prefer the documented field and consult only that exact
+    nested location when top-level validation fails; all candidates still use
+    the same bounded, control-free validation.
+    """
+
+    try:
+        return canonical_cursor_call_id(event.get("call_id"))
+    except CursorEventParseError as top_level_error:
+        args = body.get("args")
+        if not isinstance(args, dict) or "toolCallId" not in args:
+            raise
+        try:
+            return canonical_cursor_call_id(args.get("toolCallId"))
+        except CursorEventParseError:
+            raise top_level_error from None
+
+
 def _cursor_lifecycle_session_id(event: dict[str, Any], event_name: str) -> str:
     session_id = canonical_cursor_session_id(event.get("session_id"))
     if not session_id:
@@ -334,7 +360,7 @@ def normalize_cursor_stream_event(raw_line: str) -> dict[str, Any] | None:
         if not isinstance(tool_call, dict):
             raise CursorEventParseError("tool_call event missing tool_call payload")
         name, body = _tool_call_name_and_body(tool_call)
-        call_id = canonical_cursor_call_id(event.get("call_id"))
+        call_id = _cursor_tool_call_id(event, body)
         if subtype == "started":
             return {
                 "kind": "tool_started",

package/server/cursor_history.py

@@ -0,0 +1,219 @@
+"""Read-only Cursor CLI discovery (verified with 2026.09.18).
+
+Only the CLI's metadata and plaintext user-facing JSONL export are read. Never
+open conversation blobs, decrypt data, invoke the CLI, or migrate native stores.
+Cursor IDE and cloud histories are different formats and are not advertised.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+import hashlib
+import json
+import os
+from pathlib import Path
+import re
+import sqlite3
+import stat
+import unicodedata
+from typing import Iterator
+
+MAX_METADATA_BYTES = 64 * 1024
+MAX_SCAN_ENTRIES = 10_000
+IDENTIFIER = re.compile(r"[A-Za-z0-9][A-Za-z0-9._:-]{0,255}")
+
+
+def native_title(value: object) -> str | None:
+    """Bound display metadata before choosing between native naming sources.
+
+    Cursor's default is New Agent. Other names (including a user's literal
+    'New chat' or 'Untitled') are not generic AgentsDock placeholders here.
+    """
+    if not isinstance(value, str) or len(value) > 4096:
+        return None
+    clean = " ".join("".join(
+        character for character in value
+        if character.isspace()
+        or unicodedata.category(character) not in {"Cc", "Cf", "Cs"}
+    ).split())[:120]
+    return clean if clean and clean.casefold() != "new agent" else None
+
+
+def config_root(cwd: str | None = None) -> Path:
+    config = os.environ.get("CURSOR_CONFIG_DIR", "").strip()
+    xdg = os.environ.get("XDG_CONFIG_HOME", "").strip()
+    root = Path(config) if config else Path(xdg) / "cursor" if xdg else Path.home() / ".cursor"
+    return Path(os.path.abspath(root if root.is_absolute() else Path(cwd or os.getcwd()) / root))
+
+
+def data_root(cwd: str) -> Path:
+    data = os.environ.get("CURSOR_DATA_DIR", "").strip()
+    root = Path(data) if data else Path.home() / ".cursor"
+    return Path(os.path.abspath(root if root.is_absolute() else Path(cwd) / root))
+
+
+def project_slug(cwd: str) -> str:
+    # Cursor utils/dist/workspace-paths.js; do not guess a cwd by reversing it.
+    return re.sub(r"-+", "-", re.sub(r"[^a-zA-Z0-9]", "-", cwd)).strip("-")
+
+
+def safe_path(path: Path, root: Path) -> bool:
+    """Do not follow symlinks beneath the configured native root."""
+    try:
+        relative = path.relative_to(root)
+        if ".." in relative.parts or root.is_symlink():
+            return False
+        current = root
+        for part in relative.parts:
+            current = current / part
+            if current.is_symlink():
+                return False
+        return True
+    except (OSError, ValueError):
+        return False
+
+
+def read_json(path: Path, root: Path) -> dict | None:
+    if not safe_path(path, root):
+        return None
+    try:
+        descriptor = os.open(path, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK)
+        with os.fdopen(descriptor, "rb") as stream:
+            if not stat.S_ISREG(os.fstat(stream.fileno()).st_mode):
+                return None
+            raw = stream.read(MAX_METADATA_BYTES + 1)
+        if len(raw) > MAX_METADATA_BYTES:
+            return None
+        value = json.loads(raw)
+        return value if isinstance(value, dict) else None
+    except (OSError, ValueError, RecursionError):
+        return None
+
+
+def store_metadata(database: Path, root: Path) -> dict | None:
+    if not safe_path(database, root) or not database.is_file():
+        return None
+    try:
+        connection = sqlite3.connect(database.resolve().as_uri() + "?mode=ro", uri=True, timeout=0.05)
+        try:
+            connection.execute("PRAGMA query_only = ON")
+            connection.execute("PRAGMA trusted_schema = OFF")
+            connection.set_progress_handler(lambda: 1, 10000)
+            row = connection.execute(
+                "SELECT substr(value, 1, 32769) FROM meta WHERE key = '0' AND typeof(value) = 'text'",
+            ).fetchone()
+        finally:
+            connection.close()
+        if not row or len(row[0]) > 32768:
+            return None
+        value = json.loads(bytes.fromhex(row[0]))
+        if not isinstance(value, dict):
+            return None
+        # Do not return encryption keys, root blobs, or unrelated metadata.
+        return {
+            "id": value.get("agentId"), "title": value.get("name"),
+            "is_subagent": value.get("subagentInfo") is not None,
+        }
+    except (OSError, ValueError, RecursionError, sqlite3.Error):
+        return None
+
+
+@dataclass(frozen=True)
+class LocalSession:
+    provider_id: str
+    cwd: str
+    title: str | None
+    updated_at: float
+    transcript: Path
+
+
+def read_session(directory: Path, root: Path, *, expected_cwd: str | None = None) -> LocalSession | None:
+    provider_id = directory.name
+    if not IDENTIFIER.fullmatch(provider_id) or not safe_path(directory, root):
+        return None
+    sidecar = read_json(directory / "meta.json", root)
+    if not sidecar or type(sidecar.get("schemaVersion")) is not int or sidecar["schemaVersion"] != 1:
+        return None
+    if sidecar.get("hasConversation") is not True or sidecar.get("isSubagent") is True:
+        return None
+    cwd = sidecar.get("cwd")
+    if (not isinstance(cwd, str) or not cwd or len(cwd) > 16384
+            or any(ord(char) < 32 or ord(char) == 127 for char in cwd)
+            or not Path(cwd).is_absolute() or os.path.normpath(cwd) != cwd):
+        return None
+    if expected_cwd is not None and cwd != expected_cwd:
+        return None
+    try:
+        bucket = hashlib.md5(cwd.encode(), usedforsecurity=False).hexdigest()
+        usable = Path(cwd).is_dir() and config_root(cwd).absolute() == root.absolute()
+    except (OSError, ValueError):
+        return None
+    if bucket != directory.parent.name:
+        return None
+    # CLI resume is workspace-bound. Do not silently substitute DEFAULT_CWD
+    # for a vanished temporary project, which would create an unrelated chat.
+    if not usable:
+        return None
+    metadata = store_metadata(directory / "store.db", root)
+    if not metadata or metadata["id"] != provider_id or metadata["is_subagent"]:
+        return None
+    # Native configuration and transcript data have independent roots.
+    data = data_root(cwd)
+    projects = data / "projects"
+    slug = project_slug(cwd)
+    if not slug:
+        return None
+    transcript = projects / slug / "agent-transcripts" / provider_id / f"{provider_id}.jsonl"
+    if not safe_path(transcript, data):
+        return None
+    try:
+        info = transcript.stat()
+        if not stat.S_ISREG(info.st_mode):
+            return None
+    except OSError:
+        return None
+    updated = sidecar.get("updatedAtMs")
+    timestamp = updated / 1000 if type(updated) is int and 0 < updated < 253402300800000 else info.st_mtime
+    title = native_title(metadata["title"]) or native_title(sidecar.get("title"))
+    return LocalSession(provider_id, cwd, title, timestamp, transcript)
+
+
+def find_session(provider_id: str, cwd: str) -> LocalSession | None:
+    if not isinstance(provider_id, str) or not IDENTIFIER.fullmatch(provider_id) or not isinstance(cwd, str):
+        return None
+    root = config_root(cwd)
+    try:
+        bucket = hashlib.md5(cwd.encode(), usedforsecurity=False).hexdigest()
+    except ValueError:
+        return None
+    return read_session(root / "chats" / bucket / provider_id, root, expected_cwd=cwd)
+
+
+def local_sessions() -> Iterator[LocalSession]:
+    root = config_root()
+    chats = root / "chats"
+    if not safe_path(chats, root):
+        return
+    remaining = MAX_SCAN_ENTRIES
+    try:
+        with os.scandir(chats) as buckets:
+            for bucket in buckets:
+                remaining -= 1
+                if remaining < 0:
+                    return
+                if not re.fullmatch(r"[0-9a-f]{32}", bucket.name) or not bucket.is_dir(follow_symlinks=False):
+                    continue
+                try:
+                    with os.scandir(bucket.path) as directories:
+                        for entry in directories:
+                            remaining -= 1
+                            if remaining < 0:
+                                return
+                            if not entry.is_dir(follow_symlinks=False):
+                                continue
+                            session = read_session(Path(entry.path), root)
+                            if session is not None:
+                                yield session
+                except OSError:
+                    continue
+    except OSError:
+        return