ags-cli 0.1.0__py3-none-any.whl

harness/services/ssh.py

@@ -0,0 +1,300 @@
+"""Remote (SSH) project support — all the plumbing in one module.
+
+Shells out to the system ``ssh`` binary rather than a Python SSH library, so the
+server user's ``~/.ssh/config`` (aliases, keys, agent, ProxyJump, ControlMaster)
+works unchanged and no key material ever touches the harness. ``BatchMode=yes``
+means key/agent auth only — a host that would prompt for a password fails fast
+with its stderr surfaced instead of hanging.
+
+Remote commands are plain POSIX sh; the remote login shell must be POSIX-ish."""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import posixpath
+import re
+import shlex
+import time
+
+# No leading '-' (blocks ssh option injection); alias, host, or user@host forms.
+HOST_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_.@-]*$")
+
+# Test seam: point at tests/simulators/ssh_stub.py to run "remote" commands locally.
+SSH_BIN = os.environ.get("HARNESS_SSH_BIN", "ssh")
+
+_CONNECT_TIMEOUT_S = 5
+
+
+def validate_host(host: str) -> str:
+    """A host is an ssh alias, hostname, or user@host — never an option string."""
+    host = (host or "").strip()
+    if not HOST_RE.match(host):
+        raise ValueError(f"invalid ssh host: {host!r}")
+    return host
+
+
+def ssh_base_argv(host: str, *, tty: bool = False) -> list[str]:
+    return [
+        SSH_BIN,
+        "-tt" if tty else "-T",
+        "-o", "BatchMode=yes",
+        "-o", f"ConnectTimeout={_CONNECT_TIMEOUT_S}",
+        validate_host(host),
+    ]
+
+
+async def ssh_run(host: str, remote_cmd: str, *, timeout_s: float = 15.0) -> tuple[int, str, str]:
+    """Run ``remote_cmd`` on ``host`` via the ssh client. Returns (rc, stdout, stderr)."""
+    proc = await asyncio.create_subprocess_exec(
+        *ssh_base_argv(host), remote_cmd,
+        stdin=asyncio.subprocess.DEVNULL,
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.PIPE,
+    )
+    try:
+        out, err = await asyncio.wait_for(proc.communicate(), timeout=timeout_s)
+    except TimeoutError:
+        proc.kill()
+        raise TimeoutError(f"ssh to {host!r} timed out after {timeout_s:.0f}s") from None
+    return proc.returncode or 0, out.decode(errors="replace"), err.decode(errors="replace")
+
+
+async def remote_is_dir(host: str, path: str) -> bool:
+    rc, _, _ = await ssh_run(host, f"test -d {shlex.quote(path)}")
+    return rc == 0
+
+
+def _remote_cd(path: str | None) -> str:
+    """POSIX `cd` clause for a remote path, with `~` handled on the remote side."""
+    if path in (None, "", "~"):
+        return "cd"
+    if path.startswith("~/"):
+        return f'cd -- "$HOME"/{shlex.quote(path[2:])}'
+    return f"cd -- {shlex.quote(path)}"
+
+
+async def browse_dirs_remote(host: str, path: str | None) -> dict:
+    """Remote counterpart of ``browse_dirs`` — same ``{path, parent, dirs}`` shape
+    (plus ``host``). First stdout line is the resolved path (`pwd -P`), the rest is
+    `ls -1p` filtered to non-dot directories. Known limitation: directory names
+    containing newlines are mis-parsed — acceptable for a folder picker."""
+    rc, out, err = await ssh_run(host, f"{_remote_cd(path)} && pwd -P && LC_ALL=C ls -1p")
+    if rc != 0:
+        raise ValueError(err.strip() or f"cannot read remote directory: {path}")
+    lines = out.splitlines()
+    if not lines:
+        raise ValueError(f"cannot read remote directory: {path}")
+    resolved = lines[0].strip()
+    dirs = sorted(
+        (ln[:-1] for ln in lines[1:] if ln.endswith("/") and not ln.startswith(".")),
+        key=str.lower,
+    )
+    parent = posixpath.dirname(resolved)
+    return {
+        "path": resolved,
+        "parent": parent if parent != resolved else None,
+        "dirs": dirs,
+        "host": host,
+    }
+
+
+async def ssh_check(host: str, *, path: str | None = None, bin: str | None = None) -> dict:
+    """Connectivity probe for the GUI "Test connection" button. Never raises on
+    connection failure — returns ``ok: False`` with the ssh client's stderr."""
+    result: dict = {"ok": False, "latency_ms": None, "error": None,
+                    "dir_ok": None, "bin_version": None}
+    t0 = time.monotonic()
+    try:
+        rc, _, err = await ssh_run(host, "true")
+    except (TimeoutError, OSError, ValueError) as exc:
+        result["error"] = str(exc)
+        return result
+    result["latency_ms"] = round((time.monotonic() - t0) * 1000, 1)
+    if rc != 0:
+        result["error"] = err.strip() or f"ssh exited with code {rc}"
+        return result
+    result["ok"] = True
+    if path:
+        result["dir_ok"] = await remote_is_dir(host, path)
+    if bin:
+        q = shlex.quote(bin)
+        # Login shell so ~/.profile PATH additions (~/.local/bin, where agent CLIs
+        # usually live) are visible — same environment the run itself will get.
+        probe = shlex.quote(f"command -v {q} >/dev/null 2>&1 && {q} --version")
+        rc, out, _ = await ssh_run(host, f"sh -lc {probe}")
+        if rc == 0 and out.strip():
+            result["bin_version"] = out.strip().splitlines()[0]
+    return result
+
+
+async def ssh_run_with_input(host: str, remote_cmd: str, input_str: str, timeout_s: float = 15.0) -> tuple[int, str, str]:
+    """Run ``remote_cmd`` on ``host`` via the ssh client, sending ``input_str`` to stdin. Returns (rc, stdout, stderr)."""
+    proc = await asyncio.create_subprocess_exec(
+        *ssh_base_argv(host), remote_cmd,
+        stdin=asyncio.subprocess.PIPE,
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.PIPE,
+    )
+    try:
+        out, err = await asyncio.wait_for(
+            proc.communicate(input=input_str.encode("utf-8")),
+            timeout=timeout_s
+        )
+    except TimeoutError:
+        proc.kill()
+        raise TimeoutError(f"ssh to {host!r} timed out after {timeout_s:.0f}s") from None
+    return proc.returncode or 0, out.decode(errors="replace"), err.decode(errors="replace")
+
+
+def _remote_safe_join(project_dir: str, subpath: str) -> str:
+    """Validate and resolve target path under remote project directory."""
+    root = posixpath.normpath(project_dir)
+    target = posixpath.normpath(posixpath.join(root, subpath))
+    root_check = root if root.endswith('/') else root + '/'
+    if not (target + '/').startswith(root_check) and target != root:
+        raise ValueError(f"path outside remote project folder: {subpath!r}")
+    return target
+
+
+async def list_dir_remote(host: str, project_dir: str, subpath: str = "") -> dict:
+    """List directory contents on remote host."""
+    target = _remote_safe_join(project_dir, subpath)
+    cmd = (
+        f"cd -- {shlex.quote(target)} && "
+        "for f in *; do "
+        '[ -e "$f" ] || [ -L "$f" ] || continue; '
+        'if [ -d "$f" ]; then '
+        'echo "d|0|$f"; '
+        "else "
+        'size=$(ls -dn -- "$f" 2>/dev/null | awk \'{print $5}\'); '
+        'echo "f|${size:-0}|$f"; '
+        "fi; "
+        "done"
+    )
+    rc, out, err = await ssh_run(host, cmd)
+    if rc != 0:
+        dir_rc, _, _ = await ssh_run(host, f"test -d {shlex.quote(target)}")
+        if dir_rc != 0:
+            raise ValueError(f"not a directory or cannot access: {subpath!r}")
+        raise ValueError(err.strip() or f"failed to list remote directory: {subpath}")
+
+    dirs = []
+    files = []
+    for line in out.splitlines():
+        if not line or '|' not in line:
+            continue
+        parts = line.split('|', 2)
+        if len(parts) < 3:
+            continue
+        t, size_str, name = parts
+        try:
+            size = int(size_str)
+        except ValueError:
+            size = 0
+        if t == "d":
+            dirs.append({"name": name, "type": "dir", "size": 0})
+        else:
+            files.append({"name": name, "type": "file", "size": size})
+
+    dirs.sort(key=lambda e: e["name"].lower())
+    files.sort(key=lambda e: e["name"].lower())
+
+    norm = "" if subpath in ("", ".") else posixpath.normpath(subpath).strip("/")
+    parent = posixpath.dirname(norm) if norm else None
+    return {
+        "root": project_dir,
+        "subpath": norm,
+        "parent": parent,
+        "entries": dirs + files,
+    }
+
+
+async def read_file_remote(host: str, project_dir: str, subpath: str, max_bytes: int = 1_000_000) -> dict:
+    """Read file content on remote host."""
+    target = _remote_safe_join(project_dir, subpath)
+    cmd = f"ls -dn -- {shlex.quote(target)}"
+    rc, out, err = await ssh_run(host, cmd)
+    if rc != 0:
+        raise ValueError(f"not a file or cannot access: {subpath!r}")
+    
+    parts = out.strip().split()
+    if not parts or parts[0].startswith('d'):
+        raise ValueError(f"not a file: {subpath!r}")
+    
+    try:
+        size = int(parts[4])
+    except (IndexError, ValueError):
+        size = 0
+
+    base = {"name": posixpath.basename(target), "subpath": posixpath.normpath(subpath).strip("/"), "size": size}
+    if size > max_bytes:
+        return {**base, "truncated": True, "binary": False, "text": None}
+
+    # NUL byte check to see if binary
+    nul_check_cmd = (
+        f"head -c 1024 -- {shlex.quote(target)} | tr -d '\\0' | wc -c && "
+        f"head -c 1024 -- {shlex.quote(target)} | wc -c"
+    )
+    chk_rc, chk_out, _ = await ssh_run(host, nul_check_cmd)
+    is_binary = False
+    if chk_rc == 0:
+        chk_lines = chk_out.splitlines()
+        if len(chk_lines) >= 2:
+            try:
+                c1 = int(chk_lines[0].strip())
+                c2 = int(chk_lines[1].strip())
+                if c1 != c2:
+                    is_binary = True
+            except ValueError:
+                pass
+
+    if is_binary:
+        return {**base, "truncated": False, "binary": True, "text": None}
+
+    cat_rc, cat_out, cat_err = await ssh_run(host, f"cat -- {shlex.quote(target)}")
+    if cat_rc != 0:
+        raise ValueError(cat_err.strip() or f"failed to read file: {subpath}")
+
+    return {**base, "truncated": False, "binary": False, "text": cat_out}
+
+
+async def write_file_remote(host: str, project_dir: str, subpath: str, content: str) -> dict:
+    """Write file content on remote host."""
+    target = _remote_safe_join(project_dir, subpath)
+    parent = posixpath.dirname(target)
+    cmd = f'mkdir -p -- {shlex.quote(parent)} && cat > {shlex.quote(target)}'
+    rc, out, err = await ssh_run_with_input(host, cmd, content)
+    if rc != 0:
+        raise ValueError(err.strip() or f"failed to write file: {subpath}")
+    return {"ok": True}
+
+
+
+async def delete_file_remote(host: str, project_dir: str, subpath: str) -> dict:
+    """Delete file or directory on remote host."""
+    target = _remote_safe_join(project_dir, subpath)
+    norm = posixpath.normpath(subpath)
+    if norm in ("", ".", "/"):
+        raise ValueError("cannot delete project root directory")
+    cmd = f"rm -rf -- {shlex.quote(target)}"
+    rc, out, err = await ssh_run(host, cmd)
+    if rc != 0:
+        raise ValueError(err.strip() or f"failed to delete file/directory: {subpath}")
+    return {"ok": True}
+
+
+async def create_file_remote(host: str, project_dir: str, subpath: str, is_dir: bool = False) -> dict:
+    """Create new file or directory on remote host."""
+    target = _remote_safe_join(project_dir, subpath)
+    if is_dir:
+        cmd = f"mkdir -p -- {shlex.quote(target)}"
+    else:
+        parent = posixpath.dirname(target)
+        cmd = f'mkdir -p -- {shlex.quote(parent)} && touch -- {shlex.quote(target)}'
+    rc, out, err = await ssh_run(host, cmd)
+    if rc != 0:
+        raise ValueError(err.strip() or f"failed to create: {subpath}")
+    return {"ok": True}
+
+

harness/services/stats.py

@@ -0,0 +1,132 @@
+"""Per-turn latency and token breakdown service.
+
+Computes run statistics from timestamps and cost data, suitable for
+the `ags stats` CLI command and the `/api/v1/sessions/{id}/stats` endpoint.
+"""
+
+from __future__ import annotations
+
+import uuid
+from datetime import UTC, datetime
+
+from fastapi import HTTPException
+from sqlalchemy import func, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from harness.models.run import Run
+from harness.models.run_event import RunEvent
+from harness.models.session import Session
+
+
+def _normalize(dt: datetime | None) -> datetime | None:
+    """Normalize a datetime to be timezone-aware (UTC). If naive, assumes UTC."""
+    if dt is None:
+        return None
+    if dt.tzinfo is None:
+        return dt.replace(tzinfo=UTC)
+    return dt
+
+
+def run_stats(run: Run, first_event_ts: datetime | None) -> dict:
+    """Pure helper to compute stats for a single run.
+
+    Args:
+        run: The Run model instance.
+        first_event_ts: The timestamp of the first RunEvent for this run, or None.
+
+    Returns:
+        A dict with keys: run_id, provider, queue_ms, first_event_ms, total_ms,
+        tokens (dict with prompt/completion), resume.
+        All ms values are int or None; tokens default to 0.
+    """
+    run_created = _normalize(run.created_at)
+    run_started = _normalize(run.started_at)
+    run_finished = _normalize(run.finished_at)
+    first_event_normalized = _normalize(first_event_ts)
+
+    # Queue time: started_at - created_at
+    queue_ms = None
+    if run_started is not None and run_created is not None:
+        queue_ms = int((run_started - run_created).total_seconds() * 1000)
+
+    # First event time: first_event_ts - started_at
+    first_event_ms = None
+    if first_event_normalized is not None and run_started is not None:
+        first_event_ms = int((first_event_normalized - run_started).total_seconds() * 1000)
+
+    # Total time: finished_at - started_at
+    total_ms = None
+    if run_finished is not None and run_started is not None:
+        total_ms = int((run_finished - run_started).total_seconds() * 1000)
+
+    # Tokens from cost dict, default 0
+    tokens = {
+        "prompt": run.cost.get("prompt_tokens", 0),
+        "completion": run.cost.get("completion_tokens", 0),
+    }
+
+    # Resume mode from context_meta
+    resume = (run.context_meta or {}).get("resume")
+
+    return {
+        "run_id": str(run.id),
+        "provider": run.adapter_kind.value,
+        "queue_ms": queue_ms,
+        "first_event_ms": first_event_ms,
+        "total_ms": total_ms,
+        "tokens": tokens,
+        "resume": resume,
+    }
+
+
+async def session_stats(db: AsyncSession, session_id: uuid.UUID) -> list[dict]:
+    """Fetch per-run stats for a session.
+
+    Loads all runs for the session (ordered by created_at), then for each run
+    finds the minimum RunEvent timestamp (first event). Raises HTTPException(404)
+    if the session doesn't exist.
+
+    Args:
+        db: AsyncSession for DB queries.
+        session_id: The session ID to fetch stats for.
+
+    Returns:
+        A list of dicts (one per run) from run_stats(), in created_at order.
+
+    Raises:
+        HTTPException(404): If the session doesn't exist.
+    """
+    # Check session exists
+    sess = await db.execute(
+        select(Session).where(Session.id == session_id)
+    )
+    if sess.scalar_one_or_none() is None:
+        raise HTTPException(404, "session not found")
+
+    # Fetch all runs for the session, ordered by created_at
+    runs = (
+        await db.execute(
+            select(Run).where(Run.session_id == session_id).order_by(Run.created_at.asc())
+        )
+    ).scalars().all()
+
+    # For each run, find the first event timestamp
+    first_event_by_run = {}
+    if runs:
+        run_ids = [r.id for r in runs]
+        # Query: min(RunEvent.ts) grouped by run_id for all runs in this session
+        first_events = (
+            await db.execute(
+                select(
+                    RunEvent.run_id,
+                    func.min(RunEvent.ts).label("first_ts"),
+                ).where(RunEvent.run_id.in_(run_ids)).group_by(RunEvent.run_id)
+            )
+        ).all()
+        first_event_by_run = {rid: ts for rid, ts in first_events}
+
+    # Build stats for each run
+    return [
+        run_stats(r, first_event_by_run.get(r.id))
+        for r in runs
+    ]

harness/services/tasks.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+import uuid
+
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from harness.models.task import Task
+from harness.observability.audit import write_audit
+from harness.schemas.task import TaskCreate
+from harness.services.workspaces import get_or_create_workspace
+
+
+async def create_task(db: AsyncSession, payload: TaskCreate, *, actor: str = "cli") -> Task:
+    ws = await get_or_create_workspace(db, payload.workspace)
+    task = Task(
+        workspace_id=ws.id,
+        title=payload.title,
+        objective=payload.objective,
+        constraints=payload.constraints,
+        created_by=actor,
+    )
+    db.add(task)
+    await db.flush()
+    await write_audit(
+        db, actor=actor, action="task.create", target_type="task",
+        target_id=str(task.id), after={"title": task.title, "workspace": payload.workspace},
+    )
+    return task
+
+
+async def get_task(db: AsyncSession, task_id: uuid.UUID) -> Task | None:
+    return (await db.execute(select(Task).where(Task.id == task_id))).scalar_one_or_none()
+
+
+async def list_tasks(db: AsyncSession, *, limit: int = 50) -> list[Task]:
+    return list(
+        (
+            await db.execute(select(Task).order_by(Task.created_at.desc()).limit(limit))
+        ).scalars()
+    )

harness/services/workspaces.py

@@ -0,0 +1,184 @@
+from __future__ import annotations
+
+import os
+
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from harness.models.enums import TrustPolicy
+from harness.models.workspace import Workspace
+from harness.observability.audit import write_audit
+from harness.security.permissions import write_mode_enabled
+
+
+async def get_workspace_by_slug(db: AsyncSession, slug: str) -> Workspace | None:
+    return (
+        await db.execute(select(Workspace).where(Workspace.slug == slug))
+    ).scalar_one_or_none()
+
+
+async def get_or_create_workspace(
+    db: AsyncSession, slug: str, *, name: str | None = None,
+    trust_policy: TrustPolicy = TrustPolicy.restricted,
+) -> Workspace:
+    ws = await get_workspace_by_slug(db, slug)
+    if ws is None:
+        ws = Workspace(slug=slug, name=name or slug.title(), trust_policy=trust_policy)
+        db.add(ws)
+        await db.flush()
+    return ws
+
+
+# ── Project folder + plan/write mode (per-workspace runtime settings) ─────────
+# Stored in ``workspace.settings`` so a change takes effect on the next run with no
+# restart. Both fall back to the process defaults (cwd / HARNESS_WRITE) when unset.
+
+def _mode_label(write_mode: bool) -> str:
+    return "write (agents can edit files)" if write_mode else "read-only (plan)"
+
+
+def _resolve_existing_dir(path: str) -> str:
+    resolved = os.path.abspath(os.path.expanduser(path))
+    if not os.path.isdir(resolved):
+        raise ValueError(f"not a directory: {resolved}")
+    return resolved
+
+
+def browse_dirs(path: str | None, *, strict: bool = False) -> dict:
+    """List the immediate subdirectories of ``path`` (default: home) for the GUI
+    folder picker — directory *names* only, never file contents. Sync so it stays
+    off the async hot path. ``strict`` raises instead of falling back to home when
+    ``path`` isn't a directory — autocomplete needs the error, the picker needs
+    the fallback."""
+    base = os.path.abspath(os.path.expanduser(path)) if path else os.path.expanduser("~")
+    if not os.path.isdir(base):
+        if strict:
+            raise ValueError(f"not a directory: {base}")
+        base = os.path.expanduser("~")
+    dirs: list[str] = []
+    try:
+        for entry in os.scandir(base):
+            if not entry.name.startswith(".") and entry.is_dir():
+                dirs.append(entry.name)
+    except OSError:
+        pass
+    dirs.sort(key=str.lower)
+    parent = os.path.dirname(base)
+    return {"path": base, "parent": parent if parent != base else None, "dirs": dirs}
+
+
+def effective_host(settings: dict) -> str | None:
+    """The ssh host a workspace's project lives on, or None for a local project."""
+    return settings.get("project_host") or None
+
+
+def effective_project(settings: dict) -> tuple[str, bool]:
+    """Resolve the (project_dir, write_mode) a run should use from a workspace's
+    settings, falling back to the process cwd and the HARNESS_WRITE env default."""
+    project_dir = settings.get("project_dir") or os.getcwd()
+    write_mode = settings.get("write_mode")
+    if write_mode is None:
+        write_mode = write_mode_enabled()
+    return project_dir, bool(write_mode)
+
+
+def effective_default_workspace_mode(workspace_settings: dict) -> str:
+    """The isolation mode NEW sessions get when the request doesn't choose:
+    workspace setting → HARNESS_WORKSPACE_MODE_DEFAULT env → private worktree."""
+    return (
+        workspace_settings.get("default_workspace_mode")
+        or os.environ.get("HARNESS_WORKSPACE_MODE_DEFAULT", "worktree")
+    )
+
+
+def effective_write_mode(session_settings: dict, workspace_settings: dict) -> bool:
+    """Resolve the write_mode a run should use: the session's own ``write_mode``
+    override when set, else the workspace default (which itself falls back to
+    the HARNESS_WRITE env default via ``effective_project``)."""
+    session_mode = session_settings.get("write_mode")
+    if session_mode is not None:
+        return bool(session_mode)
+    return effective_project(workspace_settings)[1]
+
+
+async def get_project_settings(db: AsyncSession, slug: str) -> dict:
+    ws = await get_workspace_by_slug(db, slug)
+    settings = (ws.settings if ws else None) or {}
+    project_dir, write_mode = effective_project(settings)
+    return {
+        "workspace": slug,
+        "project_dir": project_dir,
+        "project_host": effective_host(settings),
+        "write_mode": write_mode,
+        "mode": _mode_label(write_mode),
+        "default_workspace_mode": effective_default_workspace_mode(settings),
+        "remote_hosts": settings.get("remote_hosts", []),
+    }
+
+
+def _normalize_remote_hosts(entries: list[dict], validate_host) -> list[dict]:
+    """Validate + de-dupe a saved-hosts address book. Each entry is
+    ``{label, host}``; the host is validated (raises ValueError on a bad value) and
+    duplicates (by host) are dropped. Labels are optional free text, trimmed."""
+    normalized: list[dict] = []
+    seen: set[str] = set()
+    for entry in entries or []:
+        host = validate_host(str((entry or {}).get("host", "")))
+        if host in seen:
+            continue
+        label = str((entry or {}).get("label", "")).strip()[:80]
+        normalized.append({"label": label, "host": host})
+        seen.add(host)
+    return normalized
+
+
+async def set_project_settings(
+    db: AsyncSession, slug: str, *, project_dir: str | None = None,
+    project_host: str | None = None, write_mode: bool | None = None,
+    default_workspace_mode: str | None = None,
+    remote_hosts: list[dict] | None = None, actor: str = "cli",
+) -> dict:
+    """Update a workspace's project folder, remote host, mode, and/or saved-host
+    address book. ``project_dir`` is validated to be an existing directory — locally,
+    or over ssh when the (possibly just-set) ``project_host`` is present.
+    ``project_host=""`` clears the host (back to local); ``None`` leaves it unchanged.
+    ``remote_hosts`` (when given) replaces the whole saved list. Audited."""
+    from harness.services.ssh import remote_is_dir, validate_host
+
+    ws = await get_or_create_workspace(db, slug)
+    settings = dict(ws.settings or {})
+    before = {"project_dir": settings.get("project_dir"),
+              "project_host": settings.get("project_host"),
+              "write_mode": settings.get("write_mode"),
+              "default_workspace_mode": settings.get("default_workspace_mode"),
+              "remote_hosts": settings.get("remote_hosts")}
+    if remote_hosts is not None:
+        settings["remote_hosts"] = _normalize_remote_hosts(remote_hosts, validate_host)
+    if project_host is not None:  # host first: dir validation depends on it
+        settings["project_host"] = validate_host(project_host) if project_host else None
+    if project_dir is not None:
+        host = effective_host(settings)
+        if host:
+            if not await remote_is_dir(host, project_dir):
+                raise ValueError(f"not a directory on {host}: {project_dir}")
+            settings["project_dir"] = project_dir  # remote POSIX path, stored as-is
+        else:
+            settings["project_dir"] = _resolve_existing_dir(project_dir)
+    if write_mode is not None:
+        settings["write_mode"] = bool(write_mode)
+    if default_workspace_mode is not None:
+        if default_workspace_mode not in ("main", "worktree"):
+            raise ValueError("default_workspace_mode must be 'main' or 'worktree'")
+        settings["default_workspace_mode"] = default_workspace_mode
+    ws.settings = settings  # reassign so SQLAlchemy flags the JSONB column dirty
+    await db.flush()
+    after = {"project_dir": settings.get("project_dir"),
+             "project_host": settings.get("project_host"),
+             "write_mode": settings.get("write_mode"),
+             "default_workspace_mode": settings.get("default_workspace_mode"),
+             "remote_hosts": settings.get("remote_hosts")}
+    await write_audit(
+        db, actor=actor, action="set_project", target_type="workspace", target_id=slug,
+        before=before, after=after,
+    )
+    return await get_project_settings(db, slug)