@@ -21,9 +21,12 @@ classifiers = [
     "Topic :: Software Development :: Libraries :: Python Modules",
 ]
 dependencies = [
-    "oold>=0.15.0",
+    # registered_credentials(), used to find the wiki of a file without a URL
+    "oold>=1.1.0",
     "opensemantic",
-    "opensemantic.core>=0.57.4",
+    # TEMPORARY: the file controllers this module wraps are on the core branch
+    # below. Replace with opensemantic.core>=0.59.0 once released.
+    "opensemantic.core @ git+https://github.com/OpenSemanticWorld-Packages/opensemantic.core-python@feat/regen-core-v0.59.0",
     "opensemantic.base>=0.42.7",
     "pydantic[email]>=2.12.0",
     "datamodel-code-generator==0.51.0",
 
@@ -25,8 +25,15 @@ def __init__(self, **kwargs):
         if path is not None and not kwargs.get("local_path"):
             kwargs["local_path"] = str(path)
         super().__init__(**kwargs)
-        if self.local_path:
-            self._set_metadata()
+        if not self.local_path:
+            # The controller this replaces declared path as a required field,
+            # so an instance without one never existed. Raising here keeps the
+            # error at the call site that is wrong, instead of surfacing it on
+            # the first read.
+            raise ValueError(
+                f"{type(self).__name__} needs a file: pass path= or local_path="
+            )
+        self._set_metadata()
 
     @classmethod
     def from_other(cls, other, path=None, **kwargs) -> "LocalFileController":
 
@@ -1,11 +1,12 @@
 import functools
 import logging
 import os
-from typing import IO, Any, Dict, List, Optional
+from typing import IO, Any, Dict, List, Optional, Tuple
 from urllib.parse import urlparse
 
 import mwclient.errors
 from oold.backend.auth import get_credential as _get_registered_credential
+from oold.backend.auth import registered_credentials as _registered_credentials
 
 from osw.auth import CredentialManager
 from osw.controller.file.base import FileController
@@ -82,31 +83,49 @@ def store_params_for_upload(
     return {**se_params, "overwrite": "replace remote"}
 
 
-_sessions: Dict[str, OSW] = {}
-"""Sessions by host, so several files of one wiki share a connection."""
+_sessions: Dict[str, Tuple[Any, OSW]] = {}
+"""Sessions by credential IRI, with the credential they were built from.
 
+Keyed by the credential rather than by the host, because two credentials
+scoped to different paths of one wiki are two different logins. The credential
+is kept so a later ``set_credential`` replaces the session instead of being
+ignored for the lifetime of the process.
+"""
 
-def session_for(url: str) -> OSW:
-    """An OSW session for the host of ``url``, from the registered credential.
 
-    The file entity may be stored somewhere other than its bytes, so the
-    lookup key is the URL the content lives at, not the entity's own IRI.
-    """
+def clear_sessions() -> None:
+    """Drop the cached sessions, so the next access logs in again."""
+    _sessions.clear()
+
+
+def credential_for(url: str) -> Any:
+    """The credential registered for ``url``, or a readable error."""
     host = urlparse(url).netloc or url
-    session = _sessions.get(host)
-    if session is not None:
-        return session
     try:
-        credential = _get_registered_credential(url)
+        return _get_registered_credential(url)
     except ValueError as error:
         raise ValueError(
             f"No credential registered for {host}. Pass osw= explicitly or "
             "register one with oold.backend.auth.set_credential."
         ) from error
+
+
+def session_for(url: str, credential: Any = None) -> OSW:
+    """An OSW session for the host of ``url``, from the registered credential.
+
+    The file entity may be stored somewhere other than its bytes, so the
+    lookup key is the URL the content lives at, not the entity's own IRI.
+    """
+    host = urlparse(url).netloc or url
+    if credential is None:
+        credential = credential_for(url)
+    cached = _sessions.get(credential.iri)
+    if cached is not None and cached[0] == credential:
+        return cached[1]
     cred_mngr = CredentialManager()
     cred_mngr.add_credential(credential)
     session = OSW(site=WtSite(WtSite.WtSiteConfig(iri=host, cred_mngr=cred_mngr)))
-    _sessions[host] = session
+    _sessions[credential.iri] = (credential, session)
     return session
 
 
@@ -135,7 +154,12 @@ def from_other(
         osw: Optional[OSW] = None,
         **kwargs: Dict[str, Any],
     ) -> "WikiFileController":
-        return super().from_other(other, osw=osw, **kwargs)
+        # Only pass a session that was given: writing None over the one the
+        # source already carries would defer the failure to put time, with a
+        # message about a missing credential rather than a dropped session.
+        if osw is not None:
+            kwargs["osw"] = osw
+        return super().from_other(other, **kwargs)
 
     def get(self) -> IO:
         self._init()
@@ -288,11 +312,38 @@ def url(self):
         )
 
     def _ensure_session(self) -> OSW:
-        """The session, connecting on first use when none was passed in."""
+        """The session, connecting on first use when none was passed in.
+
+        A file that is about to be uploaded has no URL yet - that is what the
+        upload produces - so the URL is only one of the ways to find the wiki.
+        Without one the registered credentials decide, and they are only
+        unambiguous when there is exactly one.
+        """
         if self.osw is None:
-            self.osw = session_for(self._url())
+            self.osw = session_for(self._session_url())
         return self.osw
 
+    def _session_url(self) -> str:
+        """The wiki to connect to: the file's own URL, else the credential's."""
+        try:
+            return self._url()
+        except ValueError:
+            pass
+        registered = _registered_credentials()
+        if len(registered) == 1:
+            return next(iter(registered))
+        if not registered:
+            raise ValueError(
+                f"{type(self).__name__} has no download_url or access_url and "
+                "no credential is registered. Pass osw= explicitly or register "
+                "one with oold.backend.auth.set_credential."
+            )
+        raise ValueError(
+            f"{type(self).__name__} has no download_url or access_url, and "
+            f"credentials are registered for {', '.join(sorted(registered))}. "
+            "Pass osw= explicitly to say which wiki this file belongs to."
+        )
+
     def _init(self, name=None, suffix=None):
         self._ensure_session()
         # set the name attribute to the actual file name, e.g., "image.png"
 
@@ -20,7 +20,10 @@
 def test_controller_accepts_a_caller_supplied_stream():
     stream = BytesIO(b"payload")
     controller = InMemoryController(stream=stream)
-    assert controller.get() is stream
+    assert controller.stream is stream
+    # get() hands out a reader over the buffer, not the buffer itself, so a
+    # caller closing what it read does not empty the controller
+    assert controller.get().read() == b"payload"
     assert controller.get().read() == b"payload"
 
 
@@ -68,7 +71,7 @@ def _fake_from_other(other, osw, **data):
 
     controller = seen["source_file_controller"]
     assert isinstance(controller, InMemoryController)
-    assert controller.get() is stream
+    assert controller.stream is stream
 
 
 def test_upload_rejects_a_source_that_is_not_file_like():
 
@@ -0,0 +1,171 @@
+"""Unit tests for how a wiki file controller finds its session.
+
+The session is optional: a controller built from a file entity connects on
+first use. A file that is about to be uploaded has no URL yet - that is what
+the upload produces - so the URL cannot be the only way to find the wiki.
+
+Offline: the session is never built here, only the inputs that decide which
+one would be.
+"""
+
+from io import BytesIO
+
+import pytest
+from oold.backend.auth import UserPwdCredential, set_credential
+
+import osw.controller.file.wiki as wiki_module
+from osw.controller.file.local import LocalFileController
+from osw.controller.file.wiki import OSW, WikiFileController, WtSite
+
+
+@pytest.fixture(autouse=True)
+def _clean_credentials(monkeypatch):
+    """Keep the process-wide credential store and session cache per test."""
+    import oold.backend.auth as auth
+
+    saved = auth._credentials.get()
+    auth._credentials.set({})
+    wiki_module.clear_sessions()
+    yield
+    auth._credentials.set(saved)
+    wiki_module.clear_sessions()
+
+
+def _credential(iri, username="bot", password="secret"):
+    return UserPwdCredential(iri=iri, username=username, password=password)
+
+
+def _a_session() -> OSW:
+    """A stand-in session: only which one travels is under test.
+
+    pydantic v1 copies a model on assignment, so the controller does not hold
+    the very object that was passed in; the sessions are told apart by the
+    site they carry.
+    """
+    return OSW.construct(site=WtSite.__new__(WtSite))
+
+
+def _controller(**kwargs):
+    return WikiFileController(**kwargs)
+
+
+# -- choosing the wiki --------------------------------------------------------
+
+
+def test_a_url_decides_the_wiki():
+    controller = _controller(download_url="https://wiki.example.org/wiki/File:A.bin")
+    assert controller._session_url() == "https://wiki.example.org/wiki/File:A.bin"
+
+
+def test_without_a_url_the_single_registered_credential_decides():
+    """A fresh upload has no URL, so the credential is the only pointer."""
+    set_credential(_credential("wiki.example.org"))
+    assert _controller()._session_url() == "wiki.example.org"
+
+
+def test_without_a_url_and_without_a_credential_the_error_says_so():
+    with pytest.raises(ValueError, match="no credential is registered"):
+        _controller()._session_url()
+
+
+def test_several_credentials_without_a_url_are_ambiguous():
+    set_credential(_credential("wiki.example.org"))
+    set_credential(_credential("other.example.org"))
+    with pytest.raises(ValueError, match=r"other\.example\.org"):
+        _controller()._session_url()
+
+
+def test_a_session_that_was_passed_in_is_kept():
+    sentinel = _a_session()
+    controller = _controller(osw=sentinel)
+    assert controller._ensure_session().site is sentinel.site
+
+
+# -- the session cache --------------------------------------------------------
+
+
+def test_sessions_are_cached_per_credential(monkeypatch):
+    """Two path-scoped credentials of one host are two logins."""
+    built = []
+    monkeypatch.setattr(
+        wiki_module, "OSW", lambda site: built.append(site) or f"session{len(built)}"
+    )
+    monkeypatch.setattr(wiki_module, "WtSite", lambda config: config)
+    monkeypatch.setattr(wiki_module.WtSite, "WtSiteConfig", dict, raising=False)
+    set_credential(_credential("wiki.example.org/a", username="a"))
+    set_credential(_credential("wiki.example.org/b", username="b"))
+
+    first = wiki_module.session_for("https://wiki.example.org/a/File:X")
+    second = wiki_module.session_for("https://wiki.example.org/b/File:X")
+    again = wiki_module.session_for("https://wiki.example.org/a/File:Y")
+
+    assert first != second
+    assert again == first
+
+
+def test_a_replaced_credential_replaces_the_session(monkeypatch):
+    """A later set_credential must not be ignored for the process lifetime."""
+    built = []
+    monkeypatch.setattr(
+        wiki_module, "OSW", lambda site: built.append(site) or f"session{len(built)}"
+    )
+    monkeypatch.setattr(wiki_module, "WtSite", lambda config: config)
+    monkeypatch.setattr(wiki_module.WtSite, "WtSiteConfig", dict, raising=False)
+    set_credential(_credential("wiki.example.org", password="old"))
+    first = wiki_module.session_for("https://wiki.example.org/File:X")
+
+    set_credential(_credential("wiki.example.org", password="new"))
+    second = wiki_module.session_for("https://wiki.example.org/File:X")
+
+    assert second != first
+
+
+def test_a_missing_credential_is_reported_with_the_host():
+    with pytest.raises(ValueError, match=r"wiki\.example\.org"):
+        wiki_module.session_for("https://wiki.example.org/File:X")
+
+
+# -- from_other ---------------------------------------------------------------
+
+
+def test_from_other_keeps_a_session_the_source_carries():
+    sentinel = _a_session()
+    source = WikiFileController(osw=sentinel, download_url="https://w.example/x")
+
+    target = WikiFileController.from_other(source)
+
+    assert target.osw.site is sentinel.site
+
+
+def test_from_other_takes_the_session_it_is_given():
+    sentinel = _a_session()
+    other = _a_session()
+    source = WikiFileController(osw=other, download_url="https://w.example/x")
+
+    target = WikiFileController.from_other(source, osw=sentinel)
+
+    assert target.osw.site is sentinel.site
+    assert target.osw.site is not other.site
+
+
+# -- the local controller -----------------------------------------------------
+
+
+def test_local_controller_needs_a_file():
+    with pytest.raises(ValueError, match="needs a file"):
+        LocalFileController()
+
+
+def test_local_controller_accepts_path_or_local_path(tmp_path):
+    target = tmp_path / "a.bin"
+    target.write_bytes(b"x")
+
+    assert LocalFileController(path=target).path == target
+    assert LocalFileController(local_path=str(target)).path == target
+
+
+def test_local_controller_round_trips_a_file(tmp_path):
+    controller = LocalFileController(path=tmp_path / "a.bin")
+    controller.put(BytesIO(b"payload"))
+    with controller.get() as handle:
+        assert handle.read() == b"payload"