ags-cli 0.1.0__py3-none-any.whl

harness/services/worktrees.py

@@ -0,0 +1,439 @@
+"""Per-session private workspaces: one git worktree + branch per session.
+
+An isolated session runs in its own worktree under ``~/.ags/worktrees/<workspace>/
+<session-hex12>`` on branch ``ags/session/<hex12>``, based on whatever branch the
+project dir had checked out when the worktree was created. Changes flow back via
+an explicit merge (``merge_session_worktree``) — never automatically. All git
+work runs sync in a thread (same pattern as ``orchestrator/snapshot.py``).
+
+Session bookkeeping lives in ``Session.settings``: ``workspace_mode``
+("main"|"worktree"), ``worktree_path``, ``worktree_branch``, ``worktree_base``,
+``worktree_fallback_reason``, ``merged_at``, ``merge_commit``."""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import shutil
+import subprocess
+import uuid
+from datetime import UTC, datetime
+from pathlib import Path
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from harness.models.session import Session
+from harness.models.workspace import Workspace
+from harness.observability.audit import write_audit
+from harness.observability.logging import get_logger
+from harness.settings import HOME_DIR
+
+log = get_logger("worktrees")
+
+_GIT_TIMEOUT = 60
+
+
+class _GitError(RuntimeError):
+    pass
+
+
+def worktrees_root() -> Path:
+    """Root directory holding all session worktrees. Overridable for tests."""
+    override = os.environ.get("HARNESS_WORKTREES_DIR")
+    return Path(override) if override else HOME_DIR / "worktrees"
+
+
+def branch_name(session_id: uuid.UUID) -> str:
+    return f"ags/session/{session_id.hex[:12]}"
+
+
+def worktree_dir(workspace_slug: str, session_id: uuid.UUID) -> Path:
+    return worktrees_root() / workspace_slug / session_id.hex[:12]
+
+
+def _git(cwd: str | Path, *args: str) -> str:
+    r = subprocess.run(["git", *args], cwd=cwd, capture_output=True, text=True,
+                       timeout=_GIT_TIMEOUT)
+    if r.returncode != 0:
+        raise _GitError((r.stderr.strip() or r.stdout.strip())[:500])
+    return r.stdout.strip()
+
+
+def is_git_repo(project_dir: str) -> bool:
+    return (Path(project_dir) / ".git").exists()
+
+
+async def _save_settings(db: AsyncSession, sess: Session, updates: dict) -> None:
+    settings = dict(sess.settings or {})
+    settings.update(updates)
+    # Drop keys explicitly cleared with None.
+    for k in [k for k, v in settings.items() if v is None]:
+        settings.pop(k)
+    sess.settings = settings  # reassign so SQLAlchemy flags the JSON column dirty
+    await db.flush()
+
+
+# ── creation ──────────────────────────────────────────────────────────────────
+
+def _ensure_sync(project_dir: str, path: Path, branch: str) -> tuple[str, str, bool]:
+    """Create (or re-attach) the worktree. Returns (path, base_branch, reattached)."""
+    try:
+        base = _git(project_dir, "symbolic-ref", "--short", "HEAD")
+    except _GitError as exc:
+        raise _GitError(f"detached or unborn HEAD in {project_dir}: {exc}") from exc
+    # HEAD must resolve to a commit (an unborn branch cannot back a worktree).
+    _git(project_dir, "rev-parse", "--verify", "HEAD")
+
+    path.parent.mkdir(parents=True, exist_ok=True)
+    _git(project_dir, "worktree", "prune")  # clear stale registrations first
+    branch_exists = bool(
+        subprocess.run(["git", "rev-parse", "--verify", "--quiet", branch],
+                       cwd=project_dir, capture_output=True, timeout=_GIT_TIMEOUT
+                       ).returncode == 0
+    )
+    if branch_exists:
+        # Re-attach: the branch survived (e.g. dir was deleted); keep its history.
+        _git(project_dir, "worktree", "add", str(path), branch)
+    else:
+        _git(project_dir, "worktree", "add", "-b", branch, str(path), base)
+    return str(path), base, branch_exists
+
+
+async def ensure_worktree(
+    db: AsyncSession, *, session: Session, workspace: Workspace, project_dir: str,
+    project_host: str | None = None,
+) -> tuple[str, str] | None:
+    """Idempotently provision the session's private worktree.
+
+    Returns (worktree_path, branch) — or None when the session runs in main
+    mode, including a one-time downgrade (recorded in
+    ``worktree_fallback_reason``) when the project can't support worktrees
+    (remote host, non-git dir, git failure)."""
+    settings = session.settings or {}
+    if settings.get("workspace_mode") == "main":
+        return None
+
+    recorded_path = settings.get("worktree_path")
+    branch = settings.get("worktree_branch") or branch_name(session.id)
+    if recorded_path and Path(recorded_path).is_dir():
+        return recorded_path, branch
+
+    reason: str | None = None
+    if project_host:
+        reason = "private workspaces are local-only; project lives on a remote host"
+    elif not is_git_repo(project_dir):
+        reason = f"not a git repository: {project_dir}"
+    if reason:
+        await _save_settings(db, session, {
+            "workspace_mode": "main", "worktree_fallback_reason": reason,
+        })
+        log.warning("worktree_fallback_main", session_id=str(session.id), reason=reason)
+        return None
+
+    path = Path(recorded_path) if recorded_path else worktree_dir(workspace.slug, session.id)
+    try:
+        wt_path, base, reattached = await asyncio.to_thread(
+            _ensure_sync, project_dir, path, branch
+        )
+    except (_GitError, subprocess.TimeoutExpired, OSError) as exc:
+        reason = f"worktree creation failed: {exc}"
+        await _save_settings(db, session, {
+            "workspace_mode": "main", "worktree_fallback_reason": reason,
+        })
+        log.warning("worktree_fallback_main", session_id=str(session.id), reason=reason)
+        return None
+
+    # A re-attached branch keeps its recorded base; a freshly created branch is
+    # based on whatever is checked out NOW — record that, or a later merge would
+    # target a stale base branch.
+    recorded_base = (session.settings or {}).get("worktree_base")
+    await _save_settings(db, session, {
+        "workspace_mode": "worktree",
+        "worktree_path": wt_path,
+        "worktree_branch": branch,
+        "worktree_base": (recorded_base if reattached and recorded_base else base),
+    })
+    await write_audit(
+        db, actor="engine", action="session.worktree_create", target_type="session",
+        target_id=str(session.id), after={"path": wt_path, "branch": branch, "base": base},
+    )
+    return wt_path, branch
+
+
+# ── status ────────────────────────────────────────────────────────────────────
+
+def _status_sync(wt: str, base: str) -> dict:
+    dirty_lines = _git(wt, "status", "--porcelain")
+    changed: set[str] = set()
+    # Committed changes vs the merge-base (three-dot): commits landed on the base
+    # branch AFTER the worktree branched off must not show up as session changes.
+    try:
+        changed.update(
+            f for f in _git(wt, "diff", "--name-only", f"{base}...HEAD").splitlines() if f
+        )
+    except _GitError:
+        pass
+    # ...plus uncommitted work: modified/staged tracked files and untracked files.
+    for line in dirty_lines.splitlines():
+        # porcelain v1: 2-char XY status, then the path ("old -> new" on renames).
+        name = line[2:].strip().split(" -> ")[-1].strip('"')
+        if name:
+            changed.add(name)
+    try:
+        behind_ahead = _git(wt, "rev-list", "--left-right", "--count", f"{base}...HEAD")
+        behind, ahead = (int(x) for x in behind_ahead.split())
+    except (_GitError, ValueError):
+        behind = ahead = 0
+    return {
+        "dirty": bool(dirty_lines),
+        "changed_files": sorted(changed),
+        "ahead": ahead,
+        "behind": behind,
+    }
+
+
+async def worktree_status(db: AsyncSession, session_id: uuid.UUID) -> dict:
+    """The session's workspace isolation state, for the GUI badge / CLI status."""
+    from harness.services.sessions import get_session
+
+    sess = await get_session(db, session_id)
+    if sess is None:
+        raise ValueError("session not found")
+    settings = sess.settings or {}
+    mode = settings.get("workspace_mode") or (
+        "worktree" if settings.get("worktree_path") else "main"
+    )
+    out = {
+        "workspace_mode": mode,
+        "path": settings.get("worktree_path"),
+        "branch": settings.get("worktree_branch"),
+        "base": settings.get("worktree_base"),
+        "exists": False,
+        "dirty": False,
+        "changed_files": [],
+        "ahead": 0,
+        "behind": 0,
+        "merged_at": settings.get("merged_at"),
+        "merge_commit": settings.get("merge_commit"),
+        "fallback_reason": settings.get("worktree_fallback_reason"),
+    }
+    wt, base = out["path"], out["base"]
+    if mode != "worktree" or not wt or not Path(wt).is_dir():
+        return out
+    out["exists"] = True
+    try:
+        out.update(await asyncio.to_thread(_status_sync, wt, base or "HEAD"))
+    except (subprocess.TimeoutExpired, _GitError, OSError) as exc:
+        log.warning("worktree_status_failed", session_id=str(session_id), error=str(exc))
+    return out
+
+
+# ── merge-back ────────────────────────────────────────────────────────────────
+
+def _main_checkout_of(wt: str) -> str:
+    """The primary checkout a worktree belongs to (parent of its common .git dir).
+    Derived from the worktree itself so it stays correct even if the workspace's
+    project_dir setting changed after the worktree was created."""
+    common = _git(wt, "rev-parse", "--path-format=absolute", "--git-common-dir")
+    return str(Path(common).parent)
+
+
+def _merge_sync(
+    project_dir: str, wt: str, branch: str, base: str, *, squash: bool, message: str,
+) -> dict:
+    # 1. The main checkout must be clean and on the base branch — a merge mutates
+    #    it. Validate FIRST so a refused merge leaves the worktree untouched too.
+    if _git(project_dir, "status", "--porcelain"):
+        raise ValueError(
+            f"project checkout has uncommitted (dirty) changes; commit or stash "
+            f"them in {project_dir} first"
+        )
+    current = _git(project_dir, "symbolic-ref", "--short", "HEAD")
+    if current != base:
+        raise ValueError(
+            f"project checkout is on branch '{current}' but the session is based "
+            f"on '{base}'; check out '{base}' first"
+        )
+
+    # 2. Auto-commit the worktree — agents usually leave changes uncommitted.
+    if _git(wt, "status", "--porcelain"):
+        _git(wt, "add", "-A")
+        _git(wt, "-c", "user.name=ags-harness", "-c", "user.email=ags@localhost",
+             "commit", "-m", "ags: session work (auto-committed at merge)")
+
+    # 3. Anything to merge at all?
+    ahead = int(_git(project_dir, "rev-list", "--count", f"{base}..{branch}") or "0")
+    if ahead == 0:
+        return {"merged": False, "nothing_to_merge": True, "commit": None,
+                "conflicts": [], "reason": "session branch has no new commits"}
+
+    # 4. Merge (never leave a conflicted tree behind).
+    try:
+        if squash:
+            _git(project_dir, "merge", "--squash", branch)
+            _git(project_dir, "-c", "user.name=ags-harness",
+                 "-c", "user.email=ags@localhost", "commit", "-m", message)
+        else:
+            _git(project_dir, "-c", "user.name=ags-harness",
+                 "-c", "user.email=ags@localhost",
+                 "merge", "--no-ff", branch, "-m", message)
+    except _GitError as exc:
+        try:
+            conflicts = [
+                f for f in _git(project_dir, "diff", "--name-only",
+                                "--diff-filter=U").splitlines() if f
+            ]
+        except _GitError:
+            conflicts = []
+        for abort in (("merge", "--abort"), ("reset", "--merge")):
+            try:
+                _git(project_dir, *abort)
+                break
+            except _GitError:
+                continue
+        return {"merged": False, "nothing_to_merge": False, "commit": None,
+                "conflicts": conflicts, "reason": str(exc)}
+
+    commit = _git(project_dir, "rev-parse", "HEAD")
+    return {"merged": True, "nothing_to_merge": False, "commit": commit,
+            "conflicts": [], "reason": None}
+
+
+async def merge_session_worktree(
+    db: AsyncSession, session_id: uuid.UUID, *,
+    squash: bool = False, delete_worktree: bool = False,
+    message: str | None = None, actor: str = "api",
+) -> dict:
+    """Merge the session branch back into its base branch in the main checkout.
+
+    Auto-commits pending worktree changes first. Raises ValueError for
+    user-fixable refusals (main-mode session, missing worktree, dirty main,
+    wrong branch checked out); returns ``merged=False`` with a ``conflicts``
+    list when the merge itself conflicts (already aborted)."""
+    from harness.services.sessions import get_session
+
+    sess = await get_session(db, session_id)
+    if sess is None:
+        raise ValueError("session not found")
+    # Refuse while a run is executing in this session's worktree — merging would
+    # auto-commit and land a half-written tree on the base branch.
+    from harness.workers.inprocess import _session_lock
+
+    if _session_lock(session_id).locked():
+        raise ValueError("a run is still executing in this session; wait for it to finish")
+    settings = sess.settings or {}
+    if settings.get("workspace_mode") != "worktree":
+        raise ValueError("session runs directly in the main project (no private worktree)")
+    wt, branch, base = (settings.get("worktree_path"), settings.get("worktree_branch"),
+                        settings.get("worktree_base"))
+    if not (wt and branch and base) or not Path(wt).is_dir():
+        raise ValueError("session worktree does not exist (nothing to merge)")
+
+    try:
+        project_dir = await asyncio.to_thread(_main_checkout_of, wt)
+    except (_GitError, subprocess.TimeoutExpired) as exc:
+        raise ValueError(f"cannot locate the main checkout for the worktree: {exc}") from exc
+
+    msg = message or f"Merge session {session_id.hex[:12]} ({sess.canonical_objective[:60]})"
+    try:
+        out = await asyncio.to_thread(
+            _merge_sync, project_dir, wt, branch, base, squash=squash, message=msg,
+        )
+    except (subprocess.TimeoutExpired, _GitError) as exc:
+        raise ValueError(f"merge failed: {exc}") from exc
+
+    if out["merged"]:
+        await _save_settings(db, sess, {
+            "merged_at": datetime.now(UTC).isoformat(), "merge_commit": out["commit"],
+        })
+        await write_audit(
+            db, actor=actor, action="session.worktree_merge", target_type="session",
+            target_id=str(session_id),
+            after={"commit": out["commit"], "squash": squash, "branch": branch},
+        )
+        if delete_worktree:
+            await remove_worktree(db, session_id, delete_branch=True, actor=actor)
+    return out
+
+
+# ── removal / cleanup ─────────────────────────────────────────────────────────
+
+def _remove_sync(project_dir: str | None, wt: str, branch: str | None,
+                 delete_branch: bool) -> None:
+    repo = project_dir if project_dir and is_git_repo(project_dir) else None
+    if repo:
+        try:
+            _git(repo, "worktree", "remove", "--force", wt)
+        except _GitError:
+            shutil.rmtree(wt, ignore_errors=True)
+        try:
+            _git(repo, "worktree", "prune")
+        except _GitError:
+            pass
+        if delete_branch and branch:
+            try:
+                _git(repo, "branch", "-D", branch)
+            except _GitError:
+                pass
+    else:
+        shutil.rmtree(wt, ignore_errors=True)
+
+
+async def remove_worktree(
+    db: AsyncSession, session_id: uuid.UUID, *,
+    delete_branch: bool = False, actor: str = "api",
+) -> bool:
+    """Discard a session's worktree (fail-soft). The branch is kept unless
+    ``delete_branch`` — an unmerged branch is the safety net for declined merges."""
+    from harness.services.sessions import get_session
+
+    sess = await get_session(db, session_id)
+    if sess is None:
+        return False
+    settings = sess.settings or {}
+    wt = settings.get("worktree_path")
+    if not wt:
+        return False
+    try:
+        project_dir: str | None = (
+            await asyncio.to_thread(_main_checkout_of, wt) if Path(wt).is_dir() else None
+        )
+    except (_GitError, subprocess.TimeoutExpired):
+        project_dir = None
+    try:
+        await asyncio.to_thread(
+            _remove_sync, project_dir, wt, settings.get("worktree_branch"), delete_branch,
+        )
+    except (subprocess.TimeoutExpired, OSError) as exc:
+        log.warning("worktree_remove_failed", session_id=str(session_id), error=str(exc))
+    await _save_settings(db, sess, {
+        "worktree_path": None,
+        **({"worktree_branch": None} if delete_branch else {}),
+    })
+    await write_audit(
+        db, actor=actor, action="session.worktree_remove", target_type="session",
+        target_id=str(session_id), after={"deleted_branch": delete_branch},
+    )
+    return True
+
+
+async def prune_orphan_worktrees(db: AsyncSession) -> dict:
+    """Sweep the worktrees root for directories whose session no longer exists."""
+    from sqlalchemy import select
+
+    root = worktrees_root()
+    if not root.is_dir():
+        return {"removed": 0}
+    known = {
+        s.hex[:12]
+        for s in (await db.execute(select(Session.id))).scalars()
+    }
+    removed = 0
+    for ws_dir in root.iterdir():
+        if not ws_dir.is_dir():
+            continue
+        for wt in ws_dir.iterdir():
+            if wt.is_dir() and wt.name not in known:
+                shutil.rmtree(wt, ignore_errors=True)
+                removed += 1
+    return {"removed": removed}

harness/settings.py

@@ -0,0 +1,186 @@
+"""Application settings: environment variables merged with `config.yaml`.
+
+Precedence: environment variables (secrets, URLs) override the YAML file; the
+YAML file owns declarative structure (workspaces, providers, routing, memory,
+safety). Secrets never live in YAML — only `secret_ref` pointers.
+"""
+
+from __future__ import annotations
+
+import functools
+from pathlib import Path
+from typing import Any, Literal
+
+import yaml
+from dotenv import find_dotenv, load_dotenv
+from pydantic import model_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+Env = Literal["dev", "test", "prod"]
+AuthProviderName = Literal["local", "oidc"]
+EmbeddingProviderName = Literal["auto", "hash", "openai_compatible", "fastembed"]
+
+# Daemonless state lives under the user's home, not the repo, so an installed
+# `ags` (via `uv tool install`) works from any directory.
+HOME_DIR = Path.home() / ".ags"
+# GUI-managed providers, one YAML file each, merged into config["providers"].
+PROVIDERS_DIR = HOME_DIR / "providers.d"
+# GUI-managed MCP servers, one YAML file each, merged into config["mcp"]["servers"].
+MCP_DIR = HOME_DIR / "mcp.d"
+
+
+def _merge_overlay(base: list[dict], overlay_dir: Path) -> list[dict]:
+    """Append ``<overlay_dir>/*.yaml`` entries to ``base``, skipping any name already
+    declared in config.yaml (config.yaml wins)."""
+    names = {p.get("name") for p in base}
+    merged = list(base)
+    if overlay_dir.is_dir():
+        for f in sorted(overlay_dir.glob("*.yaml")):
+            try:
+                entry = yaml.safe_load(f.read_text())
+            except yaml.YAMLError:
+                continue
+            if isinstance(entry, dict) and entry.get("name") and entry["name"] not in names:
+                merged.append(entry)
+                names.add(entry["name"])
+    return merged
+
+
+def _merge_overlay_providers(base: list[dict]) -> list[dict]:
+    return _merge_overlay(base, PROVIDERS_DIR)
+
+
+def _merge_overlay_mcp_servers(base: list[dict]) -> list[dict]:
+    return _merge_overlay(base, MCP_DIR)
+
+
+def _load_env_files() -> None:
+    """Load ``.env`` into the process environment so provider ``secret_ref: env:X``
+    pointers resolve (the CLI/server run as plain processes — nothing else loads
+    ``.env`` into ``os.environ``; pydantic-settings' ``env_file`` only
+    populates this class's own fields). Shell-exported vars win (``override=False``); a
+    project-local ``.env`` (from the CWD upward) takes precedence over the per-user
+    ``~/.ags/.env`` fallback."""
+    load_dotenv(find_dotenv(usecwd=True), override=False)
+    load_dotenv(HOME_DIR / ".env", override=False)
+
+
+_load_env_files()
+
+
+class Settings(BaseSettings):
+    """Process-wide configuration loaded from the `HARNESS_` env namespace."""
+
+    model_config = SettingsConfigDict(
+        env_prefix="HARNESS_",
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+    env: Env = "dev"
+    log_level: str = "INFO"
+    log_json: bool = True
+
+    # API
+    api_host: str = "0.0.0.0"
+    api_port: int = 8080
+    api_base_url: str = "http://localhost:8080"
+    config_file: str = "config.yaml"
+
+    # Datastore. Left blank so the default (see _resolve_datastores) applies unless
+    # the operator overrides it via HARNESS_DATABASE_URL.
+    database_url: str = ""
+
+    # Auth
+    auth_provider: AuthProviderName = "local"
+    auth_secret: str = "change-me"
+    local_admin_user: str = "admin"
+    local_admin_password: str = "admin"
+    oidc_issuer: str = ""
+    oidc_client_id: str = ""
+    oidc_client_secret: str = ""
+
+    # Embeddings
+    embedding_provider: EmbeddingProviderName = "auto"
+    embedding_dim: int = 768
+    embedding_base_url: str = "http://localhost:11434/v1"
+    embedding_api_key: str = ""
+    embedding_model: str = "nomic-embed-text"
+
+    # Observability
+    otel_enabled: bool = False
+    otel_exporter_otlp_endpoint: str = "http://localhost:4317"
+
+    # Safety
+    read_only: bool = False
+    dry_run: bool = False
+
+    # Per-run wall-clock deadline (seconds). A hung / non-responding adapter is cancelled
+    # and the run fails cleanly instead of hanging. Generous by default so a slow-but-working
+    # agent (large-repo agy, slow local LLM) isn't killed; lower it for snappier failure.
+    run_timeout_s: int = 900
+
+    # Fail a run if the adapter emits no events for this long (0 = disabled).
+    # Catches adapters that start but then silently wedge mid-run, without waiting
+    # for the full wall-clock deadline.
+    stall_timeout_s: int = 180
+
+    # Retention policy: auto-compact sessions older than this many days on startup.
+    # 0 (default) disables automatic compaction. When enabled, token and tool_result
+    # events are purged from terminal sessions older than the horizon; the structured
+    # transcript artifact (written by _persist_artifacts) serves as the archive.
+    retention_days: int = 0
+
+    # Experimental: keep a warm (long-lived) claude process per active session so
+    # the CLI's KV cache is reused across turns, reducing turn-2+ latency.
+    # Disabled by default. Enable with HARNESS_WARM_CLI=1.
+    warm_cli: bool = False
+
+    _config_cache: dict[str, Any] | None = None
+
+    @model_validator(mode="after")
+    def _resolve_datastores(self) -> Settings:
+        """Resolve the database URL.
+
+        Always SQLite under ``~/.ags``: a non-sqlite ``HARNESS_DATABASE_URL`` (e.g. a
+        stale ``.env`` in the CWD) is ignored, so the daemonless install never loads
+        asyncpg or dials Postgres. An explicit *sqlite* URL is still honored for a
+        custom local path."""
+        if not self.database_url or not self.database_url.startswith("sqlite"):
+            HOME_DIR.mkdir(parents=True, exist_ok=True)
+            self.database_url = f"sqlite+aiosqlite:///{HOME_DIR / 'harness.db'}"
+        return self
+
+    def config(self) -> dict[str, Any]:
+        """Parsed `config.yaml` (cached), with GUI-managed providers merged in.
+
+        Falls back to ``~/.ags/config.yaml`` (written by ``ags init``) when
+        the configured path is absent — so an installed CLI works outside the repo.
+        Providers added from the GUI live as ``~/.ags/providers.d/*.yaml`` and are
+        appended here, so the seed treats them like config.yaml entries (kept, not
+        pruned) without ever rewriting the user's commented config.yaml."""
+        if self._config_cache is None:
+            path = Path(self.config_file).expanduser()
+            if not path.exists():
+                home_cfg = HOME_DIR / "config.yaml"
+                if home_cfg.exists():
+                    path = home_cfg
+            cfg = (yaml.safe_load(path.read_text()) if path.exists() else {}) or {}
+            cfg["providers"] = _merge_overlay_providers(cfg.get("providers") or [])
+            mcp = cfg.get("mcp") or {}
+            mcp["servers"] = _merge_overlay_mcp_servers(mcp.get("servers") or [])
+            cfg["mcp"] = mcp
+            self._config_cache = cfg
+        return self._config_cache
+
+    def reset_config_cache(self) -> None:
+        """Drop the cached config so the next ``config()`` re-reads disk (e.g. after a
+        provider is added/removed from the GUI overlay)."""
+        self._config_cache = None
+
+
+@functools.lru_cache
+def get_settings() -> Settings:
+    """Cached singleton accessor used across DI and workers."""
+    return Settings()

harness/skills/__init__.py

@@ -0,0 +1,11 @@
+"""Harness-managed skill library for spawned CLI agents. See :mod:`harness.skills.manager`."""
+
+from harness.skills.manager import (
+    Skill,
+    discover,
+    index_for,
+    index_text,
+    provision_config_home,
+)
+
+__all__ = ["Skill", "discover", "index_for", "index_text", "provision_config_home"]