sembl-stack 0.1.0__py3-none-any.whl

sembl_stack/loop.py

@@ -0,0 +1,380 @@
+"""L6 orchestration: the short loop as a state machine.
+
+plan (L2) -> execute (L3, in a fresh sandbox L4) -> verify (L5) ->
+  BLOCK & attempts left? feed the gate's reasons back and retry
+  PASS/WARN? accept.
+
+Driven by LangGraph when installed (real retry graph + checkpointable), with a
+built-in fallback runner of identical semantics so the loop boots with zero extra
+installs. Every node is wrapped in a Langfuse span via the tracer.
+"""
+from __future__ import annotations
+
+import subprocess
+import time
+from dataclasses import dataclass, field
+from typing import Any, TypedDict
+
+from .adapters.base import Task, Verdict
+from .artifacts import Change, Trace, bind_verdict
+from .config import StackConfig
+from .specgraph import build_spec_graph
+from .store import RunStore
+from .tracing import get_tracer
+
+
+class LoopState(TypedDict, total=False):
+    """The state threaded through the graph (last-value channels)."""
+    attempt: int
+    feedback: str | None
+    history: list
+    bounds: Any
+    sandbox: Any
+    result: Any
+    verdict: Any
+
+
+@dataclass
+class LoopResult:
+    verdict: Verdict
+    attempts: int
+    history: list = field(default_factory=list)   # [(attempt, status), ...]
+    workdir: str | None = None
+    engine: str = "fallback"
+    run_id: str | None = None
+
+
+def _is_empty_change(change) -> bool:
+    """True when the executor produced no substantive change.
+
+    Not just "no diff": an executor that errored or hit a dead model often *creates an
+    empty file*, which has a `diff --git` header but no content — a no-op in substance. So
+    the real signal is the absence of added/removed content (or a structural rename/delete/
+    copy). `+++`/`---` file markers are skipped; any other `+`/`-` line is real content.
+    """
+    diff = getattr(change, "diff", "") or ""
+    for line in diff.splitlines():
+        s = line.rstrip()
+        if s.startswith(("+++", "---")):
+            continue
+        if s.startswith(("+", "-")):
+            return False                      # real content added or removed
+        if s.startswith(("rename ", "deleted file", "copy ")):
+            return False                      # structural change with no +/- body
+    return True
+
+
+def _execution_error(change) -> str | None:
+    """A hard executor failure (timeout / crash) recorded by the adapter, or None.
+
+    The adapters convert a `TimeoutExpired` / internal crash into `report["error"]`
+    instead of letting it abort the loop; this reads that signal back so the verify
+    stage can BLOCK rather than the loop raising.
+    """
+    report = getattr(change, "report", {}) or {}
+    err = report.get("error")
+    return str(err) if err else None
+
+
+def _nonzero_exit(change) -> int | None:
+    """The executor's non-zero process exit code, if any (else None).
+
+    A non-zero exit means the agent process did not finish cleanly. The gate verifies the
+    *change* (bounds + claim integrity), not process health — so a non-zero exit that still
+    produced an in-scope diff would otherwise PASS silently. The loop surfaces it instead.
+    """
+    report = getattr(change, "report", {}) or {}
+    rc = report.get("exit_code")
+    return rc if isinstance(rc, int) and rc != 0 else None
+
+
+def _usage_tokens(report: dict):
+    """Total tokens an executor reported, if any (C1.3) — best-effort, never required.
+
+    Accepts a few shapes: `usage.total_tokens`, `usage.tokens`, or a bare `tokens`. Returns
+    None when the executor didn't surface usage (the common case for the OAuth/CLI agents).
+    """
+    usage = report.get("usage")
+    if isinstance(usage, dict):
+        return usage.get("total_tokens") or usage.get("tokens")
+    return report.get("tokens")
+
+
+def _maybe_expand(cfg: StackConfig, task: Task, bounds, tracer) -> None:
+    """L1 context stage (in-loop): widen `bounds.editable_paths` along the coupling closure.
+
+    Opt-in via `loop.expand_bounds`. This makes the running loop the fuller pipeline
+    (L1→L2→L3→L4→L5) instead of only the `bounds --expand` CLI. It is a no-op — and so leaves
+    the gate exactly as strict — when no context adapter is configured/available or the seed
+    has no indexed files. Mutates `bounds` in place (one hop, closure-capped; EXP-05).
+    """
+    if not (cfg.raw.get("loop", {}) or {}).get("expand_bounds"):
+        return
+    g = cfg.context
+    if g is None or not getattr(g, "available", lambda: False)():
+        return
+    from .contextgraph import expand_bounds as _eb
+
+    opts = (cfg.raw.get("options", {}) or {}).get("context", {}) or {}
+    with tracer.span("L1.context"):
+        g.index(task.repo)
+        fg = g.file_graph(task.repo)
+    bounds.editable_paths = _eb(
+        list(bounds.editable_paths), fg, hops=opts.get("hops", 1),
+        min_strength=opts.get("min_strength", 0), max_fraction=opts.get("max_fraction", 0.4))
+
+
+# --- L4 isolation guard (defense-in-depth) -----------------------------------
+#
+# The sandbox (L4) clones the repo so the executor (L3) edits ONLY a disposable copy; the
+# gate verifies that copy's diff. But a swapped-in executor can ignore the cage and edit the
+# SOURCE tree instead (this happened live 2026-06-20: `opencode` ignored the inherited cwd
+# and wrote into the source repo until `--dir <sandbox.workdir>` was passed, commit 4a76163).
+# That leak was caught only by eye. These helpers assert — cheaply, once before and once
+# after the run — that the source working tree is left untouched, so a future regression
+# fails LOUD (forced BLOCK) instead of slipping through.
+
+_STORE_PREFIX = ".sembl/"          # the run store writes here BY DESIGN; never a breach
+
+
+def _source_tree_status(repo: str) -> set[str] | None:
+    """Snapshot the source repo's dirty working tree, EXCLUDING the `.sembl/` run store.
+
+    Returns the set of `git status --porcelain` lines for paths outside `.sembl/` (which
+    `store.py` writes into the source repo on every run, by design). Returns None — so the
+    caller skips the guard gracefully — when `repo` is not a git repo or git is unavailable.
+    """
+    try:
+        proc = subprocess.run(
+            ["git", "status", "--porcelain"], cwd=repo,
+            capture_output=True, text=True, encoding="utf-8", errors="replace")
+    except (OSError, ValueError):
+        return None                                  # git missing / bad path: can't guard
+    if proc.returncode != 0:
+        return None                                  # not a git repo: nothing to guard
+    lines: set[str] = set()
+    for line in proc.stdout.splitlines():
+        if not line.strip():
+            continue
+        path = line[3:].strip()                      # porcelain: "XY <path>"
+        if " -> " in path:                           # a rename: "old -> new"
+            path = path.split(" -> ", 1)[1]
+        path = path.strip().strip('"')
+        if path == _STORE_PREFIX.rstrip("/") or path.startswith(_STORE_PREFIX):
+            continue                                 # run-store writes are expected
+        lines.add(line)
+    return lines
+
+
+def _isolation_breach(before: set[str] | None, after: set[str] | None) -> str | None:
+    """A human reason if the source tree changed during the run (the cage leaked), else None.
+
+    `before`/`after` are `_source_tree_status` snapshots (or None when unguardable). Any
+    difference outside `.sembl/` means the executor wrote into the SOURCE repo instead of the
+    disposable clone.
+    """
+    if before is None or after is None or before == after:
+        return None
+    paths = sorted({line[3:].strip().split(" -> ")[-1].strip().strip('"')
+                    for line in (before ^ after)})
+    shown = ", ".join(paths[:5]) + (" …" if len(paths) > 5 else "")
+    return ("sandbox isolation breach: the executor modified the source repo "
+            f"(unexpected working-tree changes outside {_STORE_PREFIX}: {shown})")
+
+
+def _nodes(cfg: StackConfig, task: Task, tracer, run, holder: dict | None = None):
+    def plan(state: dict) -> dict:
+        with tracer.span("L2.plan"):
+            bounds = cfg.spec.plan(task)
+        run.put(build_spec_graph(task, bounds))
+        _maybe_expand(cfg, task, bounds, tracer)   # L1: widen along the context graph
+        run.put(bounds)                            # persist Bounds artifact (post-expansion)
+        return {"bounds": bounds}
+
+    def execute(state: dict) -> dict:
+        n = state["attempt"] + 1
+        prev = state.get("sandbox")
+        if prev is not None:
+            prev.close()                           # fresh cage per attempt
+        sandbox = cfg.sandbox.open(task.repo)
+        if holder is not None:
+            holder["sandbox"] = sandbox            # so run() can close it on a crash
+        t0 = time.perf_counter()
+        with tracer.span("L3.execute", attempt=n):
+            try:
+                result = cfg.execute.run(task, state["bounds"], sandbox,
+                                         state.get("feedback"))
+            except Exception as exc:
+                # An executor that crashes (or whose subprocess raises past the adapter's
+                # own timeout handling) must NOT abort the loop, leak the sandbox, or skip
+                # the persisted verdict. Convert the failure into a recorded Change so the
+                # verify stage turns it into a BLOCK and the run still completes cleanly.
+                diff = ""
+                try:
+                    diff = sandbox.diff()
+                except Exception:
+                    pass
+                result = Change(
+                    diff=diff, workdir=getattr(sandbox, "workdir", ""),
+                    report={"error": "executor-crashed", "exit_code": -1,
+                            "detail": repr(exc)})
+        latency_s = round(time.perf_counter() - t0, 3)
+
+        # C1.3: record cost+latency per attempt. Latency is always measured here (wall
+        # clock around the executor); tokens/cost ride along only when the adapter reported
+        # usage. Stamp latency onto the Change report too so a single artifact is enough.
+        report = dict(getattr(result, "report", {}) or {})
+        report.setdefault("latency_s", latency_s)
+        result.report = report
+        run.put(result, name=f"change-{n}")        # persist Change per attempt
+        run.record_attempt(
+            n, latency_s=latency_s, agent=report.get("agent"), model=report.get("model"),
+            exit_code=report.get("exit_code"), tokens=_usage_tokens(report),
+            cost=report.get("cost"))
+        return {"sandbox": sandbox, "result": result}
+
+    def verify(state: dict) -> dict:
+        change = state["result"]
+        exec_err = _execution_error(change)
+        if exec_err is not None:
+            # C1 hardening: a hard executor failure (timeout / crash) is not a verdict the
+            # gate can issue — the gate checks a *change*, not process health. Block directly
+            # so a timed-out or crashed run never sails through as PASS, and hand the executor
+            # actionable feedback on retry. (No gate call: there's nothing trustworthy to
+            # verify.)
+            verdict = Verdict(
+                status="BLOCK",
+                reasons=[f"executor failed ({exec_err}) — the task was not implemented; "
+                         "check the executor/model output"],
+                raw={"execution_error": exec_err, "report": getattr(change, "report", {})})
+        elif _is_empty_change(change):
+            # C1 hardening: a no-op execution (empty diff — e.g. the executor errored, hit a
+            # dead model, or wrote nothing) must NOT pass. The gate verifies a *change*; with
+            # no change there is nothing that satisfies the task, so block and tell the
+            # executor it produced nothing (actionable feedback on retry).
+            verdict = Verdict(
+                status="BLOCK",
+                reasons=["executor produced no changes (empty diff) — the task was not "
+                         "implemented; check the executor/model output"],
+                raw={"empty_diff": True, "report": getattr(change, "report", {})})
+        else:
+            with tracer.span("L5.verify"):
+                verdict = cfg.verify.verify(state["bounds"], change, cfg.strict)
+            rc = _nonzero_exit(change)
+            if rc is not None and verdict.status == "PASS":
+                # The change passed the gate but the executor process exited non-zero — it
+                # did not complete cleanly. Don't report an unqualified PASS: downgrade to
+                # WARN and record why, so a half-finished run is never mistaken for success.
+                verdict = Verdict(
+                    status="WARN",
+                    reasons=list(verdict.reasons)
+                    + [f"executor exited non-zero (exit_code={rc}); the change was applied "
+                       "but the run did not complete cleanly"],
+                    raw={**(getattr(verdict, "raw", {}) or {}), "exit_code": rc})
+        # Bind the verdict to the exact diff it judged (also for BLOCKs — harmless),
+        # so merge/apply can later refuse a verdict issued for a different change.
+        bind_verdict(verdict, getattr(change, "diff", "") or "")
+        attempt = state["attempt"] + 1
+        run.put(verdict, name=f"verdict-{attempt}")
+        return {
+            "verdict": verdict,
+            "attempt": attempt,
+            "feedback": verdict.feedback(),
+            "history": state.get("history", []) + [(attempt, verdict.status)],
+        }
+
+    def route(state: dict) -> str:
+        if state["verdict"].status in ("PASS", "WARN"):
+            return "done"
+        return "retry" if state["attempt"] < cfg.max_attempts else "done"
+
+    return plan, execute, verify, route
+
+
+def run(cfg: StackConfig, task: Task) -> LoopResult:
+    tracer = get_tracer(cfg.langfuse)
+    run_rec = RunStore(task.repo).new_run(task)
+    # L4 isolation guard: snapshot the source tree BEFORE any sandbox/executor runs.
+    tree_before = _source_tree_status(task.repo)
+    holder: dict = {"sandbox": None}
+    plan, execute, verify, route = _nodes(cfg, task, tracer, run_rec, holder)
+    init = {"attempt": 0, "feedback": None, "history": []}
+
+    try:
+        try:
+            final, engine = _run_langgraph(plan, execute, verify, route, init)
+        except ImportError:
+            final, engine = _run_fallback(plan, execute, verify, route, init), "fallback"
+    except Exception as exc:
+        # A crash in plan/verify (executor crashes are already converted in-node) must not
+        # leave the run stuck at "started" with an open sandbox on disk. Close the cage,
+        # record the failure, then re-raise so the caller still sees the real error.
+        sb = holder.get("sandbox")
+        if sb is not None:
+            try:
+                sb.close()
+            except Exception:
+                pass
+        run_rec.set_status("failed", error=repr(exc)[:500])
+        tracer.flush()
+        raise
+
+    sandbox = final.get("sandbox")
+    workdir = getattr(sandbox, "workdir", None) if sandbox else None
+    if sandbox is not None:
+        sandbox.close()
+    tracer.flush()
+
+    # L4 isolation guard: re-snapshot the source tree now that the run is over. If it
+    # changed (outside .sembl/), the executor escaped the sandbox and edited the SOURCE repo
+    # — a containment breach the gate can't see. Fail LOUD: force the final verdict to BLOCK
+    # so the breach is never mistaken for a clean PASS/WARN.
+    verdict = final["verdict"]
+    breach = _isolation_breach(tree_before, _source_tree_status(task.repo))
+    if breach is not None:
+        verdict = Verdict(
+            status="BLOCK",
+            reasons=[breach, *getattr(verdict, "reasons", [])],
+            raw={**(getattr(verdict, "raw", {}) or {}), "isolation_breach": True})
+
+    # Persist the final accepted change under a stable name, then the final verdict, a
+    # trace, and the run status. Per-attempt artifacts remain as change-1/verdict-1...
+    run_rec.put(final["result"], name="change")
+    run_rec.put(verdict)
+    run_rec.put(Trace(steps=[{"attempt": a, "status": s} for a, s in final["history"]]))
+    log = run_rec.manifest().get("attempts_log", [])             # C1.3 per-attempt metrics
+    total_latency_s = round(sum(e.get("latency_s", 0) for e in log), 3)
+    run_rec.set_status(verdict.status,
+                       attempts=final["attempt"], engine=engine,
+                       total_latency_s=total_latency_s)
+
+    return LoopResult(
+        verdict=verdict, attempts=final["attempt"],
+        history=final["history"], workdir=workdir, engine=engine,
+        run_id=run_rec.id,
+    )
+
+
+def _run_langgraph(plan, execute, verify, route, init):
+    from langgraph.graph import StateGraph, END   # raises ImportError if absent
+
+    g = StateGraph(LoopState)
+    g.add_node("plan", plan)
+    g.add_node("execute", execute)
+    g.add_node("verify", verify)
+    g.set_entry_point("plan")
+    g.add_edge("plan", "execute")
+    g.add_edge("execute", "verify")
+    g.add_conditional_edges("verify", route, {"retry": "execute", "done": END})
+    app = g.compile()
+    return app.invoke(init, {"recursion_limit": 50}), "langgraph"
+
+
+def _run_fallback(plan, execute, verify, route, init):
+    state = dict(init)
+    state.update(plan(state))
+    while True:
+        state.update(execute(state))
+        state.update(verify(state))
+        if route(state) == "done":
+            return state

sembl_stack/onboarding.py

@@ -0,0 +1,272 @@
+"""Phase-1 first-run onboarding TUI for the BYO profile.
+
+This module is a thin Textual guide over `profile.py`: welcome, choose how model
+calls are paid for, capture a few preferences, persist `~/.sembl/profile.json`,
+then return control to the Phase-0 stage rail. It is deliberately tolerant of bad
+state and keeps all credential decisions in the deterministic profile core.
+Textual is optional; callers use `available()` before launching.
+"""
+from __future__ import annotations
+
+import re
+
+from . import presets, profile
+from .session import resume_or_new, save as save_session
+
+try:
+    from textual.app import App, ComposeResult
+    from textual.containers import Vertical
+    from textual.widgets import (
+        Button,
+        Checkbox,
+        Collapsible,
+        Footer,
+        Header,
+        Input,
+        Select,
+        Static,
+    )
+    _HAVE_TEXTUAL = True
+except ImportError:                      # textual not installed - degrade gracefully
+    _HAVE_TEXTUAL = False
+
+
+RUNNER_CHOICES = {
+    "claude-login": ("Use my Claude Code login", "claude"),
+    "api-key": ("Use my API key", "claude"),
+    "local": ("Use a local model", "opencode"),
+    "mock": ("Preview the mechanics (no AI)", "mock"),
+}
+
+_ENV_NAME = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+
+
+def available() -> bool:
+    return _HAVE_TEXTUAL
+
+
+def launch(repo: str = ".") -> "profile.Profile | None":
+    """Launch first-run onboarding. Caller launches `wizard.launch(repo)` after."""
+    if not _HAVE_TEXTUAL:
+        raise RuntimeError("textual not installed - `pip install \"sembl-stack[tui]\"`")
+    return OnboardingApp(repo=repo).run()
+
+
+def env_var_options() -> list[str]:
+    return list(profile._KEY_ENV_VARS)
+
+
+def normalize_env_var_name(name: str) -> str:
+    cleaned = name.strip()
+    if not _ENV_NAME.match(cleaned):
+        raise ValueError("enter an environment variable name, not an API key value")
+    return cleaned
+
+
+def api_key_source(selected: str | None, custom: str | None) -> str:
+    custom_name = (custom or "").strip()
+    name = normalize_env_var_name(custom_name or (selected or ""))
+    return f"env:{name}"
+
+
+def profile_for_runner(
+    runner: str,
+    *,
+    key_env: str | None = None,
+    custom_key_env: str | None = None,
+    executor: str | None = None,
+    model: str | None = None,
+    strict: bool = True,
+    preset: str | None = None,
+) -> profile.Profile:
+    """Build a Profile from widget state without reading any API key value."""
+    if runner not in RUNNER_CHOICES:
+        raise ValueError(f"unknown runner: {runner}")
+    default_executor = RUNNER_CHOICES[runner][1]
+    key_source = None
+    if runner == "api-key":
+        key_source = api_key_source(key_env, custom_key_env)
+    model = (model or "").strip() or None
+    preset = preset or None
+    return profile.Profile(
+        runner=runner,
+        executor=executor or default_executor,
+        model=model,
+        key_source=key_source,
+        strict=strict,
+        preset=preset,
+    )
+
+
+def first_fix_hint(candidate: profile.Profile) -> tuple[bool, str]:
+    checks = profile.preflight(candidate)
+    return profile.ready(checks)
+
+
+if _HAVE_TEXTUAL:
+
+    class OnboardingApp(App):
+        """First-run BYO setup: welcome -> runner choice -> preferences -> profile."""
+
+        TITLE = "sembl-stack"
+        SUB_TITLE = "first-run setup"
+        BINDINGS = [("q", "quit", "Quit")]
+        CSS = """
+        #onboarding { padding: 1 2; }
+        .screen { display: none; }
+        .active { display: block; }
+        .choice { width: 100%; margin: 0 0 1 0; }
+        #mock-choice { opacity: 70%; }
+        #byo-hint { color: $error; margin: 1 0 0 0; }
+        #prefs-error { color: $error; margin: 1 0 0 0; }
+        Select, Input { margin: 0 0 1 0; }
+        Button { margin: 0 1 1 0; }
+        """
+
+        def __init__(self, repo: str = "."):
+            super().__init__()
+            self.repo = repo
+            detected = profile.detect()
+            self._runner = detected.runner
+            self._key_env = (
+                detected.key_source.removeprefix("env:")
+                if detected.key_source and detected.key_source.startswith("env:")
+                else profile._KEY_ENV_VARS[0]
+            )
+
+        def compose(self) -> "ComposeResult":
+            yield Header()
+            with Vertical(id="onboarding"):
+                with Vertical(id="welcome-screen", classes="screen active"):
+                    yield Static(
+                        "sembl-stack puts an accountability gate around an AI coding loop.",
+                        id="welcome-copy",
+                    )
+                    yield Static(
+                        "It runs on your own keys, local model, or Claude Code login.",
+                        id="keys-copy",
+                    )
+                    yield Button("Continue", id="welcome-next", variant="primary")
+
+                with Vertical(id="byo-screen", classes="screen"):
+                    yield Static("Choose how sembl-stack should run AI work.", id="byo-title")
+                    yield Button(RUNNER_CHOICES["claude-login"][0], id="claude-choice", classes="choice")
+                    yield Button(RUNNER_CHOICES["api-key"][0], id="api-choice", classes="choice")
+                    yield Select(
+                        [(name, name) for name in env_var_options()],
+                        value=self._key_env if self._key_env in env_var_options() else env_var_options()[0],
+                        id="api-env",
+                    )
+                    yield Input(placeholder="OTHER_API_KEY_ENV", id="api-env-custom")
+                    yield Button(RUNNER_CHOICES["local"][0], id="local-choice", classes="choice")
+                    yield Button(RUNNER_CHOICES["mock"][0], id="mock-choice", classes="choice")
+                    yield Static("", id="byo-hint")
+
+                with Vertical(id="prefs-screen", classes="screen"):
+                    yield Static("Preferences", id="prefs-title")
+                    yield Select([("Existing repo", "existing"), ("New repo", "new")],
+                                 value="existing", id="repo-mode")
+                    yield Checkbox("Strict gate", value=True, id="strict")
+                    yield Select([("No preset", "")] + [(name, name) for name in presets.names()],
+                                 value="", id="preset")
+                    with Collapsible(title="Advanced", collapsed=True, id="advanced"):
+                        yield Select([(name, name) for name in ("claude", "opencode", "aider", "mock")],
+                                     value=RUNNER_CHOICES[self._runner][1], id="executor")
+                        yield Input(placeholder="Model (optional)", id="model")
+                    yield Button("Go", id="finish", variant="primary")
+                    yield Static("", id="prefs-error")
+            yield Footer()
+
+        def on_mount(self) -> None:
+            self._mark_selected()
+
+        def on_button_pressed(self, event) -> None:
+            button_id = event.button.id
+            if button_id == "welcome-next":
+                self._show("byo")
+            elif button_id in {"claude-choice", "api-choice", "local-choice", "mock-choice"}:
+                runner = {
+                    "claude-choice": "claude-login",
+                    "api-choice": "api-key",
+                    "local-choice": "local",
+                    "mock-choice": "mock",
+                }[button_id]
+                self._choose_runner(runner)
+            elif button_id == "finish":
+                self._finish()
+
+        def _show(self, name: str) -> None:
+            for screen_id in ("welcome-screen", "byo-screen", "prefs-screen"):
+                screen = self.query_one(f"#{screen_id}")
+                screen.remove_class("active")
+            self.query_one(f"#{name}-screen").add_class("active")
+
+        def _choose_runner(self, runner: str) -> None:
+            self._runner = runner
+            self._mark_selected()
+            try:
+                candidate = self._candidate_from_inputs()
+            except ValueError as exc:
+                self.query_one("#byo-hint", Static).update(str(exc))
+                return
+            ok, hint = first_fix_hint(candidate)
+            if not ok:
+                self.query_one("#byo-hint", Static).update(hint)
+                return
+            self.query_one("#byo-hint", Static).update("")
+            self.query_one("#executor", Select).value = candidate.executor
+            self._show("prefs")
+
+        def _finish(self) -> None:
+            try:
+                candidate = self._candidate_from_inputs(include_preferences=True)
+            except ValueError as exc:
+                self.query_one("#prefs-error", Static).update(str(exc))
+                return
+            ok, hint = first_fix_hint(candidate)
+            if not ok:
+                self.query_one("#prefs-error", Static).update(hint)
+                return
+            try:
+                profile.save(candidate)
+            except ValueError as exc:      # e.g. an API key pasted into the Model field
+                self.query_one("#prefs-error", Static).update(str(exc))
+                return
+            session = resume_or_new(self.repo)
+            session.mode = str(self.query_one("#repo-mode", Select).value or "existing")
+            save_session(session)
+            self.exit(candidate)
+
+        def _candidate_from_inputs(self, *, include_preferences: bool = False) -> profile.Profile:
+            key_env = str(self.query_one("#api-env", Select).value or "")
+            custom_key_env = self.query_one("#api-env-custom", Input).value
+            executor = RUNNER_CHOICES[self._runner][1]
+            model = None
+            strict = True
+            preset = None
+            if include_preferences:
+                executor = str(self.query_one("#executor", Select).value or executor)
+                model = self.query_one("#model", Input).value
+                strict = bool(self.query_one("#strict", Checkbox).value)
+                preset_value = str(self.query_one("#preset", Select).value or "")
+                preset = preset_value or None
+            return profile_for_runner(
+                self._runner,
+                key_env=key_env,
+                custom_key_env=custom_key_env,
+                executor=executor,
+                model=model,
+                strict=strict,
+                preset=preset,
+            )
+
+        def _mark_selected(self) -> None:
+            ids = {
+                "claude-login": "claude-choice",
+                "api-key": "api-choice",
+                "local": "local-choice",
+                "mock": "mock-choice",
+            }
+            for runner, button_id in ids.items():
+                button = self.query_one(f"#{button_id}", Button)
+                button.variant = "primary" if runner == self._runner else "default"