Skip to content

JiuwenSwarm is an intelligent AI Agent built on openJiuwen. It extends the powerful capabilities of large language models directly to your fingertips through various communication apps you use daily.

Python
49.5 KB
Raw Blame
# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.

"""Unit tests for instance_manager module.

Tests for:
- Instance name validation
- Port auto-allocation
- Port conflict detection
- PID file management
- Instance status querying
- InstancesYamlError handling
- InstanceLock concurrency control
"""

import json
import os
import tempfile
import time
from pathlib import Path
from unittest.mock import patch, MagicMock

import pytest

from jiuwenswarm.instance_manager import (
    InstanceConfig,
    InstanceLock,
    InstanceStatus,
    InstancesYamlError,
    validate_instance_name,
    is_valid_instance_name,
    get_instances_yaml_path,
    compute_auto_port,
    calculate_instance_ports,
    check_port_conflicts,
    collect_all_ports,
    find_available_ports,
    write_pid_file,
    read_pid_file,
    delete_pid_file,
    is_process_alive,
    is_port_available,
    get_instance_status,
    get_default_instance_status,
    list_all_instances,
    format_status_line,
    get_instance_config,
    load_all_instance_configs,
    create_bootstrap_env,
    create_bootstrap_env_for_name,
    stop_instance_process,
    create_instances_yaml_template,
    load_instances_yaml,
    save_instances_yaml,
    update_instances_yaml,
    get_instance_index,
    RESERVED_NAMES,
    PORT_TYPES,
    BASE_PORTS,
    PORT_ENV_NAMES,
    PORT_ENV_OVERRIDES,
    STALE_LOCK_TIMEOUT,
)
from jiuwenswarm.instance_manager.config import (
    _format_url_hint,
    _upsert_env_ports,
)


# Module-level helper function for multiprocessing (must be at module level to be pickleable)
def _try_acquire_lock_for_multiprocess(workspace_str: str) -> bool:
    """Helper function to try acquiring lock in a subprocess.

    This must be at module level to be pickleable for multiprocessing.
    """
    from jiuwenswarm.instance_manager import (
        InstanceConfig as _InstanceConfig,
        InstanceLock as _InstanceLock,
    )

    _config = _InstanceConfig(name="test", workspace=Path(workspace_str), ports={})
    _lock = _InstanceLock(_config)
    result = _lock.acquire(timeout=0.5)  # Short timeout
    if result:
        _lock.release()
    return result


def _try_acquire_lock_with_result(workspace_str: str, result_queue) -> None:
    """Helper function for multiprocessing that returns result via Queue.

    This must be at module level to be pickleable for multiprocessing on Windows.
    """
    result = _try_acquire_lock_for_multiprocess(workspace_str)
    result_queue.put(result)


class TestInstanceNameValidation:
    """Test instance name validation."""

    @staticmethod
    def test_valid_simple_names():
        """Test valid simple names."""
        assert validate_instance_name("alice") is None
        assert validate_instance_name("bob") is None
        assert validate_instance_name("my-instance") is None
        assert validate_instance_name("test_123") is None
        assert validate_instance_name("a") is None

    @staticmethod
    def test_valid_complex_names():
        """Test valid complex names."""
        assert validate_instance_name("production-server-01") is None
        assert validate_instance_name("dev_test_env") is None
        assert validate_instance_name("CamelCaseName") is None

    @staticmethod
    def test_invalid_empty_name():
        """Test empty name is invalid."""
        assert validate_instance_name("") is not None
        assert validate_instance_name(None) is not None

    @staticmethod
    def test_invalid_too_long():
        """Test name longer than 64 chars is invalid."""
        long_name = "a" * 65
        assert validate_instance_name(long_name) is not None

    @staticmethod
    def test_invalid_special_chars():
        """Test names with special characters are invalid."""
        assert validate_instance_name("alice@example") is not None
        assert validate_instance_name("my instance") is not None  # space
        assert validate_instance_name("instance.name") is not None  # dot
        assert validate_instance_name("中文实例") is not None  # non-ASCII

    @staticmethod
    def test_invalid_leading_dot():
        """Test names starting with dot are invalid."""
        assert validate_instance_name(".hidden") is not None
        assert validate_instance_name(".alice") is not None

    @staticmethod
    def test_reserved_names():
        """Test reserved names are invalid."""
        for name in RESERVED_NAMES:
            assert validate_instance_name(name) is not None
            assert validate_instance_name(name.upper()) is not None  # case insensitive

    @staticmethod
    def test_is_valid_instance_name():
        """Test is_valid_instance_name helper."""
        assert is_valid_instance_name("alice") is True
        assert is_valid_instance_name("default") is False
        assert is_valid_instance_name("") is False


class TestPortAllocation:
    """Test port auto-allocation."""

    @staticmethod
    def test_base_ports():
        """Test base ports for default instance (index 0)."""
        assert compute_auto_port("agent_server", 0) == 18092
        assert compute_auto_port("web", 0) == 19000
        assert compute_auto_port("gateway", 0) == 19001
        assert compute_auto_port("frontend", 0) == 5173

    @staticmethod
    def test_calculate_instance_ports():
        """Test calculate_instance_ports returns all port types."""
        ports = calculate_instance_ports(1)
        assert "agent_server" in ports
        assert "web" in ports
        assert "gateway" in ports
        assert "frontend" in ports
        assert ports["agent_server"] == 19092

    @staticmethod
    def test_unknown_port_type():
        """Test unknown port type uses default base."""
        assert compute_auto_port("unknown", 0) == 10000


class TestPortAvailability:
    """Test port availability checking."""

    @staticmethod
    def test_check_port_conflicts_no_conflicts():
        """Test no conflicts when ports are available."""
        ports = {"agent_server": 19092, "web": 20000}
        # Should have no conflicts if ports are free (unlikely to be used)
        conflicts = check_port_conflicts(ports, "127.0.0.1", [])
        # This test may fail if ports happen to be occupied
        # We're testing the logic, not the actual availability
        assert isinstance(conflicts, list)

    @staticmethod
    def test_check_port_conflicts_with_existing():
        """Test conflicts detected when port in existing set."""
        ports = {"agent_server": 19092}
        existing = [19092]
        conflicts = check_port_conflicts(ports, "127.0.0.1", existing)
        assert 19092 in conflicts

    @staticmethod
    def test_is_port_available_detects_live_listener(tmp_path):
        """A port held by a real bind()+listen() is reported as occupied.

        Regression guard: the old connect()-based probe timed out against a
        stuck/zombie listener (LISTENING but not accept()ing) and falsely
        reported it as free, which made the fallback pick an index whose
        ports were actually held and the real service crashed with
        OSError [Errno 10048] on bind. The bind()-based probe detects this.
        """
        import socket as _socket
        # Pick an ephemeral port the OS hands us, then hold it.
        s = _socket.socket(_socket.AF_INET, _socket.SOCK_STREAM)
        s.bind(("127.0.0.1", 0))
        port = s.getsockname()[1]
        s.listen(1)
        try:
            assert is_port_available("127.0.0.1", port) is False
        finally:
            s.close()

    @staticmethod
    def test_is_port_available_true_when_free(tmp_path):
        """A genuinely free ephemeral port is reported as available."""
        import socket as _socket
        # Grab an ephemeral port, release it, then probe — it should be free.
        s = _socket.socket(_socket.AF_INET, _socket.SOCK_STREAM)
        s.bind(("127.0.0.1", 0))
        port = s.getsockname()[1]
        s.close()
        # Small race window, but in practice the port is free immediately.
        assert is_port_available("127.0.0.1", port) is True

    @staticmethod
    def test_is_port_available_detects_ipv6_only_listener():
        """IPv6-only listeners must count as occupied for 127.0.0.1 probes.

        Vite on Windows often binds ``[::1]:5173`` only. An IPv4-only bind
        probe would miss it, skip jiuwenswarm-start's port-group fallback, and
        then Vite ``strictPort: true`` fails with "Port 5173 is already in use".
        """
        import socket as _socket
        import pytest

        s = None
        try:
            try:
                s = _socket.socket(_socket.AF_INET6, _socket.SOCK_STREAM)
                # Restrict to IPv6-only so we do not also claim IPv4 via dualstack.
                if hasattr(_socket, "IPV6_V6ONLY"):
                    s.setsockopt(_socket.IPPROTO_IPV6, _socket.IPV6_V6ONLY, 1)
                s.bind(("::1", 0))
                s.listen(1)
            except OSError:
                # Must close before skip: an unbound AF_INET6 socket still
                # triggers ResourceWarning / PytestUnraisableExceptionWarning
                # on the next test's setup (seen on Linux CI without ::1).
                if s is not None:
                    s.close()
                    s = None
                pytest.skip("IPv6 loopback unavailable on this host")
            port = s.getsockname()[1]
            assert is_port_available("127.0.0.1", port) is False
        finally:
            if s is not None:
                s.close()


class TestInstanceConfig:
    """Test InstanceConfig dataclass."""

    @staticmethod
    def test_basic_config():
        """Test basic InstanceConfig creation."""
        config = InstanceConfig(
            name="alice",
            workspace=Path("/tmp/alice"),
            ports={"agent_server": 19092, "web": 20000},
        )
        assert config.name == "alice"
        assert "alice" in str(config.workspace)
        assert config.ports["agent_server"] == 19092


class TestPidFileManagement:
    """Test PID file management."""

    @staticmethod
    def test_write_and_read_pid_file(tmp_path):
        """Test writing and reading PID file."""
        config = InstanceConfig(
            name="test",
            workspace=tmp_path,
            ports={},
        )
        pid = 12345
        write_pid_file(config, pid)

        data = read_pid_file(config)
        assert data is not None
        assert data["pid"] == pid
        assert data["name"] == "test"
        assert "started_at" in data

    @staticmethod
    def test_read_nonexistent_pid_file(tmp_path):
        """Test reading nonexistent PID file."""
        config = InstanceConfig(
            name="test",
            workspace=tmp_path,
            ports={},
        )
        data = read_pid_file(config)
        assert data is None

    @staticmethod
    def test_delete_pid_file(tmp_path):
        """Test deleting PID file."""
        config = InstanceConfig(
            name="test",
            workspace=tmp_path,
            ports={},
        )
        write_pid_file(config, 12345)
        assert config.get_pid_file_path().exists()

        deleted = delete_pid_file(config)
        assert deleted is True
        assert not config.get_pid_file_path().exists()

        # Second delete returns False
        deleted2 = delete_pid_file(config)
        assert deleted2 is False


class TestInstanceStatus:
    """Test InstanceStatus and status querying."""

    @staticmethod
    def test_get_instance_status_stopped(tmp_path):
        """Test getting status for stopped instance."""
        config = InstanceConfig(
            name="test",
            workspace=tmp_path,
            ports={"agent_server": 19092},
        )
        status = get_instance_status(config)
        assert status.name == "test"
        assert status.running is False
        assert status.pid is None

    @staticmethod
    def test_get_instance_status_running_with_dead_pid(tmp_path):
        """Test status returns stopped when PID file exists but process is dead."""
        config = InstanceConfig(
            name="test",
            workspace=tmp_path,
            ports={},
        )
        # Write PID file with unlikely PID
        write_pid_file(config, 999999999)

        status = get_instance_status(config)
        assert status.running is False
        assert status.pid is None

    @staticmethod
    def test_format_status_line():
        """Test formatting status line."""
        status = InstanceStatus(
            name="alice",
            running=True,
            pid=12345,
            workspace=Path("/tmp/alice"),
            ports={"agent_server": 19092, "web": 20000},
        )
        line = format_status_line(status)
        assert "alice" in line
        assert "running" in line
        assert "12345" in line

    @staticmethod
    def test_format_status_line_default():
        """Test formatting default instance status."""
        status = InstanceStatus(
            name="default",
            running=False,
            pid=None,
            workspace=Path("/tmp/default"),
            ports={},
        )
        line = format_status_line(status)
        assert "default" in line
        assert "stopped" in line


class TestIsProcessAlive:
    """Test process alive checking."""

    @staticmethod
    def test_invalid_pid():
        """Test invalid PID returns False."""
        assert is_process_alive(-1) is False
        assert is_process_alive(0) is False

    @staticmethod
    def test_current_process():
        """Test current process PID is alive."""
        current_pid = os.getpid()
        assert is_process_alive(current_pid) is True


class TestBootstrapEnv:
    """Test bootstrap .env creation."""

    @staticmethod
    def test_create_bootstrap_env(tmp_path):
        """Test creating bootstrap env file."""
        config = InstanceConfig(
            name="alice",
            workspace=tmp_path,
            ports={
                "agent_server": 19092,
                "web": 20000,
                "gateway": 20001,
                "frontend": 6173,
            },
        )
        env_path = create_bootstrap_env(config)

        assert env_path.exists()
        content = env_path.read_text()
        assert "JIUWENSWARM_DATA_DIR" in content
        assert "JIUWENSWARM_INSTANCE=alice" in content
        assert "AGENT_SERVER_PORT=19092" in content


class TestInstancesYaml:
    """Test instances.yaml management."""

    @staticmethod
    def test_create_instances_yaml_template(tmp_path):
        """Test creating instances.yaml template."""
        with patch(
            "jiuwenswarm.instance_manager.yaml.get_instances_yaml_path",
            return_value=tmp_path / "instances.yaml",
        ):
            path = create_instances_yaml_template()
            assert path.exists()
            content = path.read_text()
            assert "instances:" in content

    @staticmethod
    def test_load_empty_instances_yaml(tmp_path):
        """Test loading nonexistent instances.yaml."""
        yaml_path = tmp_path / "instances.yaml"
        with patch(
            "jiuwenswarm.instance_manager.yaml.get_instances_yaml_path",
            return_value=yaml_path,
        ):
            data = load_instances_yaml()
            assert data == {"instances": {}}

    @staticmethod
    def test_save_and_load_instances_yaml(tmp_path):
        """Test saving and loading instances.yaml."""
        yaml_path = tmp_path / "instances.yaml"
        with patch(
            "jiuwenswarm.instance_manager.yaml.get_instances_yaml_path",
            return_value=yaml_path,
        ):
            data = {
                "instances": {"alice": {}, "bob": {"ports": {"agent_server": 28092}}}
            }
            save_instances_yaml(data)

            loaded = load_instances_yaml()
            assert "alice" in loaded["instances"]
            assert "bob" in loaded["instances"]
            assert loaded["instances"]["bob"]["ports"]["agent_server"] == 28092

    @staticmethod
    def test_save_is_atomic_and_leaves_no_temp_residue(tmp_path):
        """save_instances_yaml writes atomically and cleans up its temp file.

        Regression guard for the concurrent-named-instance write race: the
        file must never be observed half-written, and the sibling ``.tmp``
        temp file must not be left behind after a successful save.
        """
        yaml_path = tmp_path / "instances.yaml"
        with patch(
            "jiuwenswarm.instance_manager.yaml.get_instances_yaml_path",
            return_value=yaml_path,
        ):
            save_instances_yaml({"instances": {"alice": {"ports": {"gateway": 21001}}}})

            # File is complete and loadable.
            loaded = load_instances_yaml()
            assert loaded["instances"]["alice"]["ports"]["gateway"] == 21001

            # No leftover temp files in the same directory.
            leftovers = [p.name for p in tmp_path.iterdir() if p.name != "instances.yaml"]
            assert leftovers == [], f"temp residue left behind: {leftovers}"


class TestGetInstanceConfig:
    """Test instance config loading."""

    @staticmethod
    def test_get_instance_config_not_found(tmp_path):
        """Test getting nonexistent instance config."""
        yaml_path = tmp_path / "instances.yaml"
        yaml_path.write_text("instances: {}\n", encoding="utf-8")
        with patch(
            "jiuwenswarm.instance_manager.yaml.get_instances_yaml_path",
            return_value=yaml_path,
        ):
            config = get_instance_config("nonexistent")
            assert config is None

    @staticmethod
    def test_get_instance_config_with_auto_ports(tmp_path):
        """Test getting instance config with auto-allocated ports."""
        yaml_path = tmp_path / "instances.yaml"
        yaml_path.write_text("instances:\n  alice: {}\n", encoding="utf-8")
        with patch(
            "jiuwenswarm.instance_manager.yaml.get_instances_yaml_path",
            return_value=yaml_path,
        ):
            config = get_instance_config("alice")
            assert config is not None
            assert config.name == "alice"
            # First instance (index 1) should have these ports
            assert config.ports["agent_server"] == 19092


class TestCollectAllPorts:
    """Test collecting all ports for conflict detection."""

    @staticmethod
    def test_collect_default_ports():
        """Test collecting default instance ports."""
        yaml_path = Path("/nonexistent")
        with patch(
            "jiuwenswarm.instance_manager.yaml.get_instances_yaml_path",
            return_value=yaml_path,
        ):
            ports = collect_all_ports()
            # Default instance ports should be included
            assert 18092 in ports  # agent_server
            assert 19000 in ports  # web

    @staticmethod
    def test_collect_excluding_self():
        """Test collecting ports excluding a specific instance."""
        yaml_path = Path("/nonexistent")
        with patch(
            "jiuwenswarm.instance_manager.yaml.get_instances_yaml_path",
            return_value=yaml_path,
        ):
            ports = collect_all_ports(exclude_name="default")
            # Should be empty when excluding default and no named instances
            assert ports == []


class TestListAllInstances:
    """Test listing all instances."""

    @staticmethod
    def test_list_all_instances_empty(tmp_path):
        """Test listing with no instances.yaml."""
        yaml_path = tmp_path / "instances.yaml"
        with patch(
            "jiuwenswarm.instance_manager.yaml.get_instances_yaml_path",
            return_value=yaml_path,
        ):
            statuses = list_all_instances(include_default=True)
            # Should include default instance
            assert len(statuses) >= 1
            assert any(s.name == "default" for s in statuses)

    @staticmethod
    def test_list_all_instances_no_default(tmp_path):
        """Test listing without default instance."""
        yaml_path = tmp_path / "instances.yaml"
        with patch(
            "jiuwenswarm.instance_manager.yaml.get_instances_yaml_path",
            return_value=yaml_path,
        ):
            statuses = list_all_instances(include_default=False)
            # Should not include default instance
            assert not any(s.name == "default" for s in statuses)


class TestInstancesYamlError:
    """Test instances.yaml error handling."""

    @staticmethod
    def test_valid_yaml(tmp_path):
        """Test loading valid YAML file."""
        yaml_path = tmp_path / "instances.yaml"
        yaml_path.write_text(
            "instances:\n  alice:\n    ports:\n      agent_server: 28092\n",
            encoding="utf-8",
        )
        with patch(
            "jiuwenswarm.instance_manager.yaml.get_instances_yaml_path",
            return_value=yaml_path,
        ):
            data = load_instances_yaml()
            assert "alice" in data["instances"]
            assert data["instances"]["alice"]["ports"]["agent_server"] == 28092

    @staticmethod
    def test_missing_file(tmp_path):
        """Test missing file returns empty structure."""
        yaml_path = tmp_path / "nonexistent.yaml"
        with patch(
            "jiuwenswarm.instance_manager.yaml.get_instances_yaml_path",
            return_value=yaml_path,
        ):
            data = load_instances_yaml()
            assert data == {"instances": {}}

    @staticmethod
    def test_invalid_yaml_syntax(tmp_path):
        """Test invalid YAML syntax raises InstancesYamlError."""
        yaml_path = tmp_path / "instances.yaml"
        # Invalid YAML: missing space after colon, duplicate key
        yaml_path.write_text(
            "instances:\n  alice:bad_syntax\n  alice: duplicate\n",
            encoding="utf-8",
        )
        with patch(
            "jiuwenswarm.instance_manager.yaml.get_instances_yaml_path",
            return_value=yaml_path,
        ):
            with pytest.raises(InstancesYamlError) as exc_info:
                load_instances_yaml()
            # Check error message contains useful info
            assert "YAML format error" in str(exc_info.value)
            assert str(yaml_path) in str(exc_info.value)

    @staticmethod
    def test_missing_instances_key(tmp_path):
        """Test missing 'instances' key raises InstancesYamlError."""
        yaml_path = tmp_path / "instances.yaml"
        yaml_path.write_text("other_key: value\n", encoding="utf-8")
        with patch(
            "jiuwenswarm.instance_manager.yaml.get_instances_yaml_path",
            return_value=yaml_path,
        ):
            with pytest.raises(InstancesYamlError) as exc_info:
                load_instances_yaml()
            assert "Missing 'instances' key" in str(exc_info.value)

    @staticmethod
    def test_invalid_instance_name(tmp_path):
        """Test invalid instance name raises InstancesYamlError."""
        yaml_path = tmp_path / "instances.yaml"
        yaml_path.write_text(
            "instances:\n  '.hidden': {}\n",  # Invalid: starts with dot
            encoding="utf-8",
        )
        with patch(
            "jiuwenswarm.instance_manager.yaml.get_instances_yaml_path",
            return_value=yaml_path,
        ):
            with pytest.raises(InstancesYamlError) as exc_info:
                load_instances_yaml()
            assert "Invalid instance name" in str(exc_info.value)
            assert ".hidden" in str(exc_info.value)

    @staticmethod
    def test_reserved_instance_name(tmp_path):
        """Test reserved instance name raises InstancesYamlError."""
        yaml_path = tmp_path / "instances.yaml"
        yaml_path.write_text(
            "instances:\n  default: {}\n",  # Reserved name
            encoding="utf-8",
        )
        with patch(
            "jiuwenswarm.instance_manager.yaml.get_instances_yaml_path",
            return_value=yaml_path,
        ):
            with pytest.raises(InstancesYamlError) as exc_info:
                load_instances_yaml()
            assert "reserved" in str(exc_info.value).lower()

    @staticmethod
    def test_invalid_port_type(tmp_path):
        """Test unknown port type raises InstancesYamlError."""
        yaml_path = tmp_path / "instances.yaml"
        yaml_path.write_text(
            "instances:\n  alice:\n    ports:\n      unknown_port: 12345\n",
            encoding="utf-8",
        )
        with patch(
            "jiuwenswarm.instance_manager.yaml.get_instances_yaml_path",
            return_value=yaml_path,
        ):
            with pytest.raises(InstancesYamlError) as exc_info:
                load_instances_yaml()
            assert "unknown port type" in str(exc_info.value)
            assert "unknown_port" in str(exc_info.value)

    @staticmethod
    def test_invalid_port_value_negative(tmp_path):
        """Test negative port value raises InstancesYamlError."""
        yaml_path = tmp_path / "instances.yaml"
        yaml_path.write_text(
            "instances:\n  alice:\n    ports:\n      agent_server: -1\n",
            encoding="utf-8",
        )
        with patch(
            "jiuwenswarm.instance_manager.yaml.get_instances_yaml_path",
            return_value=yaml_path,
        ):
            with pytest.raises(InstancesYamlError) as exc_info:
                load_instances_yaml()
            assert "must be 1-65535" in str(exc_info.value)

    @staticmethod
    def test_invalid_port_value_out_of_range(tmp_path):
        """Test port value out of range raises InstancesYamlError."""
        yaml_path = tmp_path / "instances.yaml"
        yaml_path.write_text(
            "instances:\n  alice:\n    ports:\n      agent_server: 70000\n",
            encoding="utf-8",
        )
        with patch(
            "jiuwenswarm.instance_manager.yaml.get_instances_yaml_path",
            return_value=yaml_path,
        ):
            with pytest.raises(InstancesYamlError) as exc_info:
                load_instances_yaml()
            assert "must be 1-65535" in str(exc_info.value)

    @staticmethod
    def test_invalid_port_value_string(tmp_path):
        """Test string port value raises InstancesYamlError."""
        yaml_path = tmp_path / "instances.yaml"
        yaml_path.write_text(
            "instances:\n"
            "  alice:\n"
            "    ports:\n"
            '      agent_server: "28092"\n',  # String, not int
            encoding="utf-8",
        )
        with patch(
            "jiuwenswarm.instance_manager.yaml.get_instances_yaml_path",
            return_value=yaml_path,
        ):
            with pytest.raises(InstancesYamlError) as exc_info:
                load_instances_yaml()
            assert "must be integer" in str(exc_info.value)

    @staticmethod
    def test_ports_not_dict(tmp_path):
        """Test non-dict ports value raises InstancesYamlError."""
        yaml_path = tmp_path / "instances.yaml"
        yaml_path.write_text(
            "instances:\n  alice:\n    ports: invalid\n",
            encoding="utf-8",
        )
        with patch(
            "jiuwenswarm.instance_manager.yaml.get_instances_yaml_path",
            return_value=yaml_path,
        ):
            with pytest.raises(InstancesYamlError) as exc_info:
                load_instances_yaml()
            assert "'ports' must be a dict" in str(exc_info.value)

    @staticmethod
    def test_workspace_not_string(tmp_path):
        """Test non-string workspace raises InstancesYamlError."""
        yaml_path = tmp_path / "instances.yaml"
        yaml_path.write_text(
            "instances:\n  alice:\n    workspace: 123\n",  # Int, not string
            encoding="utf-8",
        )
        with patch(
            "jiuwenswarm.instance_manager.yaml.get_instances_yaml_path",
            return_value=yaml_path,
        ):
            with pytest.raises(InstancesYamlError) as exc_info:
                load_instances_yaml()
            assert "'workspace' must be a string" in str(exc_info.value)


class TestInstanceLock:
    """Test InstanceLock concurrency control."""

    @staticmethod
    def test_acquire_and_release(tmp_path):
        """Test basic lock acquire and release."""
        config = InstanceConfig(
            name="test",
            workspace=tmp_path,
            ports={},
        )
        lock = InstanceLock(config)

        # Should acquire successfully
        assert lock.acquire(timeout=1.0) is True
        assert lock.lock_path.exists()

        # Should be able to release
        lock.release()
        # On Windows, lock file is removed; on Unix, it may remain
        assert getattr(lock, "_lock_file") is None

    @staticmethod
    def test_context_manager(tmp_path):
        """Test lock as context manager."""
        config = InstanceConfig(
            name="test",
            workspace=tmp_path,
            ports={},
        )

        with InstanceLock(config) as lock:
            assert lock.lock_path.exists()
            assert getattr(lock, "_lock_file") is not None

        # Released after context
        assert getattr(lock, "_lock_file") is None

    @staticmethod
    def test_double_acquire_same_process(tmp_path):
        """Test that same process can re-acquire after release."""
        config = InstanceConfig(
            name="test",
            workspace=tmp_path,
            ports={},
        )
        lock = InstanceLock(config)

        assert lock.acquire(timeout=1.0) is True
        lock.release()

        # Should be able to acquire again
        assert lock.acquire(timeout=1.0) is True
        lock.release()

    @staticmethod
    def test_concurrent_acquire_fails(tmp_path):
        """Test that concurrent acquire from another process fails.

        This is the primary test for cross-process lock isolation.
        test_timeout_exceeded only tests same-process lock object competition,
        which is a different scenario and cannot replace this test.
        """
        import multiprocessing

        config = InstanceConfig(
            name="test",
            workspace=tmp_path,
            ports={},
        )
        lock = InstanceLock(config)

        # Acquire in this process
        assert lock.acquire(timeout=1.0) is True

        # Use Queue to get return value from subprocess
        ctx = multiprocessing.get_context("spawn")
        result_queue = ctx.Queue()

        p = ctx.Process(
            target=_try_acquire_lock_with_result, args=(str(tmp_path), result_queue)
        )
        p.start()
        p.join(timeout=5.0)

        # Process should not hang
        assert not p.is_alive()

        # The other process should fail to acquire lock (return False)
        # On Windows, the lock file already exists so exclusive creation fails
        # On Unix, flock on same file from different process fails
        if not result_queue.empty():
            subprocess_result = result_queue.get(timeout=1.0)
            assert subprocess_result is False, (
                "Subprocess should fail to acquire lock held by main process"
            )

        lock.release()

    @staticmethod
    def test_stale_lock_cleanup(tmp_path):
        """Test that stale lock is cleaned up."""
        config = InstanceConfig(
            name="test",
            workspace=tmp_path,
            ports={},
        )

        # Create a stale lock file manually
        lock_path = tmp_path / ".instance.lock"
        lock_path.write_text("99999\n0.0\n", encoding="utf-8")  # Old timestamp

        # Modify mtime to be old
        old_time = time.time() - STALE_LOCK_TIMEOUT - 10
        os.utime(lock_path, (old_time, old_time))

        # Acquire should succeed after cleaning stale lock
        lock = InstanceLock(config)
        assert lock.acquire(timeout=1.0) is True
        lock.release()

    @staticmethod
    def test_timeout_exceeded(tmp_path):
        """Test that acquire returns False after timeout."""
        config = InstanceConfig(
            name="test",
            workspace=tmp_path,
            ports={},
        )

        # First lock acquires successfully
        first_lock = InstanceLock(config)
        assert first_lock.acquire(timeout=1.0) is True

        # Second lock should fail to acquire (timeout exceeded)
        second_lock = InstanceLock(config)
        result = second_lock.acquire(timeout=0.5)
        assert result is False

        # Clean up
        first_lock.release()


class TestPortFallback:
    """Test find_available_ports() conflict-fallback scanning."""

    @staticmethod
    def test_returns_own_index_when_free(monkeypatch):
        """When the base index group is fully free, it is returned as-is."""
        ports_at = lambda idx: calculate_instance_ports(idx)
        monkeypatch.setattr(
            "jiuwenswarm.instance_manager.config.is_port_available",
            lambda host, port: True,
        )
        result = find_available_ports(base_index=0, scan_range=5)
        assert result is not None
        ports, idx = result
        assert idx == 0
        assert ports == ports_at(0)

    @staticmethod
    def test_skips_occupied_index(monkeypatch):
        """When index 1 group is occupied, returns index 2."""
        occupied = set(calculate_instance_ports(1).values())

        def fake(host, port):
            return port not in occupied

        monkeypatch.setattr(
            "jiuwenswarm.instance_manager.config.is_port_available", fake
        )
        result = find_available_ports(base_index=1, scan_range=5)
        assert result is not None
        ports, idx = result
        assert idx == 2
        assert ports == calculate_instance_ports(2)

    @staticmethod
    def test_returns_none_when_range_exhausted(monkeypatch):
        """Returns None when every index in range has a conflict."""
        monkeypatch.setattr(
            "jiuwenswarm.instance_manager.config.is_port_available",
            lambda host, port: False,
        )
        result = find_available_ports(base_index=0, scan_range=3)
        assert result is None

    @staticmethod
    def test_scan_range_zero_scans_nothing(monkeypatch):
        """scan_range=0 means scan nothing → None immediately.

        Regression guard: previously the loop was ``range(max(1, scan_range))``
        which silently scanned ONE index even when the caller asked for zero,
        making the exhausted-range error message in start_services.py describe
        a range that did not match what was actually scanned.
        """
        monkeypatch.setattr(
            "jiuwenswarm.instance_manager.config.is_port_available",
            lambda host, port: True,  # all free, but range is 0
        )
        result = find_available_ports(base_index=5, scan_range=0)
        assert result is None

    @staticmethod
    def test_exclude_ports_treated_as_occupied(monkeypatch):
        """Ports in exclude_ports are skipped even if probe says free."""
        occupied = calculate_instance_ports(0)
        monkeypatch.setattr(
            "jiuwenswarm.instance_manager.config.is_port_available",
            lambda host, port: True,
        )
        result = find_available_ports(
            base_index=0,
            scan_range=5,
            exclude_ports=list(occupied.values()),
        )
        assert result is not None
        _, idx = result
        assert idx == 1  # index 0 fully excluded -> next group


class TestEnvVarOverride:
    """Test Phase 2 env-var base-port override (Docker-friendly)."""

    @staticmethod
    def test_no_env_vars_keeps_defaults(monkeypatch):
        """Without env vars, behavior is identical to BASE_PORTS."""
        for key in PORT_ENV_OVERRIDES.values():
            monkeypatch.delenv(key, raising=False)
        assert compute_auto_port("gateway", 0) == 19001
        assert calculate_instance_ports(0)["frontend"] == 5173

    @staticmethod
    def test_env_var_overrides_base(monkeypatch):
        """JIUWENSWARM_<TYPE>_PORT overrides the base port for that type only."""
        monkeypatch.setenv("JIUWENSWARM_GATEWAY_PORT", "29001")
        monkeypatch.setenv("JIUWENSWARM_FRONTEND_PORT", "15173")
        try:
            assert compute_auto_port("gateway", 0) == 29001
            assert compute_auto_port("gateway", 2) == 29001 + 2000
            ports = calculate_instance_ports(0)
            assert ports["gateway"] == 29001
            assert ports["frontend"] == 15173
            # Unset types keep defaults
            assert ports["agent_server"] == 18092
            assert ports["web"] == 19000
        finally:
            monkeypatch.delenv("JIUWENSWARM_GATEWAY_PORT", raising=False)
            monkeypatch.delenv("JIUWENSWARM_FRONTEND_PORT", raising=False)

    @staticmethod
    def test_invalid_env_var_ignored(monkeypatch):
        """Malformed env value falls back to default (no crash)."""
        monkeypatch.setenv("JIUWENSWARM_GATEWAY_PORT", "not-a-number")
        try:
            assert compute_auto_port("gateway", 0) == 19001
        finally:
            monkeypatch.delenv("JIUWENSWARM_GATEWAY_PORT", raising=False)


class TestUpsertEnvPorts:
    """Test _upsert_env_ports() persistence for the default instance."""

    @staticmethod
    def test_append_to_empty_file(tmp_path):
        env_path = tmp_path / ".env"
        ports = {"agent_server": 19092, "web": 20000, "gateway": 20001, "frontend": 6173}
        _upsert_env_ports(env_path, ports)
        txt = env_path.read_text()
        assert "AGENT_SERVER_PORT=19092" in txt
        assert "GATEWAY_PORT=20001" in txt
        assert "FRONTEND_PORT=6173" in txt

    @staticmethod
    def test_replace_existing_preserves_others(tmp_path):
        env_path = tmp_path / ".env"
        env_path.write_text(
            "API_KEY=sk-keep\nGATEWAY_PORT=19001\nMODEL_NAME=m\n",
            encoding="utf-8",
        )
        ports = {"agent_server": 19092, "web": 20000, "gateway": 20001, "frontend": 6173}
        _upsert_env_ports(env_path, ports)
        txt = env_path.read_text()
        assert "API_KEY=sk-keep" in txt
        assert "MODEL_NAME=m" in txt
        assert "GATEWAY_PORT=20001" in txt
        assert "GATEWAY_PORT=19001" not in txt
        assert "AGENT_SERVER_PORT=19092" in txt

    @staticmethod
    def test_idempotent(tmp_path):
        env_path = tmp_path / ".env"
        ports = {"agent_server": 19092, "web": 20000, "gateway": 20001, "frontend": 6173}
        _upsert_env_ports(env_path, ports)
        before = env_path.read_text()
        _upsert_env_ports(env_path, ports)
        assert env_path.read_text() == before

    @staticmethod
    def test_comment_lines_preserved(tmp_path):
        """A commented-out port line must not be replaced; a real line is appended."""
        env_path = tmp_path / ".env"
        env_path.write_text("# GATEWAY_PORT=9999\nAPI_KEY=x\n", encoding="utf-8")
        _upsert_env_ports(env_path, {"gateway": 20001})
        lines = env_path.read_text().splitlines()
        assert "# GATEWAY_PORT=9999" in lines
        assert any(l == "GATEWAY_PORT=20001" for l in lines)


class TestFormatUrlHint:
    """Test _format_url_hint() output."""

    @staticmethod
    def test_hint_contains_gateway_port():
        hint = _format_url_hint({"gateway": 20001})
        assert "jiuwenswarm-tui --url ws://127.0.0.1:20001/tui" in hint
        assert "jiuwenswarm chat" in hint

    @staticmethod
    def test_hint_handles_missing_gateway():
        """Missing gateway port still formats (uses 0 placeholder)."""
        hint = _format_url_hint({})
        assert "ws://127.0.0.1:0/tui" in hint


class TestStartServicesFallback:
    """Test start_services._resolve_ports_with_fallback() integration.

    Covers the named-instance path (persists to instances.yaml + bootstrap .env)
    and the default-instance path (persists to ~/.jiuwenswarm/config/.env).
    """

    @staticmethod
    def test_named_instance_fallback_persists(tmp_path, monkeypatch):
        """Named instance: index-1 conflict → fallback to index-2, persisted."""
        import yaml
        from jiuwenswarm import start_services

        # Isolate instances.yaml / workspaces into tmp_path by patching the
        # path resolvers directly (env-var-based resolution is cached at module
        # import time, which is unreliable across tests in one process).
        yaml_path = tmp_path / "instances.yaml"
        ws = tmp_path / "alice"
        ws.mkdir()
        yaml_path.write_text(
            f"instances:\n  alice:\n    workspace: {ws}\n", encoding="utf-8"
        )

        monkeypatch.setattr(
            "jiuwenswarm.instance_manager.yaml.get_instances_yaml_path",
            lambda: yaml_path,
        )
        # Workspace path resolver must also point at tmp_path for bootstrap .env.
        monkeypatch.setattr(
            "jiuwenswarm.instance_manager.yaml.get_instance_workspace_path",
            lambda name: tmp_path / name,
        )

        cmd = start_services.InstanceCommand("alice")
        assert cmd.validate_and_load() is None
        orig = dict(cmd.config.ports)
        assert orig["gateway"] == 20001  # index 1

        # Make index-1 group occupied; everything else free
        occupied = set(calculate_instance_ports(1).values())
        real = is_port_available

        def fake(host, port):
            return port not in occupied and real(host, port)

        monkeypatch.setattr(
            "jiuwenswarm.instance_manager.config.is_port_available", fake
        )
        monkeypatch.setattr(
            "jiuwenswarm.start_services.is_port_available", fake
        )

        rc = start_services._resolve_ports_with_fallback(cmd)
        assert rc is None  # success
        assert cmd.config.ports["agent_server"] == 20092  # index 2
        assert cmd.config.ports["gateway"] == 21001

        # yaml persisted with new ports
        data = yaml.safe_load(yaml_path.read_text())
        assert data["instances"]["alice"]["ports"]["gateway"] == 21001

        # bootstrap .env persisted
        benv = ws / ".env"
        assert benv.exists()
        assert "GATEWAY_PORT=21001" in benv.read_text()

    @staticmethod
    def test_default_instance_fallback_persists_to_env(tmp_path, monkeypatch):
        """Default instance: conflict → fallback, persisted to config/.env."""
        from jiuwenswarm import start_services

        # Patch get_env_file (used by start_services) to a tmp path so the
        # test never touches the real ~/.jiuwenswarm/config/.env.
        cfg_env = tmp_path / "config" / ".env"
        cfg_env.parent.mkdir(parents=True, exist_ok=True)
        cfg_env.write_text("API_KEY=sk-keep\nMODEL_NAME=m-keep\n", encoding="utf-8")
        monkeypatch.setattr("jiuwenswarm.start_services.get_env_file", lambda: cfg_env)

        # Isolate from other instances configured on the host machine
        # (e.g. a leftover 'alice'/'bob' in instances.yaml would otherwise
        # pollute collect_all_ports and shift the fallback index).
        monkeypatch.setattr(
            "jiuwenswarm.instance_manager.collect_all_ports",
            lambda exclude_name=None: [],
        )

        cmd = start_services.InstanceCommand("default")
        assert cmd.validate_and_load() is None

        # Force ONLY the index-0 group to be occupied; every higher index free.
        occupied = set(calculate_instance_ports(0).values())
        real = is_port_available

        def fake(host, port):
            return port not in occupied and real(host, port)

        monkeypatch.setattr(
            "jiuwenswarm.instance_manager.config.is_port_available", fake
        )
        monkeypatch.setattr(
            "jiuwenswarm.start_services.is_port_available", fake
        )

        rc = start_services._resolve_ports_with_fallback(cmd)
        assert rc is None
        assert cmd.config.ports["gateway"] == 20001  # index 1

        # config/.env got the new ports AND preserved existing keys
        txt = cfg_env.read_text()
        assert "API_KEY=sk-keep" in txt
        assert "MODEL_NAME=m-keep" in txt
        assert "GATEWAY_PORT=20001" in txt
        assert "AGENT_SERVER_PORT=19092" in txt

    @staticmethod
    def test_no_fallback_returns_error_when_range_exhausted(tmp_path, monkeypatch):
        """When the whole scan range is occupied, fallback returns 1."""
        from jiuwenswarm import start_services

        cfg_env = tmp_path / "config" / ".env"
        cfg_env.parent.mkdir(parents=True, exist_ok=True)
        monkeypatch.setattr("jiuwenswarm.start_services.get_env_file", lambda: cfg_env)
        monkeypatch.setattr(
            "jiuwenswarm.instance_manager.collect_all_ports",
            lambda exclude_name=None: [],
        )

        cmd = start_services.InstanceCommand("default")
        assert cmd.validate_and_load() is None

        monkeypatch.setattr(
            "jiuwenswarm.instance_manager.config.is_port_available",
            lambda host, port: False,
        )
        monkeypatch.setattr(
            "jiuwenswarm.start_services.is_port_available",
            lambda host, port: False,
        )
        rc = start_services._resolve_ports_with_fallback(cmd, scan_range=3)
        assert rc == 1

    @staticmethod
    def test_persistence_failure_aborts_launch(tmp_path, monkeypatch):
        """P2: if port persistence fails, fallback returns 1 (not None).

        Without this, a default instance whose .env write fails would return
        success and the launcher would spawn subprocesses that read the OLD
        (still-conflicting) ports from .env and crash on bind. The caller
        must be told persistence failed so it aborts instead.
        """
        from unittest.mock import patch as _patch
        from jiuwenswarm import start_services

        cfg_env = tmp_path / "config" / ".env"
        cfg_env.parent.mkdir(parents=True, exist_ok=True)
        # Pre-create the file so the post-check read works even though the
        # write is mocked to fail. Pre-existing content must be preserved
        # (no fallback ports written into it).
        cfg_env.write_text("API_KEY=sk-keep\n", encoding="utf-8")
        monkeypatch.setattr("jiuwenswarm.start_services.get_env_file", lambda: cfg_env)
        monkeypatch.setattr(
            "jiuwenswarm.instance_manager.collect_all_ports",
            lambda exclude_name=None: [],
        )

        cmd = start_services.InstanceCommand("default")
        assert cmd.validate_and_load() is None

        # Only index-0 occupied so a fallback group IS found — but then make
        # the .env write raise so the persistence path fails.
        occupied = set(calculate_instance_ports(0).values())
        real = is_port_available

        def fake_probe(host, port):
            return port not in occupied and real(host, port)

        monkeypatch.setattr(
            "jiuwenswarm.instance_manager.config.is_port_available", fake_probe
        )
        monkeypatch.setattr(
            "jiuwenswarm.start_services.is_port_available", fake_probe
        )

        def boom(*args, **kwargs):
            raise OSError("simulated .env write failure")

        with _patch(
            "jiuwenswarm.instance_manager.config._upsert_env_ports",
            side_effect=boom,
        ):
            rc = start_services._resolve_ports_with_fallback(cmd)

        # Must surface the failure (return 1), not silently succeed.
        assert rc == 1
        # Persistence failed, so the .env must NOT contain fallback ports;
        # only the pre-existing content remains.
        assert "GATEWAY_PORT=20001" not in cfg_env.read_text()
        assert "API_KEY=sk-keep" in cfg_env.read_text()

    @staticmethod
    def test_no_conflict_launch_clears_stale_env_ports(tmp_path, monkeypatch):
        """P2 regression: a previous fallback's ports must not linger in .env.

        Scenario ("conflict-then-no-conflict"):
          1. Prior launch hit a conflict and wrote GATEWAY_PORT=20001 to .env.
          2. The conflict is now gone (index-0 ports are free again).
          3. This launch has NO conflict → check_ports_conflicts() is empty.

        Without the _sync_default_env_ports call on the no-conflict path,
        .env would keep GATEWAY_PORT=20001 and subprocesses (which read .env
        via load_dotenv) would bind 20001 instead of the default 19001. The
        fix re-writes index-0 defaults into .env on every no-conflict launch.
        """
        from unittest.mock import patch as _patch
        from jiuwenswarm import start_services

        cfg_env = tmp_path / "config" / ".env"
        cfg_env.parent.mkdir(parents=True, exist_ok=True)
        # Simulate a stale fallback residue from a previous launch.
        cfg_env.write_text(
            "API_KEY=sk-keep\n"
            "AGENT_SERVER_PORT=19092\n"  # stale fallback (index 1)
            "GATEWAY_PORT=20001\n"       # stale fallback (index 1)
            "MODEL_NAME=m-keep\n",
            encoding="utf-8",
        )
        monkeypatch.setattr("jiuwenswarm.start_services.get_env_file", lambda: cfg_env)
        monkeypatch.setattr(
            "jiuwenswarm.instance_manager.collect_all_ports",
            lambda exclude_name=None: [],
        )

        cmd = start_services.InstanceCommand("default")
        assert cmd.validate_and_load() is None

        # Make index-0 ports look free (no conflict) so _run takes the
        # no-conflict path. Other indices are irrelevant here.
        monkeypatch.setattr(
            "jiuwenswarm.instance_manager.config.is_port_available",
            lambda host, port: True,
        )
        monkeypatch.setattr(
            "jiuwenswarm.start_services.is_port_available",
            lambda host, port: True,
        )

        # Stub out the actual subprocess launch — we only care about .env sync.
        monkeypatch.setattr(
            "jiuwenswarm.start_services._build_commands",
            lambda mode: [("stub", ["true"], tmp_path)],
        )
        monkeypatch.setattr(
            "jiuwenswarm.start_services._run_processes",
            lambda commands, ports: 0,
        )

        rc = start_services._run("app")
        assert rc == 0

        # .env must now carry the index-0 DEFAULTS (not the stale 20001).
        txt = cfg_env.read_text()
        assert "GATEWAY_PORT=19001" in txt, txt
        assert "AGENT_SERVER_PORT=18092" in txt, txt
        # Stale fallback ports must be gone.
        assert "GATEWAY_PORT=20001" not in txt
        assert "AGENT_SERVER_PORT=19092" not in txt
        # And pre-existing unrelated keys preserved.
        assert "API_KEY=sk-keep" in txt
        assert "MODEL_NAME=m-keep" in txt