feat(settings): add an explicit opt-out from persisted portable mode

Setting LORA_MANAGER_PORTABLE=1 once wrote use_portable_settings: true
into the plugin's own settings.json, and every later run of every
instance sharing that plugin folder then read and wrote the portable
settings directory. There was no way back except editing the file by
hand, which is exactly the trap a user hit while following the FAQ's
instructions for isolating a second instance (#1114).

LORA_MANAGER_PORTABLE=0 is now the explicit exit:

- _should_use_portable_settings honours "0" as a forced off, so the
  resolved settings directory no longer depends on the persisted flag.
- SettingsManager clears the persisted flag in that case, so later runs
  without the variable stay on the shared settings directory.

Unset or unrecognised values keep the previous behaviour: the persisted
flag decides, so existing portable installs are unaffected.
LORA_MANAGER_SETTINGS_DIR still takes precedence over both.

tests/services/test_portable_mode_flag.py

@@ -0,0 +1,105 @@
+"""Tests for the portable-mode flag lifecycle (issue #1114 follow-up).
+
+``LORA_MANAGER_PORTABLE=1`` persists ``use_portable_settings: true`` into the
+plugin''s own settings.json. That is convenient for repeat runs, but it used to
+be a one-way trip: the flag made every instance sharing that plugin folder read
+(and write) the portable settings directory, and the only way back was editing
+settings.json by hand. ``LORA_MANAGER_PORTABLE=0`` is now the explicit exit.
+"""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+
+from py.services import settings_manager as settings_manager_module
+from py.services.settings_manager import SettingsManager
+
+
+def _write_settings(path, **extra):
+    payload = {
+        "folder_paths": {"loras": ["/loras"]},
+    }
+    payload.update(extra)
+    path.write_text(json.dumps(payload), encoding="utf-8")
+    return payload
+
+
+@pytest.fixture
+def isolated_settings_path(tmp_path, monkeypatch):
+    """Point SettingsManager at a settings.json we control."""
+    settings_path = tmp_path / "settings.json"
+    monkeypatch.setattr(
+        "py.services.settings_manager.ensure_settings_file",
+        lambda logger=None: str(settings_path),
+    )
+    settings_manager_module.reset_settings_manager()
+    yield settings_path
+    settings_manager_module.reset_settings_manager()
+
+
+def test_portable_env_enables_and_persists_the_flag(
+    isolated_settings_path, monkeypatch
+):
+    _write_settings(isolated_settings_path)
+    monkeypatch.setenv("LORA_MANAGER_PORTABLE", "1")
+
+    manager = SettingsManager()
+
+    assert manager.get("use_portable_settings") is True
+    persisted = json.loads(isolated_settings_path.read_text(encoding="utf-8"))
+    assert persisted["use_portable_settings"] is True
+
+
+def test_explicit_zero_clears_the_persisted_flag(
+    isolated_settings_path, monkeypatch
+):
+    """`=0` must undo a previous `=1`, without hand-editing settings.json."""
+    _write_settings(isolated_settings_path, use_portable_settings=True)
+    monkeypatch.setenv("LORA_MANAGER_PORTABLE", "0")
+
+    manager = SettingsManager()
+
+    assert manager.get("use_portable_settings") is False
+    persisted = json.loads(isolated_settings_path.read_text(encoding="utf-8"))
+    # A default value is omitted from disk, so the key is gone entirely.
+    assert persisted.get("use_portable_settings") is None
+
+
+def test_unset_env_keeps_the_persisted_flag(
+    isolated_settings_path, monkeypatch
+):
+    """Portable mode must persist across runs when the variable is unset."""
+    _write_settings(isolated_settings_path, use_portable_settings=True)
+    monkeypatch.delenv("LORA_MANAGER_PORTABLE", raising=False)
+
+    manager = SettingsManager()
+
+    assert manager.get("use_portable_settings") is True
+
+
+def test_zero_is_a_noop_when_portable_was_never_enabled(
+    isolated_settings_path, monkeypatch
+):
+    _write_settings(isolated_settings_path)
+    monkeypatch.setenv("LORA_MANAGER_PORTABLE", "0")
+
+    manager = SettingsManager()
+
+    assert manager.get("use_portable_settings") in (False, None)
+
+
+def test_pinned_settings_dir_wins_over_portable_env(
+    isolated_settings_path, monkeypatch
+):
+    """LORA_MANAGER_SETTINGS_DIR still takes precedence, as documented."""
+    _write_settings(isolated_settings_path)
+    monkeypatch.setenv("LORA_MANAGER_PORTABLE", "1")
+    monkeypatch.setenv("LORA_MANAGER_SETTINGS_DIR", str(isolated_settings_path.parent))
+
+    manager = SettingsManager()
+
+    # The pinned directory already decides the location, so the portable flag
+    # is deliberately left alone.
+    assert not manager.get("use_portable_settings")

tests/utils/test_settings_paths.py

@@ -34,10 +34,12 @@ class TestShouldUsePortableSettings:
     @pytest.mark.parametrize(
         "env_value, settings_flag, expected",
         [
-            ("1", False, True),   # env = 1 overrides settings.json false
+            ("1", False, True),   # env = 1 forces portable on
             ("1", True, True),    # env = 1 matches settings.json true
-            ("0", False, False),  # env = 0 → rely on settings.json
-            ("0", True, True),    # env = 0 → rely on settings.json
+            ("0", False, False),  # env = 0 forces portable off
+            ("0", True, False),   # env = 0 overrides a persisted true
+            ("yes", False, False),  # unrecognised value → rely on settings.json
+            ("yes", True, True),    # unrecognised value → rely on settings.json
             ("", False, False),   # unset → rely on settings.json
             ("", True, True),     # unset → rely on settings.json
         ],
@@ -58,6 +60,21 @@ class TestShouldUsePortableSettings:
             result = _should_use_portable_settings(str(settings_file), logging.getLogger())
             assert result == expected
 
+    def test_explicit_zero_is_the_documented_opt_out(self, tmp_path, caplog):
+        """`=0` must be honoured even against a persisted true flag."""
+        settings_file = tmp_path / "settings.json"
+        settings_file.write_text(json.dumps({"use_portable_settings": True}))
+
+        with pytest.MonkeyPatch.context() as mp:
+            mp.setenv("LORA_MANAGER_PORTABLE", "0")
+            with caplog.at_level(logging.INFO):
+                result = _should_use_portable_settings(
+                    str(settings_file), logging.getLogger()
+                )
+
+        assert result is False
+        assert "Portable mode disabled" in caplog.text
+
     def test_missing_file_without_env(self, tmp_path):
         """Without env var, missing settings file returns False."""
         missing = tmp_path / "nonexistent.json"