syncade 0.6.2__py3-none-any.whl

syncade/config_auth.py

@@ -0,0 +1,310 @@
+"""Auth-mode declaration for every actor: subscription vs API key.
+
+**The bug this exists to close.** Syncade copies ``dict(os.environ)`` into every
+subprocess, so the auth *mode* is whatever each CLI decides — and the two CLIs decide
+OPPOSITELY. Verified live (claude 2.1.208 / codex-cli 0.144.1) by injecting a bogus
+key into each and seeing who lost:
+
+    claude  + bogus ANTHROPIC_API_KEY -> 401. The ENV KEY beat the claude.ai login.
+                                        The CLI even says so: "ANTHROPIC_API_KEY ...
+                                        takes precedence over your claude.ai login".
+    codex   + bogus OPENAI_API_KEY    -> replied fine. The STORED CHATGPT LOGIN beat
+                                        the env key; the run billed the subscription.
+
+So on ONE machine, in ONE run, with ONE environment, one provider can bill your
+subscription while the other silently bills your API account — fanned out N reviewers
+x M rounds. A developer with ``ANTHROPIC_API_KEY`` exported (extremely common) believes
+they are on their Max plan while every subprocess charges the API.
+
+**Declared mode is enforced mode, in BOTH directions.** This is about quota as much as
+money: subscriptions have usage caps and syncade is *designed* to fan out, so
+``auth = "api"`` is a real escape hatch for heavy users — and their traffic must not
+silently fall back to a throttled subscription either.
+
+``auto`` is the default and resolves to whatever the CLI would actually do. It is
+deliberately NOT "strip everything by default": that would break users who intentionally
+run on API keys with no subscription at all. Auto is safe only because the preflight
+ALWAYS prints the resolved mode. Silence is the bug.
+
+Leaf module (imports nothing from syncade but :mod:`syncade.config_types`) because every
+actor config imports it and ``config`` cannot depend on the actors — same constraint that
+put the cold-actor defaults in :mod:`syncade.config_cold`.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import TYPE_CHECKING, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+if TYPE_CHECKING:  # runtime import would cycle: config imports THIS module
+    from syncade.config import SyncadeConfig
+
+AuthMode = Literal["auto", "subscription", "api"]
+
+PROVIDER_KEY_VARS: dict[str, tuple[str, ...]] = {
+    "anthropic": ("ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN"),
+    "openai": ("OPENAI_API_KEY",),
+}
+"""Env vars that route a provider's CLI to the API instead of its stored login.
+
+Stripping these is what makes ``auth = "subscription"`` an ENFORCED guarantee rather
+than a request: the CLI physically cannot reach the API without them.
+
+Deliberately NOT included: ``*_BASE_URL``. Those point at proxies/gateways rather than
+carrying credentials, and stripping them would break 3P-provider users for no security
+gain. Only credential-bearing vars belong here.
+"""
+
+
+def default_api_key_env(provider: str) -> str | None:
+    """The conventional key var for ``provider``, or ``None`` if unknown."""
+    keys = PROVIDER_KEY_VARS.get(provider)
+    return keys[0] if keys else None
+
+
+class AuthedActor(BaseModel):
+    """Mixin: every actor that spawns a provider CLI declares its auth mode.
+
+    Inherited by ``ReviewerConfig``, ``ProducerConfig`` and ``_ColdActorConfig``, so the
+    declaration exists on all five actor types (reviewers, producer, judge, drafter,
+    auditor) rather than only where someone remembered to add it.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    auth: AuthMode = Field(
+        default="auto",
+        description=(
+            "Which credential this actor's CLI must use. ``subscription`` STRIPS the "
+            "provider's API-key vars from the child env, so the CLI physically cannot "
+            "reach the API. ``api`` on ANTHROPIC requires the key in the env (exit 50 at "
+            "config load if missing); on OPENAI it means `codex login --with-api-key` and "
+            "reads no env var -- verified by the codex probe, not at load. "
+            "``auto`` (default) resolves to whatever the CLI would do on its own — and "
+            "the preflight always prints which that is, because the failure mode here "
+            "is silence, not the wrong choice."
+        ),
+    )
+    api_key_env: str | None = Field(
+        default=None,
+        description=(
+            'Env var holding the API key, when ``auth = "api"``. Defaults to the '
+            "provider's conventional var (ANTHROPIC_API_KEY / OPENAI_API_KEY). Set it "
+            "to use a differently-named var — e.g. a work key separate from a personal "
+            "one."
+        ),
+    )
+
+    @model_validator(mode="after")
+    def _api_key_env_must_be_honourable(self) -> AuthedActor:
+        """``api_key_env`` is refused whenever syncade could not actually honour it.
+
+        Two ways it becomes a silent no-op, and a user who names a key var plainly intends
+        it to be used, so both fail loudly at config load:
+
+        1. **Without ``auth = "api"``** the key would simply be ignored.
+        2. **On an openai actor, at all.** ``codex`` does not read the environment — its
+           key comes from ``CODEX_HOME`` (``codex login --with-api-key``). So
+           ``api_key_env = "WORK_KEY"`` on an openai actor was ACCEPTED while codex quietly
+           used whatever key was in its stored login: the user believes their WORK_KEY is
+           paying, and a different key actually is. That is the exact deceit this module
+           exists to delete, so it is refused rather than accepted-and-ignored.
+        """
+        if self.api_key_env is None:
+            return self
+        if self.auth != "api":
+            raise ValueError(
+                f'api_key_env={self.api_key_env!r} requires auth = "api" '
+                f'(got auth = "{self.auth}"), otherwise the key would be ignored'
+            )
+        if getattr(self, "provider", "") == "openai":
+            raise ValueError(
+                f"api_key_env={self.api_key_env!r} cannot be honoured for provider "
+                f'"openai": codex ignores the environment and reads its key from its '
+                f"stored login. Run `printenv {self.api_key_env} | codex login "
+                f"--with-api-key` instead — syncade will verify it with `codex login "
+                f"status`."
+            )
+        return self
+
+    def key_var(self) -> str | None:
+        """The env var this actor reads its API key from, when in ``api`` mode."""
+        return self.api_key_env or default_api_key_env(getattr(self, "provider", ""))
+
+
+def apply_auth_to_env(env: dict[str, str], actor: AuthedActor) -> dict[str, str]:
+    """Enforce ``actor.auth`` on the environment its CLI subprocess will inherit.
+
+    This is where a declaration becomes a guarantee. The env is the ONLY lever syncade
+    has — it cannot reach inside a CLI's credential resolution — so:
+
+    - ``subscription`` → **strip** the provider's key vars. The CLI then physically
+      cannot reach the API; it has no key. This closes the ``claude`` footgun outright
+      (an exported ``ANTHROPIC_API_KEY`` otherwise beats the claude.ai login, verified
+      live). Not a request to the CLI — a removal of the capability.
+    - ``api`` → strip the provider's key vars, then set the CLI's CANONICAL var from
+      wherever the user actually keeps the key. That indirection is the point of
+      ``api_key_env``: ``claude`` reads ``ANTHROPIC_API_KEY`` and nothing else, so a
+      user with the key in ``WORK_KEY`` needs it mapped across or the setting would be
+      a silent no-op. Stripping first also means a stale ``ANTHROPIC_AUTH_TOKEN`` can't
+      outrank the key the user just declared.
+    - ``auto`` → untouched. Whatever the CLI would have done, it still does — and the
+      preflight prints which that is. Auto is only safe BECAUSE it is announced.
+
+    Note this deliberately does NOT run for the test/check legs, which share
+    :func:`~syncade.worktree_env.worktree_scoped_env`: those run the operator's own test
+    command, which may legitimately need API keys. Enforcement belongs where a PROVIDER
+    CLI is spawned, which is why it lives in the adapters and not in the env builder.
+
+    Returns a new dict; ``env`` is never mutated.
+    """
+    provider = getattr(actor, "provider", "")
+    key_vars = PROVIDER_KEY_VARS.get(provider, ())
+    if actor.auth == "auto" or not key_vars:
+        return env
+
+    stripped = {k: v for k, v in env.items() if k not in key_vars}
+    if actor.auth == "subscription":
+        return stripped
+
+    if provider == "openai":
+        # codex NEVER reads the environment -- its key lives in CODEX_HOME. There is no key
+        # to route and nothing to require: `auth = "api"` here is satisfied by
+        # `codex login --with-api-key`, which auth_preflight verifies via `codex login
+        # status` before anything spends.
+        #
+        # Config load already exempts openai from the key requirement. Raising HERE anyway
+        # meant the config loaded and then the reviewer/judge DIED at subprocess-build
+        # time -- the same bug one layer down, which is the seventh time in this PR I fixed
+        # one call site and left its twin. Strip the (ignored) var and get out of the way.
+        return stripped
+
+    var = actor.key_var()
+    key = env.get(var or "")
+    if not key:
+        # config load already guaranteed this; reaching here means the env changed
+        # underneath us, and shipping the request without a key would silently fall
+        # back to the subscription -- the exact failure this PR deletes.
+        raise ValueError(
+            f'auth = "api" for provider "{provider}" requires {var} to be set in the '
+            f"environment, but it is empty or missing"
+        )
+    return {**stripped, key_vars[0]: key}
+
+
+#: The actors each CLI mode can ACTUALLY spawn. The gate must refuse (and report) on
+#: these and no others: `syncade --spec-audit` spawns only the auditor, so refusing it
+#: because a REVIEWER's declaration contradicts reality blocks a command that would never
+#: have run that reviewer -- and the auth report would announce billing for actors that
+#: are not going to bill anything.
+REVIEW_BLOCKS = frozenset({"reviewers", "producer", "synthesizer"})
+#: `--selfcheck` is a PRODUCER-ONLY commit smoke (run_selfcheck calls run_producer once
+#: and spawns no reviewer). It listed `reviewers` in error — a reviewer's auth declaration
+#: then blocked a command that never runs a reviewer. Verified against selfcheck.py.
+SELFCHECK_BLOCKS = frozenset({"producer"})
+AUDIT_BLOCKS = frozenset({"auditor"})
+DRAFT_BLOCKS = frozenset({"drafter"})
+ALL_BLOCKS = frozenset({"reviewers", "producer", "synthesizer", "drafter", "auditor"})
+
+
+def credential_fingerprint(actor: AuthedActor, env: dict[str, str]) -> tuple[tuple[str, str], ...]:
+    """A stable identity for the credential this actor will ACTUALLY present, READ from the
+    enforced env rather than derived from its declaration.
+
+    ONE definition, used by both surfaces that need it — ``--auth-check``'s probe-dedup
+    (:func:`syncade.auth_check._credential_key`) and the auth report's grouping
+    (:func:`syncade.auth_preflight.report_lines`). Two copies of "which credential is this"
+    diverged twice: round 6 (auto vs explicit api, custom key var) and round 11 (stale
+    AUTH_TOKEN). Reading VALUES, not var names, settles both — and keeping it in one place
+    is the only thing that stops the third.
+
+    Values are hashed so a secret never lands in a dict key or a log. Missing-key ``api``
+    (``apply_auth_to_env`` raises) fingerprints as ``()`` — no credential, its own group.
+    """
+    import hashlib
+
+    provider = getattr(actor, "provider", "")
+    if provider == "openai":
+        # codex reads NO env var (its login lives in CODEX_HOME), so the env does not
+        # distinguish an openai actor's credential at all: `auto`, `subscription`, and `api`
+        # openai actors on one machine are the SAME stored codex login. Fingerprinting by
+        # OPENAI_API_KEY (which `auto` leaves in the env) split them into phantom "different
+        # credentials", duplicating probes and report lines for one real credential.
+        return ()
+    try:
+        applied = apply_auth_to_env(dict(env), actor)
+    except ValueError:
+        return ()
+    return tuple(
+        sorted(
+            (var, hashlib.sha256(applied[var].encode()).hexdigest()[:12])
+            for var in PROVIDER_KEY_VARS.get(provider, ())
+            if applied.get(var)
+        )
+    )
+
+
+def authed_actors(
+    config: SyncadeConfig, blocks: frozenset[str] | None = None
+) -> list[tuple[str, AuthedActor]]:
+    """Every actor that spawns a provider CLI, labelled by its config block.
+
+    One list, so nothing gets enforced for four actors and forgotten for the fifth.
+    Reused by the load-time key check, the env enforcement, the codex reality probe,
+    and the preflight print.
+
+    ``blocks`` narrows it to the actors a given mode can actually spawn (see
+    ``*_BLOCKS`` above). ``None`` means all of them — correct for the load-time key check,
+    which validates the whole config regardless of which command is running.
+    """
+    tagged: list[tuple[str, str, AuthedActor]] = [
+        ("reviewers", f'[[reviewers]] "{r.name}"', r) for r in config.reviewers
+    ]
+    tagged.append(("producer", "[producer]", config.producer))
+    tagged.append(("synthesizer", "[synthesizer]", config.synthesizer))
+    tagged.append(("drafter", "[drafter]", config.drafter))
+    tagged.append(("auditor", "[auditor]", config.auditor))
+    return [(label, a) for tag, label, a in tagged if blocks is None or tag in blocks]
+
+
+def api_key_problems(config: SyncadeConfig, env: dict[str, str] | None = None) -> list[str]:
+    """Actors that declare ``auth = "api"`` but have no key to use.
+
+    Returned rather than raised so :mod:`syncade.config_loader` owns the error type
+    (importing it here would cycle). The caller turns a non-empty list into a
+    ``ConfigError`` — i.e. **exit 50, at config load**.
+
+    Failing here is the entire point: the alternative is discovering it mid-run, after
+    both reviewers have already run and billed. Every problem is reported at once, not
+    one per re-run.
+    """
+    env = os.environ if env is None else env  # type: ignore[assignment]
+    problems: list[str] = []
+    for label, actor in authed_actors(config):
+        if actor.auth != "api":
+            continue
+        var = actor.key_var()
+        provider = getattr(actor, "provider", "?")
+        if provider == "openai":
+            # codex NEVER reads the environment — its key lives in CODEX_HOME. Demanding
+            # OPENAI_API_KEY here was a false requirement, and a DEAD END: we tell the user
+            # to run `codex login --with-api-key` (the only thing that works), and then
+            # refused to load anyway unless they also exported a var codex ignores.
+            #
+            # The openai `api` declaration is verified where it actually lives — the
+            # `codex login status` probe in auth_preflight, which refuses if codex is not
+            # logged in with an API key. That is the real check; this one was theatre.
+            continue
+        if var is None:
+            problems.append(
+                f'{label}: auth = "api" but provider "{provider}" has no conventional '
+                f"key var — set api_key_env explicitly"
+            )
+        elif not env.get(var):
+            problems.append(
+                f'{label}: auth = "api" requires {var} to be set, but it is not '
+                f'(export it, or use auth = "subscription")'
+            )
+    return problems

syncade/config_cold.py

@@ -0,0 +1,209 @@
+"""Config surfaces + defaults for syncade's three COLD actors.
+
+Cold = runs in an isolated git-init'd tempdir, never a repo worktree; sandboxed at
+``trusted-execute``; sees only what it is handed, and returns a strict schema:
+
+- **synthesizer** (the judge) — consolidates reviewer findings. Sees structured
+  reviewer outputs, never the diff.
+- **drafter** (``--draft-spec``) — turns a session transcript into a spec.
+- **auditor** (``--spec-audit``) — checks a spec for ambiguity before a review runs.
+
+All three were hardcoded to ``CodexAdapter`` with module-constant models, so
+``codex`` was a hard requirement for every one of them (PR-v2-23). They are now
+registry-resolved, and each gets a config block. Same shape, so they live together.
+
+This is a LEAF module (it imports only :mod:`syncade.config_types`) and it has to
+be: both ``config.py`` (which mounts the models) and the actor modules (which
+re-export the defaults) need these values, and ``config.py`` cannot import the
+actors — ``syncade.synthesizer``'s ``__init__`` imports ``driver``, which imports
+``config``. The defaults sit at the bottom of the graph; everyone imports down.
+
+The defaults are ALSO the historical values, which is why ``persistence`` and
+``metrics`` still read the ``SYNTHESIZER_*`` constants directly: for a legacy run
+whose artifacts never recorded a model, the honest fallback is "the default as it
+was", NOT whatever the operator has configured today.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import ConfigDict, Field, field_validator, model_validator
+
+from syncade.config_auth import AuthedActor
+from syncade.config_types import Thinking
+
+_COLD_MODELS: dict[str, str] = {
+    "openai": "gpt-5.5",
+    "anthropic": "claude-sonnet-4-6",
+}
+"""Default model per provider for a cold actor. See :class:`_ColdActorConfig`."""
+
+
+class _ColdActorConfig(AuthedActor):
+    """Shared base for the three cold actors: ``provider`` and ``model`` move as a
+    PAIR.
+
+    Setting ``provider`` alone re-derives ``model``. Without this,
+    ``[auditor]\\nprovider = "anthropic"`` would keep the ``gpt-5.5`` default and
+    hand a codex model to ``claude`` — a 404 at dispatch, and a baffling one, since
+    the user never typed "gpt-5.5" anywhere.
+
+    This mirrors :meth:`syncade.config_producer.ProducerConfig._keep_provider_and_model_paired`
+    exactly; the producer has had the same footgun guarded since it became
+    harness-aware. It only became POSSIBLE for the cold actors in PR-v2-23, which
+    is what made their provider configurable in the first place.
+
+    An explicit ``model`` always wins — this only fills in a model the user did not
+    give, so pinning an off-map model (a new release, a fine-tune) still works.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    @model_validator(mode="before")
+    @classmethod
+    def _keep_provider_and_model_paired(cls, data: object) -> object:
+        if not isinstance(data, dict):
+            return data
+        provider = data.get("provider")
+        if provider and "model" not in data and provider in _COLD_MODELS:
+            data = {**data, "model": _COLD_MODELS[provider]}
+        return data
+
+    @field_validator("provider", check_fields=False)
+    @classmethod
+    def _validate_provider(cls, v: str) -> str:
+        # Function-local import: config_cold is a leaf that must not import
+        # adapters at module level (import cycle via config → synthesizer → driver).
+        from syncade.adapters.registry import known_providers  # noqa: PLC0415
+
+        providers = known_providers()
+        if v not in providers:
+            raise ValueError(
+                f"unknown cold-actor provider {v!r}; known providers: {', '.join(providers)}"
+            )
+        return v
+
+
+SYNTHESIZER_PROVIDER = "openai"
+SYNTHESIZER_MODEL = "gpt-5.5"
+SYNTHESIZER_THINKING: Thinking = "high"
+SYNTHESIZER_PERMISSIONS: Literal["trusted-execute"] = "trusted-execute"
+
+
+class SynthesizerConfig(_ColdActorConfig):
+    """``[synthesizer]`` — the cold judge that consolidates reviewer outputs.
+
+    Until PR-v2-23 these were module constants and the driver imported
+    :class:`~syncade.adapters.openai.CodexAdapter` by name, which made ``codex`` a
+    hard requirement for EVERY run — even an all-Anthropic one, where the user paid
+    for both reviewers and then lost the round to a CLI they never configured.
+
+    The judge is deliberately NOT harness-aware (unlike the producer): a verdict has
+    to stay comparable across runs regardless of which harness the operator happened
+    to be coding in.
+    """
+
+    provider: str = Field(
+        default=SYNTHESIZER_PROVIDER,
+        description="Model provider for the judge. Resolved against the adapter "
+        "registry, exactly like a reviewer's.",
+    )
+    model: str = Field(
+        default=SYNTHESIZER_MODEL,
+        description=(
+            "Model identifier for the judge. Defaults to the same model as the "
+            "shipped reviewers, and they should be changed together: PR-28 moved "
+            "both to gpt-5.6-sol and PR-29 moved both back (the reviewers audited "
+            "too leniently on it —. Leaving the two pins "
+            "disagreeing sets a trap, because the edit that 'reconciles' them in "
+            "the wrong direction is the one that drags the reviewers onto the "
+            "lenient model."
+        ),
+    )
+    thinking: Thinking = Field(
+        default=SYNTHESIZER_THINKING,
+        description="Reasoning-effort budget. The judge reasons across every "
+        "reviewer's findings at once, so it gets the full budget by default.",
+    )
+    permissions: Literal["trusted-execute"] = Field(
+        default=SYNTHESIZER_PERMISSIONS,
+        description=(
+            "Tool-permission tier. Cold actors are locked to ``trusted-execute``: "
+            "the OS sandbox must stay ACTIVE and scoped to the synth's temp "
+            "workspace so isolation is structural, not prompt-dependent. ``yolo`` "
+            "maps to ``--dangerously-bypass-approvals-and-sandbox`` and is "
+            "rejected at config load."
+        ),
+    )
+
+
+DRAFTER_PROVIDER = "openai"
+DRAFTER_MODEL = "gpt-5.5"
+DRAFTER_THINKING: Thinking = "xhigh"
+DRAFTER_PERMISSIONS: Literal["trusted-execute"] = "trusted-execute"
+
+
+class DrafterConfig(_ColdActorConfig):
+    """``[drafter]`` — the cold spec drafter behind ``syncade --draft-spec``.
+
+    Turns a session transcript into a PR spec. Same codex-hardcoding bug as the
+    judge (PR-v2-23): a Claude-Code-only user could not draft a spec at all.
+    """
+
+    provider: str = Field(
+        default=DRAFTER_PROVIDER,
+        description="Model provider for the drafter. Resolved against the adapter "
+        "registry, exactly like a reviewer's.",
+    )
+    model: str = Field(
+        default=DRAFTER_MODEL,
+        description="Model identifier for the drafter.",
+    )
+    thinking: Thinking = Field(
+        default=DRAFTER_THINKING,
+        description=(
+            "Reasoning-effort budget. Higher than the judge's by default: drafting a "
+            "spec from a rambling session transcript is the hardest inference syncade "
+            "asks for, and a vague spec silently degrades every downstream review."
+        ),
+    )
+    permissions: Literal["trusted-execute"] = Field(
+        default=DRAFTER_PERMISSIONS,
+        description="Tool-permission tier. Locked to ``trusted-execute`` — cold "
+        "actors may not disable the OS sandbox. ``yolo`` is rejected at config load.",
+    )
+
+
+AUDITOR_PROVIDER = "openai"
+AUDITOR_MODEL = "gpt-5.5"
+AUDITOR_THINKING: Thinking = "xhigh"
+AUDITOR_PERMISSIONS: Literal["trusted-execute"] = "trusted-execute"
+
+
+class AuditorConfig(_ColdActorConfig):
+    """``[auditor]`` — the cold spec auditor behind ``syncade --spec-audit``.
+
+    Flags an ambiguous spec BEFORE a review burns reviewer spend against it. Same
+    codex-hardcoding bug as the judge and drafter (PR-v2-23).
+    """
+
+    provider: str = Field(
+        default=AUDITOR_PROVIDER,
+        description="Model provider for the auditor. Resolved against the adapter "
+        "registry, exactly like a reviewer's.",
+    )
+    model: str = Field(
+        default=AUDITOR_MODEL,
+        description="Model identifier for the auditor.",
+    )
+    thinking: Thinking = Field(
+        default=AUDITOR_THINKING,
+        description="Reasoning-effort budget. High by default: a missed ambiguity "
+        "here is paid for by every reviewer in every round downstream.",
+    )
+    permissions: Literal["trusted-execute"] = Field(
+        default=AUDITOR_PERMISSIONS,
+        description="Tool-permission tier. Locked to ``trusted-execute`` — cold "
+        "actors may not disable the OS sandbox. ``yolo`` is rejected at config load.",
+    )

syncade/config_gc.py

@@ -0,0 +1,55 @@
+"""``[gc]`` config block (PR-v2-9): run-artifact retention shared by ``--gc`` AND auto-prune.
+
+A LEAF module — pydantic only. Like :mod:`syncade.config_retry`, it deliberately does NOT import
+:mod:`syncade.gc` (heavy: gc → gc_protection → orchestrator → config → back here), so the defaults
+are LITERAL mirrors of ``gc.DEFAULT_KEEP`` / ``gc.DEFAULT_MAX_AGE_DAYS``, drift-guarded by a test
+(``tests/config/test_gc_config.py::test_defaults_reproduce_the_runtime_defaults``).
+
+These govern transcript pruning: the newest ``keep`` runs are always retained, and ``max_age_days``
+(0 = disabled) is an ADDITIONAL floor — a beyond-keep run is pruned only if it is ALSO older. The
+same policy feeds the auto-prune at each fresh loop AND the explicit ``syncade --gc`` pass, so the
+two can never diverge. Run directories are NEVER deleted; only bulky subprocess transcripts are.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+# Drift-guarded literal mirrors of syncade.gc.DEFAULT_KEEP / DEFAULT_MAX_AGE_DAYS (see docstring).
+_DEFAULT_KEEP = 20
+_DEFAULT_MAX_AGE_DAYS = 0
+
+
+class GcConfig(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    keep: int = Field(
+        default=_DEFAULT_KEEP,
+        ge=0,
+        description=(
+            "Newest N runs whose transcripts are ALWAYS kept when pruning (default "
+            f"{_DEFAULT_KEEP}). Run directories are never deleted — only bulky subprocess "
+            "transcripts. Governs BOTH the per-loop auto-prune and an explicit ``syncade --gc``."
+        ),
+    )
+    max_age_days: int = Field(
+        default=_DEFAULT_MAX_AGE_DAYS,
+        ge=0,
+        description=(
+            "Additional age floor: a beyond-``keep`` run is pruned only if ALSO older than this "
+            f"many days. {_DEFAULT_MAX_AGE_DAYS} (default) disables the age floor."
+        ),
+    )
+
+    @field_validator("keep", "max_age_days", mode="before")
+    @classmethod
+    def _strict_int(cls, value: object) -> object:
+        # Pydantic's lax mode coerces a quoted number ("0"→0), an exact float (1.0→1), and a boolean
+        # (bool subclasses int: false→0) silently. gc.keep=false/"0" → keep=0 would prune EVERY
+        # transcript; a float/string is a typo. Reject all three (exit 50), accept only a plain int.
+        if isinstance(value, bool) or not isinstance(value, int):
+            raise ValueError(
+                f"gc integer fields must be plain integers (got {value!r}); quoted numbers, "
+                "floats, and booleans are rejected"
+            )
+        return value