alissa-tools-github-genloop 0.1.0__py3-none-any.whl

alissa/tools/github/genloop/__init__.py

@@ -0,0 +1,14 @@
+"""genloop — the generator seat of the Alissa GitHub daemon family (design
+`docs/design/genloop.md` v0.2 in `ali-fhr/studio.alissa.app`, lane L5).
+
+Where orcloop releases committed work, devloop develops it and revloop
+reviews it, genloop PROPOSES it: on a cadence it spawns one judgment session
+(`genloop-<stamp>`) that reads the operator's direction and the loop's
+exhaust and writes at most one plan on a `PLAN-` branch of the fleet's plans
+repository; the seat then opens that plan's pull request, requests the
+refuter, records the plan and emits the `plan.*` / `pass.*` loop events. The
+reserved runtime env prefix is `ALISSA_GEN_*`; the seat is OFF unless
+`ALISSA_GEN_ENABLED` is set.
+"""
+
+__all__: list[str] = []

alissa/tools/github/genloop/__main__.py

@@ -0,0 +1,89 @@
+"""`alissa-genloop` — run the genloop seat.
+
+    alissa-genloop              # poll forever (every ALISSA_GEN_POLL_INTERVAL seconds)
+    alissa-genloop --once       # one poll, print its decision line, exit
+    alissa-genloop --dry-run    # narrate every side effect instead of performing it
+    alissa-genloop --version
+
+Configuration is the environment only (`ALISSA_GEN_*`, pass-through-when-unset,
+see `config.py`); tokens are `GH_TOKEN` (read by `gh`) and `ALISSA_API_TOKEN`.
+"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import signal
+import sys
+import threading
+from typing import Sequence
+
+from .alissa_cli import AlissaCli
+from .alissa_client import AlissaClient
+from .config import Config, ConfigError
+from .github import GitHub
+from .loop import GenLoop
+from .loop_events import LoopEventRecorder
+from .state import State
+from .version import version
+
+log = logging.getLogger("alissa.tools.github.genloop")
+
+
+def build_loop(config: Config) -> GenLoop:
+    alissa = AlissaClient(base=config.alissa_endpoint or None)
+    return GenLoop(
+        config,
+        state=State.in_dir(config.state_path),
+        alissa=alissa,
+        github=GitHub(),
+        cli=AlissaCli(),
+        events=LoopEventRecorder(alissa, dry_run=config.dry_run),
+    )
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="alissa-genloop", description="The genloop seat (design lane L5).")
+    parser.add_argument("--once", action="store_true", help="run one poll and exit")
+    parser.add_argument("--dry-run", action="store_true", help="narrate side effects instead of performing them")
+    parser.add_argument("--log-level", default="INFO", help="logging level (default INFO)")
+    parser.add_argument("--version", action="version", version=f"{version.name} {version.value}")
+    args = parser.parse_args(argv)
+
+    logging.basicConfig(
+        level=getattr(logging, str(args.log_level).upper(), logging.INFO),
+        format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+    )
+    try:
+        config = Config.from_env()
+        if args.dry_run:
+            config = config.replace(dry_run=True)
+    except ConfigError as exc:
+        log.error("genloop: configuration refused — %s", exc)
+        return 2
+    log.info("genloop %s starting: %s", version.value, config.summary())
+    loop = build_loop(config)
+
+    if args.once:
+        print(loop.poll())
+        return 0
+
+    stop = threading.Event()
+
+    def _stop(signum, _frame):  # pragma: no cover - signal plumbing
+        log.info("genloop: signal %d — stopping after this poll", signum)
+        stop.set()
+
+    signal.signal(signal.SIGTERM, _stop)
+    signal.signal(signal.SIGINT, _stop)
+    while not stop.is_set():
+        try:
+            loop.poll()
+        except Exception:  # noqa: BLE001 - one bad poll must not end the seat
+            log.exception("genloop: the poll raised — retrying next interval")
+        stop.wait(config.poll_interval)
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

alissa/tools/github/genloop/alissa_cli.py

@@ -0,0 +1,89 @@
+"""The `alissa` CLI surface the seat needs: enqueue one managed session, probe
+the worker, list the managed tmux sessions, kill ONE of them.
+
+Copy-adapted from orcloop's `alissa_cli.py` (itself devloop's), deliberately
+NOT redesigned: the seats drive the same worker through the same four
+commands, and a divergence here is a divergence in what "a live session"
+means between the seats that count them.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from pathlib import Path
+from typing import Sequence
+
+from .proc import CommandError, run
+
+log = logging.getLogger(__name__)
+
+
+def _run(argv: Sequence[str], *, timeout: int, check: bool = True) -> str:
+    """`proc.run`, with a CLI that could not be EXECUTED (missing binary,
+    unexecutable file) folded into the same `CommandError` as a CLI that
+    answered badly -- every caller treats "the CLI did not answer" as a hold."""
+    try:
+        return run(argv, timeout=timeout, check=check)
+    except OSError as exc:
+        raise CommandError(argv, -1, f"could not execute {argv[0]!r}: {exc}") from exc
+
+
+class AlissaCli:
+    def enqueue_session(self, *, session: str, directive: str, cwd: Path, agent: str) -> None:
+        """`alissa tmux queue add <session> --agent <agent> --cwd <cwd>
+        <directive>`, then `queue set <session> respawn off` (best-effort): a
+        pass is one-shot, the seat's interval is the cadence."""
+        _run(
+            ["alissa", "tmux", "queue", "add", session, "--agent", agent, "--cwd", str(cwd), directive],
+            timeout=60,
+        )
+        try:
+            _run(["alissa", "tmux", "queue", "set", session, "respawn", "off"], timeout=30, check=False)
+        except CommandError:  # pragma: no cover - defence in depth
+            log.warning("could not set respawn off for %s", session)
+
+    def list_sessions(self) -> "list[dict]":
+        """`alissa tmux ls --json`. Raises CommandError whenever the CLI does
+        not answer USABLY (non-zero exit, empty or unparseable stdout, not a
+        list): a working CLI prints `[]` when there are no sessions, so
+        anything else is UNKNOWN -- and unknown holds the spawn (L2)."""
+        argv = ["alissa", "tmux", "ls", "--json"]
+        out = _run(argv, timeout=60)
+        if not out.strip():
+            raise CommandError(argv, 0, "`alissa tmux ls --json` printed nothing")
+        try:
+            data = json.loads(out)
+        except json.JSONDecodeError:
+            raise CommandError(argv, 0, "`alissa tmux ls --json` returned unparseable output") from None
+        if not isinstance(data, list):
+            raise CommandError(argv, 0, f"`alissa tmux ls --json` returned {type(data).__name__}, not a list")
+        return [entry for entry in data if isinstance(entry, dict)]
+
+    def queued(self, name: str) -> bool:
+        """True while `alissa tmux queue ls <name> --json` still holds a
+        pending item: the session was enqueued but not yet dispatched, so its
+        absence from `tmux ls` does not mean it ended. Raises CommandError
+        when the CLI does not answer usably (unknown, which holds)."""
+        argv = ["alissa", "tmux", "queue", "ls", name, "--json"]
+        out = _run(argv, timeout=60)
+        try:
+            data = json.loads(out)
+        except json.JSONDecodeError:
+            raise CommandError(argv, 0, "`alissa tmux queue ls --json` returned unparseable output") from None
+        if not isinstance(data, dict) or not isinstance(data.get("items"), list):
+            raise CommandError(argv, 0, "`alissa tmux queue ls --json` returned no `items` list")
+        return bool(data["items"])
+
+    def kill_session(self, name: str) -> None:
+        """Kill ONE managed session by name -- never the tmux server."""
+        _run(["alissa", "tmux", "kill", name], timeout=60)
+
+    def worker_running(self) -> bool:
+        """The queue only drains while `alissa worker` reconciles it."""
+        try:
+            out = _run(["alissa", "worker", "status"], timeout=30, check=False)
+        except CommandError:
+            return False
+        lowered = out.lower()
+        return "not running" not in lowered and "no worker" not in lowered

alissa/tools/github/genloop/alissa_client.py

@@ -0,0 +1,183 @@
+"""Thin REST adapter over the Alissa routes the genloop seat calls.
+
+Transport (`_request`, `_classify`) is copied from orcloop's client: stdlib
+`urllib` over HTTPS, `ALISSA_API_TOKEN` / `ALISSA_BASE` from the environment,
+every failure mapped onto a narrow taxonomy so callers never see a raw urllib
+error or status.
+
+The seat runs on the planner's own agent-bound token (D12). Studio answers
+that token with its SPONSOR's rows on every read below; of the writes, the
+seat's own two are `POST /v1/loop-events` and `POST /v1/loop/plans`. The
+third, `PUT /v1/factory/proposal-rules` (§4.4's mechanical rule write), is
+documented by Studio as a `403 FORBIDDEN` for an agent-bound token -- the seat
+attempts it and records the refusal rather than retrying it every poll.
+
+Routes (Studio `API.md`):
+
+* `GET  /v1/ping`                         -> who the token acts as.
+* `GET  /v1/factory/steering`             -> `{records: [...]}`, fleet row first.
+* `GET  /v1/factory/proposal-rules`       -> `{rules: [...]}`, unexpired only.
+* `PUT  /v1/factory/proposal-rules`       -> one rule, `201` new / `200 renewed`.
+* `GET  /v1/code/budget?scope=&projectId=&window=` -> `{state, spentUsd?, capUsd?, remainingUsd?}`.
+* `GET  /v1/loop/generated`               -> `{openLanes, plansToday, plansOpen}`.
+* `POST /v1/loop/plans`                   -> idempotent on `(repo, prNumber)`.
+* `POST /v1/loop-events`                  -> idempotent on each `dedupeKey`.
+* `GET  /v1/bodies-of-work?includeShared=true` -> `{bodiesOfWork: [...]}`.
+"""
+
+from __future__ import annotations
+
+import http.client
+import json
+import logging
+import os
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Sequence
+
+log = logging.getLogger(__name__)
+
+DEFAULT_BASE = "https://api.alissa.app"
+
+
+class AlissaError(RuntimeError):
+    """Base class. `status` is the HTTP code (0 for transport failures); `code`
+    is the API's machine error string (`{"error": ...}`) when one was sent."""
+
+    def __init__(self, status: int, payload: object, code: str | None = None):
+        self.status = status
+        self.payload = payload
+        self.code = code
+        super().__init__(f"HTTP {status}{f' {code}' if code else ''}: {payload}")
+
+
+class AlissaAuthError(AlissaError):
+    """401/403: no valid token, or the bound actor may not do this."""
+
+
+class AlissaNotFound(AlissaError):
+    """404."""
+
+
+class AlissaTransient(AlissaError):
+    """408/429/5xx or a transport failure: retry next poll."""
+
+
+def _query(params: dict) -> str:
+    pairs = [(k, str(v)) for k, v in params.items() if v is not None and v != ""]
+    return "?" + urllib.parse.urlencode(pairs) if pairs else ""
+
+
+class AlissaClient:
+    def __init__(self, token: str | None = None, base: str | None = None, *, timeout: int = 30):
+        self.base = (base or os.environ.get("ALISSA_BASE") or DEFAULT_BASE).rstrip("/")
+        self._token = token if token is not None else os.environ.get("ALISSA_API_TOKEN")
+        self._timeout = timeout
+
+    # --- transport ---------------------------------------------------------
+
+    def _request(self, method: str, path: str, body: dict | None = None) -> object:
+        if not self._token:
+            raise AlissaAuthError(0, "ALISSA_API_TOKEN is not set")
+        url = f"{self.base}{path}"
+        data = json.dumps(body).encode("utf-8") if body is not None else None
+        headers = {"Accept": "application/json", "Authorization": f"Bearer {self._token}"}
+        if data is not None:
+            headers["Content-Type"] = "application/json"
+        req = urllib.request.Request(url, data=data, method=method, headers=headers)
+        try:
+            with urllib.request.urlopen(req, timeout=self._timeout) as resp:  # noqa: S310
+                raw = resp.read().decode("utf-8")
+        except urllib.error.HTTPError as exc:
+            raise self._classify(exc) from None
+        except urllib.error.URLError as exc:
+            raise AlissaTransient(0, str(exc.reason)) from None
+        except (TimeoutError, OSError, http.client.HTTPException) as exc:
+            # A read timeout or reset after the connection is up is not a
+            # URLError; without this branch it would end the process.
+            raise AlissaTransient(0, str(exc) or type(exc).__name__) from None
+        return json.loads(raw) if raw.strip() else {}
+
+    @staticmethod
+    def _classify(exc: "urllib.error.HTTPError") -> AlissaError:
+        try:
+            detail: object = exc.read().decode("utf-8", "replace")
+        except (TimeoutError, OSError, http.client.HTTPException):
+            detail = ""
+        code: str | None = None
+        try:
+            parsed = json.loads(detail)  # type: ignore[arg-type]
+            if isinstance(parsed, dict):
+                detail = parsed
+                raw_code = parsed.get("error")
+                code = raw_code if isinstance(raw_code, str) else None
+        except (json.JSONDecodeError, TypeError):
+            pass
+        status = exc.code
+        if status in (401, 403):
+            return AlissaAuthError(status, detail, code)
+        if status == 404:
+            return AlissaNotFound(status, detail, code)
+        if status == 408 or status == 429 or 500 <= status <= 599:
+            return AlissaTransient(status, detail, code)
+        return AlissaError(status, detail, code)
+
+    # --- reads -------------------------------------------------------------
+
+    def ping(self) -> dict:
+        payload = self._request("GET", "/v1/ping")
+        return payload if isinstance(payload, dict) else {}
+
+    def factory_steering(self) -> list[dict]:
+        """The operator's steering rows (fleet first). Empty when nothing is
+        set -- which steers nothing and parks nothing."""
+        payload = self._request("GET", "/v1/factory/steering")
+        records = payload.get("records") if isinstance(payload, dict) else None
+        return [row for row in records if isinstance(row, dict)] if isinstance(records, list) else []
+
+    def proposal_rules(self) -> list[dict]:
+        payload = self._request("GET", "/v1/factory/proposal-rules")
+        rules = payload.get("rules") if isinstance(payload, dict) else None
+        return [row for row in rules if isinstance(row, dict)] if isinstance(rules, list) else []
+
+    def budget_status(self, scope: str, *, project_id: str | None = None, window: str = "30d") -> dict:
+        """The cost meter's `budgetStatus`: `{state, spentUsd?, capUsd?,
+        remainingUsd?, ...}`, `state` one of ok / warn / exhausted / unmetered."""
+        payload = self._request(
+            "GET", "/v1/code/budget" + _query({"scope": scope, "projectId": project_id, "window": window}),
+        )
+        if not isinstance(payload, dict) or not isinstance(payload.get("state"), str):
+            raise AlissaError(0, payload, "budget answered no state")
+        return payload
+
+    def loop_generated(self) -> dict:
+        """`{openLanes, plansToday, plansOpen}`."""
+        payload = self._request("GET", "/v1/loop/generated")
+        if not isinstance(payload, dict) or not isinstance(payload.get("openLanes"), int):
+            raise AlissaError(0, payload, "generated answered no openLanes")
+        return payload
+
+    def list_bodies_of_work(self) -> list[dict]:
+        payload = self._request("GET", "/v1/bodies-of-work?includeShared=true")
+        rows = payload.get("bodiesOfWork") if isinstance(payload, dict) else None
+        return [row for row in rows if isinstance(row, dict)] if isinstance(rows, list) else []
+
+    # --- writes ------------------------------------------------------------
+
+    def post_loop_plan(self, record: dict) -> dict:
+        """Record a plan or move its status forward. Idempotent on `(repo,
+        prNumber)`: the same status answers `200 {duplicate: true}`."""
+        payload = self._request("POST", "/v1/loop/plans", record)
+        return payload if isinstance(payload, dict) else {}
+
+    def post_loop_events(self, events: "Sequence[dict]") -> dict:
+        payload = self._request("POST", "/v1/loop-events", {"events": list(events)})
+        return payload if isinstance(payload, dict) else {}
+
+    def put_proposal_rule(self, *, pattern: str, scope: str, scope_key: str, reason: str, source_url: str) -> dict:
+        body: dict = {"pattern": pattern, "scope": scope, "reason": reason, "sourceUrl": source_url}
+        if scope_key:
+            body["scopeKey"] = scope_key
+        payload = self._request("PUT", "/v1/factory/proposal-rules", body)
+        return payload if isinstance(payload, dict) else {}

alissa/tools/github/genloop/config.py

@@ -0,0 +1,294 @@
+"""The genloop seat's configuration: every `ALISSA_GEN_*` knob, its one
+default, and the validation that runs before the first poll.
+
+PASS-THROUGH-WHEN-UNSET (design L10, the three seats' rule)
+=========================================================
+`Config.from_env` reads a key ONLY when its `ALISSA_GEN_<KEY>` variable is set
+and non-empty. A key the operator did not set is absent from the mapping
+`Config.build` sees, so the default below is what takes effect -- one source
+of truth for every default, this module. The container's ARG->ENV block bakes
+every variable to the empty string, which therefore means "unset", never
+"empty value".
+
+THE PLANS REPOSITORY IS PER-FLEET CONFIGURATION
+==============================================
+The operator's decision on issue #1 overrides the design's literal: a fleet's
+plans repository is `ALISSA_GEN_PLANS_REPO`, defaulting to
+`<ALISSA_GEN_OWNER>/` + `PLANS_REPO_NAME`. `PLANS_REPO_NAME` below is the ONE
+place the repository's name is written in this distribution, and
+`test_no_plans_repo_literal` holds every other file of the repository to that.
+
+FAIL CLOSED (design L9)
+=======================
+`enabled` defaults to OFF: an image deployed without `ALISSA_GEN_ENABLED`
+idles and says why every poll. Once enabled, a seat that cannot name its plans
+repository, its reviewer or (in `static` mode) one fed repo refuses to boot
+rather than guess.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import os
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Mapping
+
+ENV_PREFIX = "ALISSA_GEN_"
+
+# The default plans repository's NAME (its owner is the fleet's, see above).
+PLANS_REPO_NAME = "alissa-dark-factory-plans"
+
+REPOS_SOURCE_BOWS = "bows"
+REPOS_SOURCE_STATIC = "static"
+REPOS_SOURCES = (REPOS_SOURCE_BOWS, REPOS_SOURCE_STATIC)
+
+# The feed body-of-work title prefix every seat reads (`autodev: <owner>/<repo>`).
+BOW_PREFIX = "autodev:"
+
+DEFAULT_WORKSPACE_ROOT = "/workspace"
+DEFAULT_STATE_DIRNAME = ".genloop"
+
+_REPO_RE = re.compile(r"^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$")
+_OWNER_RE = re.compile(r"^[A-Za-z0-9_.-]+$")
+_LOGIN_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9-]*(\[bot\])?$")
+
+# Every key, with its library default. The env name is ENV_PREFIX + KEY.upper().
+DEFAULTS: dict[str, object] = {
+    # The deploy-time switch (D11, L9): off unless the operator turns it on.
+    "enabled": False,
+    # Seconds between passes (D14: six hours).
+    "interval": 6 * 3600,
+    # Seconds between polls. A poll ingests a finished pass, opens its PR and
+    # walks the floors; the interval above is what spaces the SPAWNS.
+    "poll_interval": 300,
+    # The exhaust look-back the directive hands the pass (§3).
+    "window_days": 30,
+    # D10's two counters.
+    "plans_per_day": 2,
+    "open_lanes_max": 4,
+    # A live pass older than stale_intervals x interval is stalled (L2).
+    "stale_intervals": 2,
+    # GitHub logins whose closing comment on a plan PR writes a rule (§4.4).
+    "operators": (),
+    # The fleet's GitHub owner; the plans repository defaults under it.
+    "owner": "",
+    # `owner/name`; empty means `<owner>/` + PLANS_REPO_NAME.
+    "plans_repo": "",
+    # Where the fed-repo allowlist comes from: the `autodev:` feed bodies of
+    # work (`bows`, the fleet's mode) or `repos` (`static`).
+    "repos_source": REPOS_SOURCE_BOWS,
+    "repos": (),
+    # In `bows` mode, only feeds owned by these actor ids count (empty: any
+    # feed the token can read).
+    "bow_owners": (),
+    # Who reviews a plan PR (D12: the reviewer bot, never the seat).
+    "reviewers": ("alissa-app",),
+    # This seat's own GitHub login; empty means `gh api user`.
+    "login": "",
+    # The pass's skill and the worker agent profile that runs it.
+    "skill": "alissa-code-genloop",
+    "agent": "claude",
+    # Paths. Empty means "derive" (see the properties on Config).
+    "workspace_root": "",
+    "state_dir": "",
+    "plans_hub": "",
+    # Alissa's base URL; empty means the client's default (ALISSA_BASE).
+    "alissa_endpoint": "",
+    # Narrate every side effect instead of performing it.
+    "dry_run": False,
+}
+
+CONFIG_KEYS = tuple(DEFAULTS)
+_BOOL_KEYS = frozenset(k for k, v in DEFAULTS.items() if isinstance(v, bool))
+_INT_KEYS = frozenset(k for k, v in DEFAULTS.items() if isinstance(v, int) and not isinstance(v, bool))
+_LIST_KEYS = frozenset(k for k, v in DEFAULTS.items() if isinstance(v, tuple))
+
+# Lower bounds, so a typo cannot make the seat spin.
+_INT_MIN = {
+    "interval": 60,
+    "poll_interval": 10,
+    "window_days": 1,
+    "plans_per_day": 0,
+    "open_lanes_max": 0,
+    "stale_intervals": 1,
+}
+
+_TRUE = frozenset(("1", "true", "yes", "on"))
+_FALSE = frozenset(("0", "false", "no", "off"))
+
+
+class ConfigError(ValueError):
+    """The configuration cannot run; the message names the variable."""
+
+
+def env_name(key: str) -> str:
+    return ENV_PREFIX + key.upper()
+
+
+def split_entries(raw: str) -> tuple[str, ...]:
+    """The family's list syntax: `|`-separated, `,` also accepted, blanks dropped."""
+    return tuple(part.strip() for part in re.split(r"[|,]", raw) if part.strip())
+
+
+def _coerce(key: str, value: object) -> object:
+    if key in _BOOL_KEYS:
+        if isinstance(value, bool):
+            return value
+        text = str(value).strip().lower()
+        if text in _TRUE:
+            return True
+        if text in _FALSE:
+            return False
+        raise ConfigError(f"{env_name(key)}={value!r} is not a boolean (true/false)")
+    if key in _INT_KEYS:
+        try:
+            number = int(str(value).strip())
+        except ValueError:
+            raise ConfigError(f"{env_name(key)}={value!r} is not an integer") from None
+        floor = _INT_MIN.get(key)
+        if floor is not None and number < floor:
+            raise ConfigError(f"{env_name(key)}={number} is below its minimum {floor}")
+        return number
+    if key in _LIST_KEYS:
+        if isinstance(value, (list, tuple)):
+            return tuple(str(v).strip() for v in value if str(v).strip())
+        return split_entries(str(value))
+    return str(value).strip()
+
+
+@dataclass(frozen=True)
+class Config:
+    enabled: bool = False
+    interval: int = 6 * 3600
+    poll_interval: int = 300
+    window_days: int = 30
+    plans_per_day: int = 2
+    open_lanes_max: int = 4
+    stale_intervals: int = 2
+    operators: tuple[str, ...] = ()
+    owner: str = ""
+    plans_repo: str = ""
+    repos_source: str = REPOS_SOURCE_BOWS
+    repos: tuple[str, ...] = ()
+    bow_owners: tuple[str, ...] = ()
+    reviewers: tuple[str, ...] = ("alissa-app",)
+    login: str = ""
+    skill: str = "alissa-code-genloop"
+    agent: str = "claude"
+    workspace_root: str = ""
+    state_dir: str = ""
+    plans_hub: str = ""
+    alissa_endpoint: str = ""
+    dry_run: bool = False
+
+    # -- construction ------------------------------------------------------
+
+    @classmethod
+    def build(cls, mapping: Mapping[str, object] | None = None) -> "Config":
+        """A validated Config from `mapping` (key -> raw value); a key absent
+        from the mapping takes its default from `DEFAULTS`."""
+        mapping = dict(mapping or {})
+        unknown = sorted(set(mapping) - set(CONFIG_KEYS))
+        if unknown:
+            raise ConfigError(f"unknown config key(s): {', '.join(unknown)}")
+        values = {key: _coerce(key, mapping[key]) if key in mapping else DEFAULTS[key] for key in CONFIG_KEYS}
+        config = cls(**values)  # type: ignore[arg-type]
+        config.validate()
+        return config
+
+    @classmethod
+    def from_env(cls, environ: Mapping[str, str] | None = None) -> "Config":
+        """Pass-through-when-unset: only the set, non-empty `ALISSA_GEN_*`
+        variables reach `build`. `workspace_root` also honours the image's
+        `ALISSA_WORKSPACE_ROOT`."""
+        env = os.environ if environ is None else environ
+        mapping: dict[str, object] = {}
+        for key in CONFIG_KEYS:
+            raw = env.get(env_name(key))
+            if raw is not None and raw.strip():
+                mapping[key] = raw
+        if "workspace_root" not in mapping and (env.get("ALISSA_WORKSPACE_ROOT") or "").strip():
+            mapping["workspace_root"] = env["ALISSA_WORKSPACE_ROOT"]
+        return cls.build(mapping)
+
+    def replace(self, **changes: object) -> "Config":
+        config = dataclasses.replace(self, **changes)  # type: ignore[arg-type]
+        config.validate()
+        return config
+
+    # -- validation ----------------------------------------------------------
+
+    def validate(self) -> None:
+        if self.repos_source not in REPOS_SOURCES:
+            raise ConfigError(
+                f"{env_name('repos_source')}={self.repos_source!r} is not one of {', '.join(REPOS_SOURCES)}"
+            )
+        if self.owner and not _OWNER_RE.match(self.owner):
+            raise ConfigError(f"{env_name('owner')}={self.owner!r} is not a GitHub owner")
+        if self.plans_repo and not _REPO_RE.match(self.plans_repo):
+            raise ConfigError(f"{env_name('plans_repo')}={self.plans_repo!r} is not owner/name")
+        for repo in self.repos:
+            if not _REPO_RE.match(repo):
+                raise ConfigError(f"{env_name('repos')} entry {repo!r} is not owner/name")
+        for key in ("operators", "reviewers"):
+            for login in getattr(self, key):
+                if not _LOGIN_RE.match(login):
+                    raise ConfigError(f"{env_name(key)} entry {login!r} is not a GitHub login")
+        if self.login and not _LOGIN_RE.match(self.login):
+            raise ConfigError(f"{env_name('login')}={self.login!r} is not a GitHub login")
+        if not self.enabled:
+            # An idle seat needs nothing else; it says why it idles every poll.
+            return
+        if not self.plans_repo and not self.owner:
+            raise ConfigError(
+                f"genloop is enabled but cannot name its plans repository: set {env_name('plans_repo')} "
+                f"(owner/name) or {env_name('owner')} (the default is <owner>/{PLANS_REPO_NAME})"
+            )
+        if not self.reviewers:
+            raise ConfigError(f"genloop is enabled with an empty {env_name('reviewers')} — a plan PR needs a refuter")
+        if self.repos_source == REPOS_SOURCE_STATIC and not self.repos:
+            raise ConfigError(
+                f"{env_name('repos_source')}=static with an empty {env_name('repos')} — the seat is fail-closed"
+            )
+        if self.login and self.login in self.reviewers:
+            raise ConfigError(
+                f"{env_name('login')}={self.login!r} is also a reviewer — the generator never reviews its "
+                "own plan (D12)"
+            )
+
+    # -- derived -------------------------------------------------------------
+
+    @property
+    def plans_repository(self) -> str:
+        """`owner/name` of the fleet's plans repository."""
+        if self.plans_repo:
+            return self.plans_repo
+        return f"{self.owner}/{PLANS_REPO_NAME}" if self.owner else ""
+
+    @property
+    def workspace_path(self) -> Path:
+        return Path(self.workspace_root or DEFAULT_WORKSPACE_ROOT)
+
+    @property
+    def state_path(self) -> Path:
+        return Path(self.state_dir) if self.state_dir else self.workspace_path / DEFAULT_STATE_DIRNAME
+
+    @property
+    def plans_hub_path(self) -> Path:
+        """The plans repository's worktree hub -- the one checkout the
+        container holds (D14). Defaults to `<workspace>/<repo name>`."""
+        if self.plans_hub:
+            return Path(self.plans_hub)
+        name = self.plans_repository.split("/", 1)[-1] if self.plans_repository else PLANS_REPO_NAME
+        return self.workspace_path / name
+
+    def summary(self) -> str:
+        """One line for the boot log; no secrets live in the config."""
+        return (
+            f"enabled={self.enabled} interval={self.interval}s poll={self.poll_interval}s "
+            f"plans_repo={self.plans_repository or '<unset>'} repos_source={self.repos_source} "
+            f"plans_per_day={self.plans_per_day} open_lanes_max={self.open_lanes_max} "
+            f"reviewers={'|'.join(self.reviewers)} dry_run={self.dry_run}"
+        )