sembl-stack 0.1.0__py3-none-any.whl

sembl_stack/rsi.py

@@ -0,0 +1,188 @@
+"""RSI-L1 readout — measured selection over the run store (north-star first rung).
+
+The north star (docs/process-self-improvement.md) climbs L0 (manual swap) -> L1 (measured
+selection): pick executors on RECORDED signal, not vibes. This module is that signal,
+aggregated: per executor, over every run recorded in `.sembl/runs/`, how often the loop
+went green, in how many iterations, and at what cost.
+
+Honesty rules [LOCKED]:
+  * everything here is read back from run-store artifacts the loop already persisted —
+    nothing is estimated, sampled, or modeled;
+  * cost/tokens appear ONLY when the executor adapter reported usage (the C1.3
+    `attempts_log` hook in `loop.py`); runs recorded before an adapter reported usage
+    show "not yet recorded" — never an invented number;
+  * "green" = the loop accepted the run (final PASS or WARN; WARN is counted separately
+    so a WARN-heavy executor can't hide). iterations-to-green = the first attempt whose
+    verdict the loop accepted.
+
+Pure and headless: no Textual, no click — `cli.py rsi` renders it.
+"""
+from __future__ import annotations
+
+from .store import RunStore
+
+GREEN = ("PASS", "WARN")          # statuses the loop accepts (WARN = accepted-with-caveat)
+UNKNOWN_EXECUTOR = "(unrecorded)"  # runs whose attempts_log never named an agent
+
+
+# --- per-run extraction ---------------------------------------------------------
+
+def run_record(run) -> dict | None:
+    """One run's manifest+artifacts distilled into the RSI row. None if no manifest."""
+    m = run.manifest()
+    if not m:
+        return None
+    log = m.get("attempts_log", []) or []
+    agent = next((e.get("agent") for e in log if e.get("agent")), None) or UNKNOWN_EXECUTOR
+    models = sorted({e["model"] for e in log if e.get("model")})
+    status = m.get("status", "?")
+    attempts = m.get("attempts")
+    if not isinstance(attempts, int) or attempts < 1:
+        attempts = len(log) or None
+
+    tokens = [e["tokens"] for e in log if isinstance(e.get("tokens"), (int, float))]
+    costs = [e["cost"] for e in log if isinstance(e.get("cost"), (int, float))]
+    latency = m.get("total_latency_s")
+    if not isinstance(latency, (int, float)):
+        lat = [e["latency_s"] for e in log if isinstance(e.get("latency_s"), (int, float))]
+        latency = round(sum(lat), 3) if lat else None
+
+    return {
+        "id": m.get("id", run.id),
+        "agent": agent,
+        "models": models,
+        "status": status,
+        "attempts": attempts,
+        "iters_to_green": _iters_to_green(run, status, attempts),
+        "latency_s": latency,
+        "tokens": sum(tokens) if tokens else None,
+        "cost": round(sum(costs), 6) if costs else None,
+    }
+
+
+def _iters_to_green(run, status: str, attempts: int | None) -> int | None:
+    """First attempt whose verdict the loop accepted (PASS/WARN), from the per-attempt
+    verdict artifacts; falls back to the manifest attempt count when the per-attempt
+    verdicts are missing but the run ended green (the loop stops at the first accept,
+    so the two agree by construction). None when the run never went green."""
+    if attempts:
+        for i in range(1, attempts + 1):
+            v = run.get(f"verdict-{i}")
+            if v is not None and getattr(v, "status", None) in GREEN:
+                return i
+    if status in GREEN and attempts:
+        return attempts
+    return None
+
+
+# --- aggregation -----------------------------------------------------------------
+
+def aggregate(store: RunStore) -> dict:
+    """Group every recorded run by executor and compute the RSI-L1 measures."""
+    rows = []
+    for rid in store.list_runs():
+        rec = run_record(store.open(rid))
+        if rec is not None:
+            rows.append(rec)
+
+    groups: dict[str, list[dict]] = {}
+    for r in rows:
+        groups.setdefault(r["agent"], []).append(r)
+
+    executors = []
+    for agent in sorted(groups):
+        rs = groups[agent]
+        n = len(rs)
+        n_pass = sum(1 for r in rs if r["status"] == "PASS")
+        n_warn = sum(1 for r in rs if r["status"] == "WARN")
+        n_block = sum(1 for r in rs if r["status"] == "BLOCK")
+        n_other = n - n_pass - n_warn - n_block          # failed / started / unknown
+        iters = [r["iters_to_green"] for r in rs if r["iters_to_green"] is not None]
+        lats = [r["latency_s"] for r in rs if r["latency_s"] is not None]
+        costed = [r for r in rs if r["cost"] is not None]
+        tokened = [r for r in rs if r["tokens"] is not None]
+        models = sorted({m for r in rs for m in r["models"]})
+        executors.append({
+            "executor": agent,
+            "models": models,
+            "runs": n,
+            "pass": n_pass, "warn": n_warn, "block": n_block, "other": n_other,
+            "green_rate": _rate(n_pass + n_warn, n),
+            "block_rate": _rate(n_block, n),
+            "iters_to_green": {
+                "n": len(iters),
+                "mean": round(sum(iters) / len(iters), 2) if iters else None,
+                "min": min(iters) if iters else None,
+                "max": max(iters) if iters else None,
+            },
+            "latency_s": {
+                "n": len(lats),
+                "total": round(sum(lats), 3) if lats else None,
+                "mean": round(sum(lats) / len(lats), 3) if lats else None,
+            },
+            # Honest cost: sums cover ONLY the runs whose adapter reported usage.
+            "cost_usd": {
+                "runs_recorded": len(costed),
+                "total": round(sum(r["cost"] for r in costed), 6) if costed else None,
+            },
+            "tokens": {
+                "runs_recorded": len(tokened),
+                "total": sum(r["tokens"] for r in tokened) if tokened else None,
+            },
+        })
+
+    return {
+        "store": str(store.root),
+        "n_runs": len(rows),
+        "executors": executors,
+        "runs": rows,
+    }
+
+
+def _rate(n: int, d: int) -> float | None:
+    return round(n / d, 3) if d else None
+
+
+# --- rendering ---------------------------------------------------------------------
+
+def render(summary: dict) -> str:
+    """The self-explanatory table. Every number traces to a run-store artifact."""
+    lines = [
+        "RSI-L1 — measured selection (per-executor signal from the run store)",
+        f"store: {summary['store']}   runs: {summary['n_runs']}",
+        "",
+        "  green      = the loop accepted the run (final PASS or WARN)",
+        "  iters      = attempts until the first accepted verdict (mean over green runs)",
+        "  cost       = USD summed over runs whose executor reported usage;",
+        "               'not yet recorded' means the adapter surfaced no usage — no number",
+        "               is ever invented for those runs.",
+        "",
+    ]
+    if not summary["executors"]:
+        lines.append("no runs recorded yet — `sembl-stack loop task.yaml` starts the feed.")
+        return "\n".join(lines)
+
+    hdr = (f"  {'executor':16} {'runs':>4} {'green':>6} {'block':>6} "
+           f"{'iters':>6} {'latency':>9} {'cost (USD)':>18}")
+    lines += [hdr, "  " + "-" * (len(hdr) - 2)]
+    for e in summary["executors"]:
+        iters = e["iters_to_green"]["mean"]
+        lat = e["latency_s"]["mean"]
+        cost = e["cost_usd"]
+        if cost["total"] is not None:
+            cost_s = f"{cost['total']:.4f} ({cost['runs_recorded']}/{e['runs']} runs)"
+        else:
+            cost_s = "not yet recorded"
+        lines.append(
+            f"  {e['executor']:16} {e['runs']:>4} "
+            f"{_pct(e['green_rate']):>6} {_pct(e['block_rate']):>6} "
+            f"{iters if iters is not None else '-':>6} "
+            f"{(f'{lat:.1f}s' if lat is not None else '-'):>9} "
+            f"{cost_s:>18}")
+        if e["models"]:
+            lines.append(f"  {'':16} models: {', '.join(e['models'])}")
+    return "\n".join(lines)
+
+
+def _pct(x: float | None) -> str:
+    return f"{x * 100:.0f}%" if x is not None else "-"

sembl_stack/runner.py

@@ -0,0 +1,134 @@
+"""TUI Phase 2 orchestration glue — run the REAL loop and stream stage transitions.
+
+Pure, headless, no Textual: the wizard (and any future surface) drives `run_stages` in a
+worker thread and receives `StageEvent`s as the loop's stage functions actually execute —
+plan (L2 -> rail "bounds"), execute (L3+L4 -> rail "loop"), verify (L5 -> rail "verify").
+No new core/gate logic: the events come from thin proxies wrapped around the SAME adapter
+objects `loop.run` already calls, so a TUI run and a headless `sembl-stack loop` run are
+byte-identical in behavior and artifacts.
+
+Config resolution mirrors the CLI `loop` command exactly: an explicit repo
+`sembl.stack.yaml` always wins; otherwise the onboarded profile is the default.
+"""
+from __future__ import annotations
+
+import copy
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable
+
+import yaml
+
+from .artifacts import Task
+from .config import StackConfig, load as load_config
+from .loop import LoopResult, run as run_loop
+
+# loop stage -> Phase-0 stage-rail name (session.STAGES)
+RAIL = {"plan": "bounds", "execute": "loop", "verify": "verify"}
+
+Emit = Callable[["StageEvent"], None]
+
+
+@dataclass
+class StageEvent:
+    stage: str          # rail stage name ("bounds" | "loop" | "verify")
+    state: str          # "running" | "done" | "fail"
+    detail: str = ""    # e.g. "attempt 2" or the verdict status
+
+
+class _SpecProxy:
+    def __init__(self, inner, emit: Emit):
+        self._inner, self._emit = inner, emit
+
+    def plan(self, task):
+        self._emit(StageEvent("bounds", "running"))
+        try:
+            bounds = self._inner.plan(task)
+        except Exception:
+            self._emit(StageEvent("bounds", "fail"))
+            raise
+        self._emit(StageEvent("bounds", "done"))
+        return bounds
+
+
+class _ExecuteProxy:
+    def __init__(self, inner, emit: Emit):
+        self._inner, self._emit = inner, emit
+        self._attempt = 0
+
+    def run(self, task, bounds, sandbox, feedback):
+        self._attempt += 1
+        self._emit(StageEvent("loop", "running", f"attempt {self._attempt}"))
+        try:
+            result = self._inner.run(task, bounds, sandbox, feedback)
+        except Exception:
+            # loop.execute converts the crash into a BLOCKed Change; mark the rail
+            # anyway so the user sees which attempt died.
+            self._emit(StageEvent("loop", "fail", f"attempt {self._attempt} crashed"))
+            raise
+        self._emit(StageEvent("loop", "done", f"attempt {self._attempt}"))
+        return result
+
+
+class _VerifyProxy:
+    def __init__(self, inner, emit: Emit):
+        self._inner, self._emit = inner, emit
+
+    def verify(self, bounds, change, strict):
+        self._emit(StageEvent("verify", "running"))
+        try:
+            verdict = self._inner.verify(bounds, change, strict)
+        except Exception:
+            self._emit(StageEvent("verify", "fail"))
+            raise
+        status = getattr(verdict, "status", "?")
+        self._emit(StageEvent(
+            "verify", "done" if status in ("PASS", "WARN") else "fail", status))
+        return verdict
+
+
+def load_task(repo: str, name: str = "task.yaml") -> Task | None:
+    """The repo's task.yaml as a Task (same resolution as `cli._load_task`), or None."""
+    p = Path(repo).resolve() / name
+    if not p.is_file():
+        return None
+    data = yaml.safe_load(p.read_text(encoding="utf-8")) or {}
+    if not isinstance(data, dict):
+        return None
+    base = p.parent
+
+    def _resolve(v):
+        if not v:
+            return v
+        vp = Path(v)
+        return str(vp if vp.is_absolute() else (base / vp).resolve())
+
+    return Task(text=data.get("text", ""), repo=_resolve(data.get("repo", ".")),
+                spec_path=_resolve(data.get("spec_path")))
+
+
+def resolve_config(repo: str, config_name: str = "sembl.stack.yaml") -> StackConfig:
+    """Repo sembl.stack.yaml wins; else the onboarded profile; else defaults —
+    exactly the CLI `loop` precedence, so TUI and headless runs stay identical."""
+    cfg_file = Path(repo).resolve() / config_name
+    if cfg_file.is_file():
+        return load_config(str(cfg_file))
+    from . import profile as profile_mod
+    prof = profile_mod.load()
+    overrides = profile_mod.to_stack_overrides(prof) if prof is not None else None
+    return load_config(None, overrides)
+
+
+def run_stages(cfg, task: Task, emit: Emit) -> LoopResult:
+    """Run the real loop with stage events streamed to `emit`. Blocking — call it from a
+    worker thread; `emit` fires on that thread (marshal to the UI thread yourself,
+    e.g. Textual's `call_from_thread`)."""
+    wrapped = copy.copy(cfg)             # shallow: same adapters, three wrapped in proxies
+    wrapped.spec = _SpecProxy(cfg.spec, emit)
+    wrapped.execute = _ExecuteProxy(cfg.execute, emit)
+    wrapped.verify = _VerifyProxy(cfg.verify, emit)
+    result = run_loop(wrapped, task)
+    v = result.verdict
+    emit(StageEvent("verify", "done" if v.status in ("PASS", "WARN") else "fail",
+                    v.status))
+    return result

sembl_stack/session.py

@@ -0,0 +1,86 @@
+"""Phase-0 guided-session pointer over the run store.
+
+A tiny `.sembl/session.json` `{repo, mode, run_id, current_stage, completed}` is what makes the
+guided `sembl-stack` TUI leave/continue-anywhere: it points at a run in the existing store and
+records which stage the user reached. Pure and headless — unit-testable without Textual; the
+wizard only renders and advances it.
+"""
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+
+# The Phase-0 stage rail (CI-run-page order). Only stages that are already headless.
+STAGES = ["bounds", "loop", "verify", "merge", "deploy", "postdeploy"]
+
+
+@dataclass
+class Session:
+    repo: str = "."
+    mode: str = "existing"            # "new" | "existing"
+    run_id: str | None = None
+    current_stage: str = STAGES[0]
+    completed: list[str] = field(default_factory=list)
+
+    def advance(self) -> str:
+        """Mark the current stage complete and move to the next; return the new current stage."""
+        if self.current_stage not in self.completed:
+            self.completed.append(self.current_stage)
+        i = STAGES.index(self.current_stage)
+        if i + 1 < len(STAGES):
+            self.current_stage = STAGES[i + 1]
+        return self.current_stage
+
+    @property
+    def done(self) -> bool:
+        return all(s in self.completed for s in STAGES)
+
+
+def _path(repo: str) -> Path:
+    return Path(repo).resolve() / ".sembl" / "session.json"
+
+
+def save(session: Session) -> Path:
+    p = _path(session.repo)
+    p.parent.mkdir(parents=True, exist_ok=True)
+    p.write_text(json.dumps(asdict(session), indent=2), encoding="utf-8")
+    return p
+
+
+def load(repo: str) -> "Session | None":
+    """Read the saved session, or None if it's missing OR unusable.
+
+    A truncated/corrupt `session.json` or one pointing at an unknown stage must NOT brick the
+    guided entrypoint — an unusable pointer is treated exactly like no pointer (start fresh).
+    """
+    p = _path(repo)
+    if not p.is_file():
+        return None
+    try:
+        data = json.loads(p.read_text(encoding="utf-8"))
+        if not isinstance(data, dict):
+            return None
+        s = Session(**{k: v for k, v in data.items() if k in Session.__dataclass_fields__})
+    except (OSError, ValueError, TypeError):
+        return None
+    # Validate the stage pointer so advance()'s STAGES.index never raises on bad state.
+    if s.current_stage not in STAGES:
+        return None
+    if not isinstance(s.completed, list):
+        return None
+    s.completed = [stage for stage in s.completed if stage in STAGES]
+    return s
+
+
+def resume_or_new(repo: str) -> Session:
+    """Resume the saved session if it exists and is incomplete; else a fresh session.
+
+    This is the "continue anywhere" entry point: an incomplete saved session is the latest
+    point the user reached, so the wizard reopens there. A missing or finished session starts
+    fresh at the first stage.
+    """
+    existing = load(repo)
+    if existing is not None and not existing.done:
+        return existing
+    return Session(repo=str(Path(repo).resolve()))

sembl_stack/specgraph.py

@@ -0,0 +1,146 @@
+"""Build a deterministic SpecGraph artifact from task/spec inputs.
+
+The graph is intentionally structural and local: no model call, no repo scan, no
+network. It gives the reconciliation stage a stable spec-side artifact before a
+heavier spec parser exists.
+"""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from .artifacts import Bounds, SpecGraph, Task
+
+SCHEMA_VERSION = 1
+
+_ROUTE_RE = re.compile(
+    r"(?:route|endpoint|path)\s*[:=-]\s*(?:(GET|POST|PUT|PATCH|DELETE)\s+)?"
+    r"(/[A-Za-z0-9_./{}:-]+)",
+    re.IGNORECASE,
+)
+_ENTITY_RE = re.compile(
+    r"(?:entity|model|table)\s*[:=-]\s*([A-Za-z][A-Za-z0-9_ -]{1,80})",
+    re.IGNORECASE,
+)
+_RULE_RE = re.compile(r"\b(must|only|never|required|requires|should)\b", re.IGNORECASE)
+
+_SPEC_FILENAMES = (
+    "tasks.md",
+    "spec.md",
+    "plan.md",
+    "requirements.md",
+    "README.md",
+)
+
+
+def build_spec_graph(task: Task, bounds: Bounds | None = None) -> SpecGraph:
+    """Build a JSON-serializable graph of declared spec intent."""
+    nodes: list[dict] = []
+    edges: list[dict] = []
+    seen: set[str] = set()
+
+    def add_node(node_id: str, node_type: str, name: str, **attrs) -> None:
+        if node_id in seen:
+            return
+        seen.add(node_id)
+        node = {"id": node_id, "type": node_type, "name": name}
+        node.update({k: v for k, v in attrs.items() if v not in (None, "", [], {})})
+        nodes.append(node)
+
+    def add_edge(src: str, dst: str, rel: str) -> None:
+        edges.append({"from": src, "to": dst, "type": rel})
+
+    add_node("task", "task", "task", text=task.text, repo=task.repo)
+
+    sources = _read_sources(getattr(task, "spec_path", None))
+    if task.text:
+        sources.insert(0, ("task.text", task.text))
+
+    for idx, (source, text) in enumerate(sources):
+        source_id = f"source:{idx}"
+        add_node(source_id, "source", source, path=None if source == "task.text" else source)
+        add_edge("task", source_id, "declares")
+        _extract_concepts(text, source_id, add_node, add_edge)
+
+    if bounds is not None:
+        for path in bounds.editable_paths:
+            node_id = f"scope:editable:{path}"
+            add_node(node_id, "editable_path", path)
+            add_edge("task", node_id, "allows")
+        for path in bounds.forbidden_areas:
+            node_id = f"scope:forbidden:{path}"
+            add_node(node_id, "forbidden_area", path)
+            add_edge("task", node_id, "forbids")
+
+    return SpecGraph(
+        nodes=nodes,
+        edges=edges,
+        sources=[source for source, _ in sources],
+        data={"schema_version": SCHEMA_VERSION},
+    )
+
+
+def _read_sources(spec_path: str | None) -> list[tuple[str, str]]:
+    if not spec_path:
+        return []
+    root = Path(spec_path)
+    if root.is_file():
+        return [(str(root), _read_text(root))]
+    if not root.is_dir():
+        return []
+
+    paths: list[Path] = []
+    for name in _SPEC_FILENAMES:
+        p = root / name
+        if p.is_file():
+            paths.append(p)
+    for p in sorted(root.glob("*.md")):
+        if p not in paths:
+            paths.append(p)
+    return [(str(p), _read_text(p)) for p in paths]
+
+
+def _read_text(path: Path) -> str:
+    try:
+        return path.read_text(encoding="utf-8")
+    except UnicodeDecodeError:
+        return path.read_text(encoding="utf-8", errors="replace")
+
+
+def _extract_concepts(text: str, source_id: str, add_node, add_edge) -> None:
+    for match in _ROUTE_RE.finditer(text):
+        method, route = match.groups()
+        route = _clean_route(route)
+        method = (method or "ANY").upper()
+        node_id = f"route:{method}:{route}"
+        add_node(node_id, "route", route, method=method)
+        add_edge(source_id, node_id, "mentions")
+
+    for match in _ENTITY_RE.finditer(text):
+        entity = _clean_label(match.group(1))
+        if not entity:
+            continue
+        node_id = f"entity:{_slug(entity)}"
+        add_node(node_id, "entity", entity)
+        add_edge(source_id, node_id, "mentions")
+
+    for line_no, line in enumerate(text.splitlines(), start=1):
+        stripped = line.strip(" -*\t")
+        if not stripped or not _RULE_RE.search(stripped):
+            continue
+        node_id = f"rule:{source_id}:{line_no}"
+        add_node(node_id, "data_rule", stripped, line=line_no)
+        add_edge(source_id, node_id, "declares")
+
+
+def _clean_label(value: str) -> str:
+    return re.sub(r"\s+", " ", value).strip(" .:-")
+
+
+def _clean_route(value: str) -> str:
+    return value.rstrip(".,;:)")
+
+
+def _slug(value: str) -> str:
+    slug = re.sub(r"[^a-z0-9]+", "-", value.lower()).strip("-")
+    return slug or "unnamed"

sembl_stack/store.py

@@ -0,0 +1,112 @@
+"""Run store — artifacts persisted at `.sembl/runs/<run-id>/` in the target repo.
+
+Local-first, no server required to read a past run. Each run is a directory of JSON
+artifacts plus a `run.json` manifest. This is what makes runs inspectable (TUI/web),
+resumable, and enterable at an arbitrary stage (supply the upstream artifact).
+"""
+from __future__ import annotations
+
+import json
+import re
+import time
+import uuid
+from pathlib import Path
+
+from . import artifacts
+from .artifacts import _Serializable
+
+
+class Run:
+    def __init__(self, root: Path, run_id: str):
+        self.id = run_id
+        self.dir = root / run_id
+        self.dir.mkdir(parents=True, exist_ok=True)
+        self._manifest_path = self.dir / "run.json"
+
+    # -- artifacts --------------------------------------------------------------
+    def put(self, artifact: _Serializable, name: str | None = None) -> str:
+        """Persist an artifact; `name` defaults to its KIND. Returns the file name."""
+        name = name or artifact.KIND
+        fname = f"{name}.json"
+        (self.dir / fname).write_text(artifact.to_json(), encoding="utf-8")
+        self._touch_manifest(name, artifact.KIND, fname)
+        return fname
+
+    def get(self, name: str):
+        """Load an artifact by name (reconstructs the right type via its `_kind` tag)."""
+        path = self.dir / f"{name}.json"
+        if not path.is_file():
+            return None
+        return artifacts.from_dict(json.loads(path.read_text(encoding="utf-8")))
+
+    def has(self, name: str) -> bool:
+        return (self.dir / f"{name}.json").is_file()
+
+    # -- manifest ---------------------------------------------------------------
+    def manifest(self) -> dict:
+        if self._manifest_path.is_file():
+            return json.loads(self._manifest_path.read_text(encoding="utf-8"))
+        return {}
+
+    def set_status(self, status: str, **extra) -> None:
+        m = self.manifest()
+        m["status"] = status
+        m["updated"] = time.time()
+        m.update(extra)
+        self._write_manifest(m)
+
+    def record_attempt(self, attempt: int, **metric) -> None:
+        """Append a per-attempt cost/latency record to the manifest (C1.3).
+
+        One entry per execute call: `{attempt, latency_s, agent, model, exit_code,
+        tokens, cost}` (tokens/cost only where the executor reported usage). This is the
+        signal `sembl-stack runs` shows and that the process-RSI / eval (B) layer consumes.
+        Keys with a None value are dropped so the manifest stays clean.
+        """
+        m = self.manifest()
+        entry = {"attempt": attempt}
+        entry.update({k: v for k, v in metric.items() if v is not None})
+        m.setdefault("attempts_log", []).append(entry)
+        self._write_manifest(m)
+
+    def _touch_manifest(self, name: str, kind: str, fname: str) -> None:
+        m = self.manifest()
+        m.setdefault("artifacts", {})[name] = {
+            "kind": kind, "file": fname, "ts": time.time()}
+        self._write_manifest(m)
+
+    def _write_manifest(self, m: dict) -> None:
+        self._manifest_path.write_text(
+            json.dumps(m, indent=2, ensure_ascii=False), encoding="utf-8")
+
+
+_RUN_ID = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]*$")
+
+
+class RunStore:
+    def __init__(self, repo: str):
+        self.root = Path(repo).resolve() / ".sembl" / "runs"
+
+    def new_run(self, task=None) -> Run:
+        run_id = time.strftime("%Y%m%d-%H%M%S-") + uuid.uuid4().hex[:6]
+        run = Run(self.root, run_id)
+        m = {"id": run_id, "created": time.time(), "status": "started",
+             "artifacts": {}}
+        if task is not None:
+            m["task"] = {"text": getattr(task, "text", ""),
+                         "repo": getattr(task, "repo", "")}
+        run._write_manifest(m)
+        return run
+
+    def open(self, run_id: str) -> Run:
+        # A run id is a single directory name under .sembl/runs — never a path. Rejecting
+        # separators/leading dots here keeps `runs <id>` / `apply <id>` from resolving
+        # (and mkdir-ing) outside the store via a crafted id like `..\\..\\evil`.
+        if not _RUN_ID.match(run_id):
+            raise ValueError(f"invalid run id: {run_id!r}")
+        return Run(self.root, run_id)
+
+    def list_runs(self) -> list[str]:
+        if not self.root.is_dir():
+            return []
+        return sorted((p.name for p in self.root.iterdir() if p.is_dir()), reverse=True)