stargate-cli 1.0.0__py3-none-any.whl

stargate/commit.py

@@ -0,0 +1,253 @@
+"""Committing a finished run on its own branch, and saying why when that fails."""
+from __future__ import annotations
+
+import shlex
+import subprocess
+import sys
+from pathlib import Path
+
+from .core import RunContext, StargateError, git_quiet, print_output, run_process
+
+COMMIT_SUBJECT_CHARS = 72
+
+
+COMMIT_TIMEOUT_SECONDS = 600
+
+
+COMMIT_OUTPUT_LINES = 20
+
+
+def _commit_output_label(ctx: RunContext) -> str | None:
+    if ctx.mode == "fanout-task":
+        return f"task {ctx.slug}/commit"
+    return None
+
+
+def _labelled_output(label: str, output: str) -> str:
+    prefix = f"[{label}] "
+    chunks = output.splitlines(keepends=True)
+    return "".join(prefix + chunk for chunk in chunks) if chunks else f"[{label}]"
+
+
+def _print_commit_output(ctx: RunContext, output: str) -> None:
+    if not output:
+        return
+    label = _commit_output_label(ctx)
+    if label:
+        output = _labelled_output(label, output)
+    print_output(output, end="" if output.endswith("\n") else "\n")
+
+
+def _print_commit_diagnostic(ctx: RunContext, message: str) -> None:
+    label = _commit_output_label(ctx)
+    displayed = _labelled_output(label, message) if label else message
+    print_output(f"\n{displayed}", file=sys.stderr)
+
+
+def commit_message(ctx: RunContext, verdict: str, test_exit: int | None) -> str:
+    task = " ".join(ctx.task.split()) or "run"
+    suffix = f" ({verdict})"
+    available = max(0, COMMIT_SUBJECT_CHARS - len("stargate: ") - len(suffix))
+    subject_task = task[:available].rstrip()
+    subject = f"stargate: {subject_task}{suffix}"
+
+    if ctx.test_command:
+        tests = (
+            f"{ctx.test_command} (exit {test_exit})"
+            if test_exit is not None else f"{ctx.test_command} (not run)"
+        )
+    elif "report-only" in ctx.test_source:
+        tests = "not run (report-only detection)"
+    else:
+        tests = "not configured"
+
+    trailers = [
+        f"Stargate-Run-Id: {ctx.run_id}",
+        f"Stargate-Verdict: {verdict}",
+        f"Stargate-Base-Ref: {ctx.base_ref}",
+        f"Stargate-Base-Commit: {ctx.base_commit}",
+    ]
+    if test_exit is not None:
+        trailers.append(f"Stargate-Tests-Exit: {test_exit}")
+    return f"""\
+{subject}
+
+Task: {task}
+Verdict: {verdict}
+Tests: {tests}
+Base: {ctx.base_ref}
+Base commit: {ctx.base_commit}
+
+Produced by stargate agents, committed by the orchestrator; the agents
+themselves never run git. Plan, review and traces:
+.stargate/runs/{ctx.run_id}/
+
+{chr(10).join(trailers)}
+"""
+
+
+def stage_run_changes(ctx: RunContext) -> bool:
+    """Stage agent work while excluding untracked test-created entries."""
+    excludes = [f":(exclude,literal){name}" for name in sorted(ctx.test_artifacts)]
+    run_process(
+        ["git", "add", "-A", "--", ".", *excludes],
+        ctx.worktree,
+        output_label=_commit_output_label(ctx),
+    )
+    proc = subprocess.run(
+        ["git", "diff", "--cached", "--quiet"],
+        cwd=str(ctx.worktree),
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.PIPE,
+        text=True,
+    )
+    if proc.returncode not in (0, 1):
+        raise StargateError(
+            f"git diff --cached --quiet failed in {ctx.worktree}: "
+            f"{proc.stderr.strip()}"
+        )
+    return proc.returncode == 1
+
+
+def commit_failure(ctx: RunContext, reason: str, output: str = "") -> None:
+    tail = "\n".join(output.strip().splitlines()[-COMMIT_OUTPUT_LINES:])
+    message = (
+        f"Could not commit the run's work ({reason}). The changes are intact "
+        f"in {ctx.worktree}; any successfully staged changes remain staged, "
+        "and nothing was lost. A pre-commit hook or a commit signing "
+        "configuration in this repository is the usual cause -- a hook that "
+        "rewrote files may leave those rewrites unstaged. Fix the cause and "
+        "resume -- the recorded verdict is reused, so this retries the commit "
+        "without paying for another review:\n"
+        f"  stargate resume {ctx.run_id}\n"
+        "Or finish by hand with:\n"
+        f"  cd {shlex.quote(str(ctx.worktree))} && git commit"
+    )
+    if tail:
+        message += "\nLast output:\n" + "\n".join(
+            f"  {line}" for line in tail.splitlines()
+        )
+    ctx.commit_error = message
+    _print_commit_diagnostic(ctx, message)
+
+
+def commit_run(
+    ctx: RunContext,
+    verdict: str,
+    test_exit: int | None,
+    *,
+    allow_empty: bool = False,
+) -> str:
+    """Make at most one commit after the run reaches a terminal verdict.
+
+    Red results are committed too: they are the results most in need of a
+    durable recovery point, and the private, unpushed branch plus verdict in
+    the message keeps the history honest. Fixer passes are one editing session,
+    so committing before the final review would create misleading checkpoints.
+    """
+    ctx.commit_error = ""
+    if not ctx.worktree.exists():
+        return "empty"
+
+    branch = git_quiet(ctx.worktree, "rev-parse", "--abbrev-ref", "HEAD").strip()
+    if branch != ctx.branch:
+        commit_failure(
+            ctx,
+            f"worktree is on {branch!r}, not the run branch {ctx.branch!r}",
+        )
+        return "failed"
+
+    try:
+        changed = stage_run_changes(ctx)
+    except StargateError as exc:
+        commit_failure(ctx, f"staging failed: {exc}")
+        return "failed"
+    if not changed and not allow_empty:
+        return "empty"
+
+    message_path = ctx.artifacts / "commit-message.txt"
+    message_path.write_text(commit_message(ctx, verdict, test_exit))
+    output_label = _commit_output_label(ctx)
+    output_log: Path | None = None
+    if output_label:
+        # A log-backed process is tracked by the signal-safe runner. Its
+        # transcript is then printed as one labelled block and removed; the
+        # durable commit message remains the only new task artifact.
+        output_log = ctx.artifacts / ".commit-output.log"
+        output_log.unlink(missing_ok=True)
+    try:
+        proc = run_process(
+            [
+                "git",
+                "commit",
+                *(("--allow-empty",) if allow_empty else ()),
+                "-F",
+                str(message_path),
+            ],
+            ctx.worktree,
+            check=False,
+            timeout=COMMIT_TIMEOUT_SECONDS,
+            log_path=output_log,
+            output_label=output_label,
+        )
+    except StargateError as exc:
+        commit_failure(ctx, str(exc))
+        return "failed"
+    finally:
+        if output_log is not None:
+            output_log.unlink(missing_ok=True)
+    if output_label:
+        _print_commit_output(ctx, proc.stdout or "")
+    if proc.returncode:
+        commit_failure(ctx, f"git exit {proc.returncode}", proc.stdout or "")
+        return "failed"
+
+    ctx.commit = git_quiet(ctx.worktree, "rev-parse", "HEAD").strip()
+    # Known test output is deliberately left untracked, so it must not be
+    # blamed on a hook. The same exclusions reveal only unexpected rewrites.
+    excludes = [f":(exclude,literal){name}" for name in sorted(ctx.test_artifacts)]
+    status = git_quiet(
+        ctx.worktree, "status", "--porcelain", "--", ".", *excludes
+    )
+    if status:
+        warning = (
+            "Warning: the commit succeeded, but a repository hook modified "
+            f"files afterward. Those changes remain uncommitted in {ctx.worktree}; "
+            "stargate will not create a second commit."
+        )
+        _print_commit_diagnostic(ctx, warning)
+    return "committed"
+
+
+def terminal_commit_at_head(ctx: RunContext, verdict: str) -> str:
+    """Recover a terminal commit made just before state persistence stopped.
+
+    A signal can arrive after ``git commit`` succeeds but before ``finish``
+    records the terminal fields in state.json.  The commit trailers make that
+    narrow window distinguishable from both task commits and user commits, so
+    a resume can adopt the commit instead of adding another empty one.
+    """
+    if not ctx.worktree.exists():
+        return ""
+    try:
+        head = git_quiet(ctx.worktree, "rev-parse", "HEAD").strip()
+        message = git_quiet(ctx.worktree, "log", "-1", "--format=%B", "HEAD")
+    except StargateError:
+        return ""
+    trailers = set(message.splitlines())
+    if (
+        f"Stargate-Run-Id: {ctx.run_id}" in trailers
+        and f"Stargate-Verdict: {verdict}" in trailers
+    ):
+        return head
+    return ""
+
+
+def commit_summary(ctx: RunContext, enabled: bool) -> str:
+    if not enabled:
+        return "disabled"
+    if ctx.commit_error:
+        return "FAILED"
+    if ctx.commit:
+        return ctx.commit
+    return "none (nothing to commit)"

stargate/config.py

@@ -0,0 +1,422 @@
+"""Everything read off disk to configure a run: the layered YAML, the agent
+entry each role resolves to, and the prompt files."""
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from .core import StargateError
+
+# Per-project override. Deliberately NOT "agents.yaml": that name is common
+# enough that a global install would silently pick up an unrelated repo's file.
+PROJECT_CONFIG = ".stargate.yaml"
+
+
+ROLES = ("architect", "developer", "reviewer", "fixer")
+
+
+PROMPTS = (*ROLES, "fanout")
+
+
+def user_config() -> Path:
+    base = os.environ.get("XDG_CONFIG_HOME") or "~/.config"
+    return Path(os.path.expanduser(base)) / "stargate" / "agents.yaml"
+
+
+def resolve_config(arg: str | None, script_dir: Path) -> list[Path]:
+    """Config sources, most specific first."""
+    if arg:
+        # Explicit config is also the escape hatch for resuming past a broken
+        # definition, so layering anything under it would make it non-explicit.
+        return [Path(arg).expanduser().resolve()]
+
+    project = (Path.cwd() / PROJECT_CONFIG).resolve()
+    user = user_config().resolve()
+    packaged = (script_dir / "agents.yaml").resolve()
+    candidates = [path for path in (project, user) if path.exists()]
+    # Lookup never walks to a parent or follows a path from config, so a project
+    # cannot accidentally pull configuration from an unrelated repository.
+    return list(dict.fromkeys([*candidates, packaged]))
+
+
+def init_prompts(script_dir: Path) -> int:
+    target = user_config().parent / "prompts"
+    target.mkdir(parents=True, exist_ok=True)
+    for name in PROMPTS:
+        dest = target / f"{name}.md"
+        if dest.exists():
+            print(f"kept    {dest}")
+            continue
+        dest.write_text((script_dir / "prompts" / f"{name}.md").read_text())
+        print(f"wrote   {dest}")
+    print("\nEdit these to override the defaults. Delete one to fall back.")
+    return 0
+
+
+def init_config(script_dir: Path) -> int:
+    target = user_config()
+    if target.exists():
+        print(f"Already exists, not overwriting: {target}")
+        return 1
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text((script_dir / "agents.yaml").read_text())
+    print(f"Wrote {target}\nEdit it to set test_command, models, timeouts.")
+    return 0
+
+
+def layer_config(base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any]:
+    """Merge sections by key while replacing each structured entry whole."""
+    merged = dict(base)
+    for section, value in override.items():
+        inherited = merged.get(section)
+        # A bare mapping section such as `settings:` must not erase its base.
+        # ponytail: add a delete sentinel only if an overlay needs one.
+        if isinstance(inherited, dict) and value is None:
+            continue
+        if isinstance(inherited, dict) and isinstance(value, dict):
+            merged[section] = {**inherited, **value}
+        else:
+            merged[section] = value
+    return merged
+
+
+def load_config(
+    paths: list[Path],
+) -> tuple[dict[str, Any], list[tuple[Path, dict[str, Any]]]]:
+    """Load the effective config and retain the layers that supplied it."""
+    layers: list[tuple[Path, dict[str, Any]]] = []
+    for path in paths:
+        if not path.exists():
+            raise StargateError(f"Config not found: {path}")
+        data = yaml.safe_load(path.read_text()) or {}
+        if not isinstance(data, dict):
+            raise StargateError(f"Config must be a YAML mapping: {path}")
+        layers.append((path, data))
+
+    config: dict[str, Any] = {}
+    for _, data in reversed(layers):
+        config = layer_config(config, data)
+
+    agents = config.get("agents")
+    workflow = config.get("workflow")
+    if (
+        not isinstance(agents, dict) or not agents
+        or not isinstance(workflow, dict) or not workflow
+    ):
+        raise StargateError("Config must contain 'agents' and 'workflow'.")
+    if "settings" in config and not isinstance(config["settings"], dict):
+        raise StargateError("Config 'settings' must be a mapping.")
+    return config, layers
+
+
+def agent_entry(config: dict[str, Any], role: str) -> dict[str, Any]:
+    try:
+        return config["agents"][config["workflow"][role]]
+    except KeyError as exc:
+        raise StargateError(f"Invalid agent configuration for role '{role}'.") from exc
+
+
+def agent_env(entry: dict[str, Any]) -> dict[str, str] | None:
+    """The environment for one agent, or None to inherit unchanged.
+
+    A null value REMOVES the variable. That is the case worth supporting: an
+    ANTHROPIC_API_KEY exported globally shadows the CLI's own login, and
+    without this the only fix is to unset it for the whole orchestrator.
+    """
+    declared = entry.get("env")
+    if not declared:
+        return None
+    if not isinstance(declared, dict):
+        raise StargateError("An agent's 'env' must be a mapping of names to values.")
+    env = dict(os.environ)
+    for key, value in declared.items():
+        if value is None:
+            env.pop(str(key), None)
+        else:
+            env[str(key)] = str(value)
+    return env
+
+
+def env_summary(entry: dict[str, Any]) -> str:
+    """Which variables an agent overrides. Names only -- values are secrets."""
+    declared = entry.get("env") or {}
+    if not isinstance(declared, dict) or not declared:
+        return ""
+    return ", ".join(
+        f"{key} (unset)" if value is None else str(key)
+        for key, value in declared.items()
+    )
+
+
+def parse_usage(transcript: str, pattern: str | None) -> int:
+    """Tokens an agent reported spending, via a regex the CONFIG supplies.
+
+    The orchestrator cannot see inside an agent — most of a run's tokens are the
+    model reading the repo, never crossing this process. So the only usable
+    number is whatever the CLI prints, and the shape of that is the vendor's
+    business, not this file's.
+    """
+    if not pattern:
+        return 0
+    # The last match, never the first: an agent that reads or writes test
+    # fixtures echoes strings shaped like the usage footer into its own
+    # transcript, and the CLI prints the real total once, at the end.
+    matches = list(re.finditer(pattern, transcript))
+    if not matches or not matches[-1].groups():
+        return 0
+    match = matches[-1]
+    try:
+        return int(match.group(1).replace(",", "").replace(".", "").replace("_", ""))
+    except ValueError:
+        return 0
+
+
+def token_cap(config: dict[str, Any]) -> int:
+    return int(config.get("settings", {}).get("max_task_tokens", 0) or 0)
+
+
+def agent_command(config: dict[str, Any], role: str) -> list[str]:
+    command = agent_entry(config, role).get("command")
+    if not isinstance(command, list) or not command:
+        raise StargateError(f"Agent for role '{role}' needs a non-empty command list.")
+    return [str(x) for x in command]
+
+
+TEST_COMMAND_PLACEHOLDER = "{test_command}"
+
+
+# The packaged allowlist syntax uses parentheses and commas as structure and
+# `*` as a wildcard. Interpolating any of them would grant a PATTERN broader
+# than the one project command stargate runs, even though config is trusted.
+TEST_COMMAND_PATTERN_UNSAFE = re.compile(r"[(),*\x00-\x1f\x7f]")
+
+
+def test_command_grant(test_command: str) -> str | None:
+    """The exact command safe to place in a permission pattern, if any."""
+    command = (test_command or "").strip()
+    if not command or TEST_COMMAND_PATTERN_UNSAFE.search(command):
+        return None
+    return command
+
+
+def expand_test_command(command: list[str], test_command: str) -> list[str]:
+    """Expand {test_command}, dropping its whole option when no grant is safe.
+
+    An empty value is not safe here: it can become Bash(), an empty argv item,
+    or leave an option to consume the agent prompt as its value. The command
+    placeholder therefore belongs in an option value, never in argv[0].
+    """
+    grant = test_command_grant(test_command)
+    expanded: list[str] = []
+    for index, part in enumerate(command):
+        if TEST_COMMAND_PLACEHOLDER not in part:
+            expanded.append(part)
+            continue
+        if index == 0:
+            raise StargateError(
+                "{test_command} cannot be used as an agent executable; put it "
+                "in an option value."
+            )
+        if grant is not None:
+            expanded.append(part.replace(TEST_COMMAND_PLACEHOLDER, grant))
+            continue
+        # An option containing the placeholder is self-contained, regardless
+        # of its spelling. A separate value may itself contain `=`, so only
+        # its position -- not that character -- identifies the option to drop.
+        if not part.startswith("-") and expanded and expanded[-1].startswith("-"):
+            expanded.pop()
+    if not expanded:
+        raise StargateError("Expanding {test_command} left an empty agent command.")
+    return expanded
+
+
+AGENT_RETRIES_DEFAULT = 0
+
+
+AGENT_RETRY_BACKOFF_DEFAULT = 10.0
+
+
+def retry_settings(config: dict[str, Any]) -> tuple[int, float]:
+    settings = config.get("settings", {})
+    retries = max(0, int(settings.get("agent_retries", AGENT_RETRIES_DEFAULT) or 0))
+    backoff = max(0.0, float(
+        settings.get(
+            "agent_retry_backoff_seconds", AGENT_RETRY_BACKOFF_DEFAULT
+        ) or 0
+    ))
+    return retries, backoff
+
+
+def prompt_dirs(config: dict[str, Any], script_dir: Path) -> list[Path]:
+    """Prompt sources, most specific first. Overrides are per-file: a custom
+    reviewer.md is picked up while the other three fall back to the defaults."""
+    configured = str(config.get("settings", {}).get("prompts_dir", "") or "").strip()
+    dirs = [Path(os.path.expanduser(configured)).resolve()] if configured else []
+    return [*dirs, user_config().parent / "prompts", script_dir / "prompts"]
+
+
+def find_prompt(dirs: list[Path], name: str) -> Path:
+    for base in dirs:
+        candidate = base / f"{name}.md"
+        if candidate.exists():
+            return candidate
+    searched = ", ".join(str(d) for d in dirs)
+    raise StargateError(f"Prompt {name}.md not found in: {searched}")
+
+
+def render_prompt(dirs: list[Path], name: str, **values: str) -> str:
+    """Substitute only the placeholders we define, in a single pass.
+
+    Not str.format: a custom prompt is free to contain JSON, CSS or an f-string
+    example, and every brace in it would otherwise have to be escaped or the
+    run dies with KeyError before a single agent starts.
+
+    One pass rather than one replace per key, because the values are agent
+    output. Replacing in sequence rescans what the previous key just inserted,
+    so a review whose own text contains `{tests}` reached the fixer with the
+    test report spliced inside the reviewer's finding.
+    """
+    text = find_prompt(dirs, name).read_text()
+    if not values:
+        return text
+    pattern = re.compile("|".join(re.escape("{" + key + "}") for key in values))
+    # A function replacement, so a value containing backslashes or \1 is
+    # inserted literally rather than read as a group reference.
+    return pattern.sub(lambda match: values[match.group(0)[1:-1]], text)
+
+
+def value_source(
+    layers: list[tuple[Path, dict[str, Any]]], section: str, key: str
+) -> str:
+    """The numbered layer that supplied one effective value."""
+    for index, (_, data) in enumerate(layers, 1):
+        block = data.get(section)
+        if isinstance(block, dict) and key in block:
+            return f"[{index}]"
+    return "(default)"
+
+
+# Committing is ON by default. The friction this removes is a default-level
+# problem: a run whose work exists only as a dirty worktree cannot be built on
+# without a hand-made branch and commit, and a `git worktree remove --force`
+# destroys it, because the artifacts hold traces and prose, not code. A flag
+# nobody knows exists does not fix that. Unlike a detected test command, this
+# executes nothing the user has not already sanctioned: the commit lands on a
+# branch stargate created, in a worktree stargate created, and is only pushed
+# with --pr in that invocation, never merged. The change is narrow -- `git status` in
+# the worktree goes clean, while `git diff <base>` still shows every change.
+# `commit: false` restores the old behaviour exactly.
+SEVERITIES = ("high", "medium", "low")
+
+
+def blocking_severities(config: dict[str, Any]) -> tuple[str, ...]:
+    """Validate the opt-in policy; only an empty policy preserves reviewer authority."""
+    value = config.get("settings", {}).get("blocking_severities")
+    if value is None:
+        return ()
+    if not isinstance(value, list):
+        raise StargateError(
+            "settings.blocking_severities must be a list of severity names "
+            f"({', '.join(SEVERITIES)}), e.g. [high, medium]; got {value!r}."
+        )
+    names = []
+    for item in value:
+        name = item.strip().lower() if isinstance(item, str) else item
+        if name not in SEVERITIES:
+            raise StargateError(
+                "settings.blocking_severities contains an unknown severity "
+                f"{item!r}; valid names are {', '.join(SEVERITIES)}."
+            )
+        names.append(name)
+    return tuple(dict.fromkeys(names))
+
+
+def task_sources(config: dict[str, Any]) -> list[dict[str, Any]]:
+    """Validate sources before fetching; normalize hosts and command arguments."""
+    value = config.get("task_sources")
+    if value is None:
+        return []
+    if not isinstance(value, list):
+        raise StargateError("task_sources must be a list of source mappings.")
+    sources = []
+    for index, entry in enumerate(value):
+        label = f"task_sources[{index}]"
+        if not isinstance(entry, dict):
+            raise StargateError(f"{label} must be a mapping.")
+        hosts = entry.get("hosts")
+        if not isinstance(hosts, list) or not hosts or any(
+            not isinstance(host, str) or not host.strip() for host in hosts
+        ):
+            raise StargateError(f"{label}.hosts must be a non-empty list of non-empty host names.")
+        commands = entry.get("commands")
+        if not isinstance(commands, list) or not commands:
+            raise StargateError(f"{label}.commands must be a non-empty list of commands.")
+        normalized = []
+        for command_index, command in enumerate(commands):
+            command_label = f"{label}.commands[{command_index}]"
+            if not isinstance(command, list) or not command:
+                raise StargateError(
+                    f"{command_label} must be a non-empty list of command arguments; "
+                    "commands takes a list of commands, not a flat argument list."
+                )
+            if any(not isinstance(part, (str, int, float)) for part in command):
+                raise StargateError(f"{command_label} arguments must be strings or numbers.")
+            argv = [str(part) for part in command]
+            if not argv[0].strip():
+                raise StargateError(f"{command_label}[0] must name an executable.")
+            normalized.append(argv)
+        if entry.get("env") is not None and not isinstance(entry["env"], dict):
+            raise StargateError(f"{label}.env must be a mapping of names to values.")
+        sources.append({**entry, "hosts": [host.lower() for host in hosts], "commands": normalized})
+    return sources
+
+
+def pull_request_command(config: dict[str, Any]) -> list[str] | None:
+    """Validate how to publish; configuration never authorizes publication."""
+    block = config.get("pull_request")
+    if block is None:
+        return None
+    if not isinstance(block, dict):
+        raise StargateError("pull_request must be a mapping with a 'command'.")
+    command = block.get("command")
+    if not isinstance(command, list) or not command:
+        raise StargateError("pull_request.command must be a non-empty list of command arguments.")
+    if any(not isinstance(part, (str, int, float)) for part in command):
+        raise StargateError("pull_request.command arguments must be strings or numbers.")
+    argv = [str(part) for part in command]
+    if not argv[0].strip():
+        raise StargateError("pull_request.command[0] must name an executable.")
+    if not any("{branch}" in part for part in argv):
+        raise StargateError(
+            "pull_request.command must pass {branch} to the command; without it the pull "
+            "request would be opened from whatever branch is checked out."
+        )
+    if block.get("env") is not None and not isinstance(block["env"], dict):
+        raise StargateError("pull_request.env must be a mapping of names to values.")
+    return argv
+
+
+def validate_publication_request(config: dict[str, Any], *, requested: bool) -> None:
+    command = pull_request_command(config)
+    if requested:
+        if command is None:
+            raise StargateError(
+                "--pr needs a pull_request.command in your config; the config says how "
+                "to publish, the flag says whether. No agent was started."
+            )
+        if not commit_enabled(config):
+            raise StargateError(
+                "--pr requires settings.commit: true; without a commit there is "
+                "nothing to publish. No agent was started."
+            )
+
+
+def commit_enabled(config: dict[str, Any]) -> bool:
+    value = config.get("settings", {}).get("commit", True)
+    if not isinstance(value, bool):
+        raise StargateError("settings.commit must be true or false.")
+    return value