caokit 0.3.0.dev0__py3-none-any.whl

caokit/project.py

@@ -0,0 +1,359 @@
+"""Project-level configuration: per-project overrides layered on the user-level company.
+
+The user-level ``caokit.toml`` (``~/.config/caokit``) defines the default roster. A
+project may add ``<repo>/.company/caokit.toml`` with a project name and overrides for
+individual roles. The *effective* config is the user-level one with those overrides
+applied, and its profiles are named ``<project>_<role>-<tool>`` so projects never
+overwrite each other in CAO's machine-global profile store.
+
+Example project file::
+
+    schema = 1
+    [project]
+    name = "myapp"
+    [policy]
+    allow_soft_engineer = false
+    [roles.engineer]
+    model = "sonnet"            # tool omitted: keep the user-level tool
+"""
+
+import json
+import tomllib
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from .adapters import ROLES, AdapterError, Runner, default_runner, load_adapter, validate_model
+from .config import POLICY_KEYS, SCHEMA, Binding, Config, ConfigError, _only
+from .render import validate_project_name
+from .roster import check_roster
+
+# Lives under .company/, which the managed .gitignore block ignores (except contracts/).
+PROJECT_FILE = Path(".company") / "caokit.toml"
+_POLICY_KEYS = POLICY_KEYS
+
+
+@dataclass
+class Overrides:
+    """A project's name and its per-role / policy overrides.
+
+    Attributes:
+        name: Project slug used to namespace profile names.
+        roles: For each overridden role, only the keys given: ``tool`` and/or ``model``.
+        policy: Policy switches the project sets explicitly.
+        keep_archived_days: Days an archived task file is kept before ``tasks prune``
+            deletes it; None keeps archived tasks forever.
+        worktrees: Give each source-changing task its own git worktree (CAO ``use_worktree``).
+    """
+
+    name: str
+    roles: dict[str, dict[str, str]] = field(default_factory=dict)
+    policy: dict[str, bool] = field(default_factory=dict)
+    keep_archived_days: int | None = None
+    worktrees: bool = False
+
+
+def parse_overrides(d: dict[str, Any]) -> Overrides:
+    """Validate a parsed project ``caokit.toml`` and build :class:`Overrides`.
+
+    Args:
+        d: The dict produced by parsing the project file.
+
+    Returns:
+        The validated overrides.
+
+    Raises:
+        ConfigError: Wrong schema, missing/invalid project name, unknown key or role,
+            or a value of the wrong type.
+    """
+    _only(d, {"schema", "project", "policy", "roles", "tasks"}, "")
+    if d.get("schema") != SCHEMA:
+        raise ConfigError(f"schema must be {SCHEMA} (got {d.get('schema')!r})")
+    proj = d.get("project")
+    if not isinstance(proj, dict) or not isinstance(proj.get("name"), str):
+        raise ConfigError("project.name is required (a string)")
+    _only(proj, {"name"}, "project")
+    try:
+        name = validate_project_name(proj["name"])
+    except ValueError as e:
+        raise ConfigError(str(e)) from e
+    pol = d.get("policy", {})
+    _only(pol, _POLICY_KEYS, "policy")
+    for k, v in pol.items():
+        if not isinstance(v, bool):
+            raise ConfigError(f"policy.{k} must be true or false")
+    roles: dict[str, dict[str, str]] = {}
+    for role, o in d.get("roles", {}).items():
+        if role not in ROLES:
+            raise ConfigError(f"unknown role: roles.{role} (valid: {', '.join(ROLES)})")
+        _only(o, {"tool", "model"}, f"roles.{role}")
+        for k, v in o.items():
+            if not isinstance(v, str) or not v:
+                raise ConfigError(f"roles.{role}.{k} must be a non-empty string")
+        roles[role] = dict(o)
+    tasks = d.get("tasks", {})
+    _only(tasks, {"keep_archived_days", "worktrees"}, "tasks")
+    if not isinstance(tasks.get("worktrees", False), bool):
+        raise ConfigError("tasks.worktrees must be true or false")
+    days = tasks.get("keep_archived_days")
+    if days is not None and (isinstance(days, bool) or not isinstance(days, int) or days < 1):
+        raise ConfigError("tasks.keep_archived_days must be a whole number of days, at least 1")
+    return Overrides(
+        name=name,
+        roles=roles,
+        policy=dict(pol),
+        keep_archived_days=days,
+        worktrees=tasks.get("worktrees", False),
+    )
+
+
+def load_overrides(repo: Path) -> Overrides:
+    """Read and validate ``<repo>/.company/caokit.toml``.
+
+    Args:
+        repo: Project root.
+
+    Returns:
+        The validated overrides.
+
+    Raises:
+        ConfigError: The file is missing, is not valid TOML, or fails validation.
+    """
+    path = Path(repo) / PROJECT_FILE
+    if not path.is_file():
+        raise ConfigError(
+            f"no project config at {path}; run `caokit init {repo} --name <project>` first"
+        )
+    try:
+        return parse_overrides(tomllib.loads(path.read_text(encoding="utf-8")))
+    except ValueError as e:  # TOMLDecodeError subclasses ValueError
+        raise ConfigError(f"invalid TOML in {path}: {e}") from e
+
+
+def worktrees_enabled(repo: Path) -> bool:
+    """Return True if the project turned per-task worktrees on (False without a project file).
+
+    Raises:
+        ConfigError: The project file exists but is invalid.
+    """
+    if not (Path(repo) / PROJECT_FILE).is_file():
+        return False
+    return load_overrides(repo).worktrees
+
+
+def dump_overrides(ov: Overrides) -> str:
+    """Serialise overrides to TOML text.
+
+    Args:
+        ov: The overrides to write.
+
+    Returns:
+        TOML text that :func:`parse_overrides` round-trips.
+    """
+    q = json.dumps  # JSON string escaping is valid TOML basic-string escaping
+    out = [f"schema = {SCHEMA}", "", "[project]", f"name = {q(ov.name)}"]
+    if ov.policy:
+        out += ["", "[policy]"] + [f"{k} = {str(v).lower()}" for k, v in ov.policy.items()]
+    for role in ROLES:  # fixed order keeps the file stable across runs
+        if role in ov.roles:
+            out += ["", f"[roles.{role}]"] + [f"{k} = {q(v)}" for k, v in ov.roles[role].items()]
+    tasks = []
+    if ov.keep_archived_days is not None:
+        tasks.append(f"keep_archived_days = {ov.keep_archived_days}")
+    if ov.worktrees:
+        tasks.append("worktrees = true")
+    if tasks:
+        out += ["", "[tasks]", *tasks]
+    return "\n".join(out) + "\n"
+
+
+def apply_overrides(base: Config, ov: Overrides) -> Config:
+    """Layer a project's overrides on the user-level config.
+
+    Merge rules, per role: a given ``tool``/``model`` replaces the base value. If the
+    tool changes and no model is given, the base model is dropped (a model ID from one
+    tool is meaningless for another), so the tool default applies until one is set.
+
+    Args:
+        base: The user-level configuration.
+        ov: The project's overrides.
+
+    Returns:
+        A new config named for the project; ``base`` is not modified.
+    """
+    roles = {r: Binding(b.tool, b.model) for r, b in base.roles.items()}
+    for role, o in ov.roles.items():
+        b = base.roles[role]
+        tool = o.get("tool", b.tool)
+        if "model" in o:
+            model: str | None = o["model"]
+        elif tool != b.tool:
+            model = None
+        else:
+            model = b.model
+        roles[role] = Binding(tool, model)
+    return Config(
+        roles=roles,
+        allow_soft_engineer=ov.policy.get("allow_soft_engineer", base.allow_soft_engineer),
+        allow_soft_general=ov.policy.get("allow_soft_general", base.allow_soft_general),
+        allow_single_provider=ov.policy.get("allow_single_provider", base.allow_single_provider),
+        expected_cao_version=base.expected_cao_version,
+        project=ov.name,
+    )
+
+
+def parse_override_specs(specs: Sequence[str]) -> dict[str, dict[str, str]]:
+    """Parse ``--override`` CLI values into per-role overrides.
+
+    Accepted forms: ``role=tool``, ``role=tool:model`` and ``role=:model`` (model only,
+    keeping the user-level tool).
+
+    Args:
+        specs: Values such as ``engineer=claude:sonnet``.
+
+    Returns:
+        Mapping of role to the keys given for it.
+
+    Raises:
+        ConfigError: A spec is malformed or names an unknown role.
+    """
+    out: dict[str, dict[str, str]] = {}
+    for spec in specs:
+        role, sep, rest = spec.partition("=")
+        if not sep or role not in ROLES or not rest:
+            raise ConfigError(
+                f"bad --override {spec!r}: use role=tool[:model] or role=:model "
+                f"(roles: {', '.join(ROLES)})"
+            )
+        tool, _, model = rest.partition(":")
+        entry: dict[str, str] = {}
+        if tool:
+            entry["tool"] = tool
+        if model:
+            entry["model"] = model
+        out[role] = {**out.get(role, {}), **entry}
+    return out
+
+
+def resolve_project(
+    repo: Path, base: Config, name: str | None, specs: Sequence[str]
+) -> tuple[Config, Overrides | None]:
+    """Work out the effective config for a project.
+
+    With ``name`` or ``specs``, build new overrides (to be written by the caller).
+    Otherwise load the project's existing file. With neither and no file, the project
+    is not namespaced and the user-level config applies unchanged.
+
+    Args:
+        repo: Project root.
+        base: The user-level configuration.
+        name: Project slug from ``--name``, if given.
+        specs: ``--override`` values, if any.
+
+    Returns:
+        ``(effective_config, new_overrides)``. ``new_overrides`` is None when nothing
+        new needs writing.
+
+    Raises:
+        ConfigError: Overrides without a name, bad specs, or an invalid project file.
+    """
+    if name or specs:
+        if not name:
+            raise ConfigError("--override needs --name <project> so the profiles are namespaced")
+        try:
+            validate_project_name(name)
+        except ValueError as e:
+            raise ConfigError(str(e)) from e
+        ov = Overrides(name=name, roles=parse_override_specs(specs))
+        return apply_overrides(base, ov), ov
+    if (Path(repo) / PROJECT_FILE).is_file():
+        return apply_overrides(base, load_overrides(repo)), None
+    return base, None
+
+
+def effective_config(repo: Path, base: Config) -> Config:
+    """Return the project's effective config (requires an existing project file).
+
+    Args:
+        repo: Project root.
+        base: The user-level configuration.
+
+    Returns:
+        ``base`` with the project's overrides applied and its name set.
+
+    Raises:
+        ConfigError: The project file is missing or invalid.
+    """
+    return apply_overrides(base, load_overrides(repo))
+
+
+def check_effective(
+    cfg: Config, ov: Overrides | None, runner: Runner = default_runner
+) -> tuple[list[str], list[str]]:
+    """Run the roster rules and validate overridden models against their tools.
+
+    Args:
+        cfg: The effective config.
+        ov: The overrides being applied, or None to check the roster rules only.
+        runner: Command runner used to ask tools for their model lists.
+
+    Returns:
+        ``(errors, warnings)``.
+    """
+    res = check_roster(cfg)
+    errors, warnings = list(res.errors), list(res.warnings)
+    for role in ov.roles if ov else {}:
+        b = cfg.roles[role]
+        if not b.model:
+            continue
+        try:
+            adapter = load_adapter(b.tool)
+        except AdapterError:
+            continue  # unknown tool is already reported by the roster rules
+        e, w = validate_model(adapter, b.model, runner)
+        errors += [f"roles.{role}: {x}" for x in e]
+        warnings += [f"roles.{role}: {x}" for x in w]
+    return errors, warnings
+
+
+def set_keep_archived_days(repo: Path, days: int) -> Path:
+    """Record how long archived tasks are kept in the project's ``caokit.toml``.
+
+    Args:
+        repo: Project root; it must already have a project file (``caokit init --name``).
+        days: Days to keep an archived task, at least 1.
+
+    Returns:
+        The path written.
+
+    Raises:
+        ConfigError: No project file, an invalid existing file, or ``days`` below 1.
+    """
+    if days < 1:
+        raise ConfigError("tasks.keep_archived_days must be a whole number of days, at least 1")
+    ov = load_overrides(repo)
+    ov.keep_archived_days = days
+    path = Path(repo) / PROJECT_FILE
+    path.write_text(dump_overrides(ov), encoding="utf-8")
+    return path
+
+
+def set_worktrees(repo: Path, on: bool) -> Path:
+    """Turn per-task git worktrees on or off in the project's ``caokit.toml``.
+
+    Args:
+        repo: Project root; it must already have a project file (``caokit init --name``).
+        on: True to have the General dispatch each engineer into its own worktree.
+
+    Returns:
+        The path written.
+
+    Raises:
+        ConfigError: No project file or an invalid existing one.
+    """
+    ov = load_overrides(repo)
+    ov.worktrees = on
+    path = Path(repo) / PROJECT_FILE
+    path.write_text(dump_overrides(ov), encoding="utf-8")
+    return path

caokit/render.py

@@ -0,0 +1,129 @@
+"""Render concrete CAO profiles from a tool-agnostic role body and a tool adapter."""
+
+import json
+import re
+from importlib import resources
+
+from .adapters import Adapter
+
+# Mirrors CAO 2.5.4 install_service._PROFILE_NAME_RE; dots are NOT allowed.
+PROFILE_NAME_RE = r"^[A-Za-z0-9_-]{1,64}$"
+# Role and tool IDs: lowercase alphanumerics only, so "-" in a name is an unambiguous separator.
+_PART_RE = re.compile(r"^[a-z0-9]+$")
+
+
+# Project slug: lowercase alphanumerics and "-", at most 24 chars. It must not contain "_" because
+# "_" separates the project from "<role>-<tool>", which keeps the full name unambiguous, and the
+# cap keeps "<project>_<role>-<tool>" well under CAO's 64-character limit.
+PROJECT_RE = re.compile(r"^[a-z0-9][a-z0-9-]{0,23}$")
+
+
+def validate_project_name(project: str) -> str:
+    """Check a project slug.
+
+    Args:
+        project: Candidate slug, e.g. ``myapp``.
+
+    Returns:
+        The slug unchanged.
+
+    Raises:
+        ValueError: If it is not 1-24 chars of lowercase letters, digits and ``-``.
+    """
+    if not PROJECT_RE.match(project):
+        raise ValueError(
+            f"invalid project name {project!r}: use 1-24 lowercase letters, digits or '-' "
+            "(start with a letter or digit)"
+        )
+    return project
+
+
+def profile_name(role: str, tool: str, project: str | None = None) -> str:
+    """Build the concrete CAO profile name.
+
+    Shared profiles are ``<role>-<tool>``; project-scoped ones are
+    ``<project>_<role>-<tool>`` so projects never overwrite each other in CAO's
+    machine-global profile store.
+
+    Args:
+        role: Role ID, e.g. ``inspector``.
+        tool: Tool ID, e.g. ``antigravity``.
+        project: Project slug, or None for the shared (machine-wide) profile.
+
+    Returns:
+        The profile name, e.g. ``inspector-antigravity`` or ``myapp_inspector-antigravity``.
+
+    Raises:
+        ValueError: If a part is invalid or the result is not a valid CAO profile name.
+    """
+    for part in (role, tool):
+        if not _PART_RE.match(part):
+            raise ValueError(f"invalid name part {part!r}")
+    name = f"{role}-{tool}"
+    if project is not None:
+        name = f"{validate_project_name(project)}_{name}"
+    if not re.match(PROFILE_NAME_RE, name):
+        raise ValueError(f"invalid profile name {name!r}")
+    return name
+
+
+def load_role(role: str) -> str:
+    """Read the tool-agnostic role file shipped in the package.
+
+    Args:
+        role: Role ID (validated so it cannot traverse out of ``data/roles``).
+
+    Returns:
+        The full markdown text, frontmatter included.
+
+    Raises:
+        ValueError: If ``role`` is not a valid role ID.
+    """
+    if not _PART_RE.match(role):
+        raise ValueError(f"invalid role {role!r}")
+    return (resources.files("caokit") / "data" / "roles" / (role + ".md")).read_text(
+        encoding="utf-8"
+    )
+
+
+def render_profile(
+    role: str, adapter: Adapter, model: str | None, project: str | None = None
+) -> str:
+    """Combine a role body with a tool adapter into a complete CAO profile.
+
+    Output is deterministic, since CAO stores profiles byte for byte and the
+    installer verifies the stored copy against this text.
+
+    Args:
+        role: Role ID.
+        adapter: The tool adapter that fills the role.
+        model: Model ID to pin, or None to omit ``model:`` (tool default applies).
+        project: Project slug to namespace the profile name with, or None for shared.
+
+    Returns:
+        The profile text (frontmatter + body + optional "Tool notes" section).
+
+    Raises:
+        ValueError: If the role file has no frontmatter.
+    """
+    text = load_role(role)
+    m = re.match(r"^---\n(.*?)\n---\n(.*)$", text, re.S)
+    if not m:
+        raise ValueError(f"role {role} has no frontmatter")
+    fm_lines, body = m.group(1).split("\n"), m.group(2)
+    out: list[str] = ["---", "name: " + profile_name(role, adapter.id, project)]
+    for line in fm_lines:
+        out.append(line)
+        # Provider-specific fields are injected right after the CAO ``role:`` line.
+        if line.startswith("role:"):
+            out.append("provider: " + adapter.cao_provider)
+            if model:
+                out.append("model: " + json.dumps(model))  # quoted: IDs may contain dots/colons
+            for k, v in adapter.frontmatter.items():
+                out.append(f"{k}: {v}")
+    out.append("---")
+    result = "\n".join(out) + "\n" + body
+    if adapter.notes:
+        # Caveats (e.g. advisory-only limits) go at the end so the role body stays tool-agnostic.
+        result = result.rstrip("\n") + "\n\n## Tool notes\n\n" + adapter.notes + "\n"
+    return result

caokit/reset.py

@@ -0,0 +1,208 @@
+"""`caokit reset`: back up CAO's state, reinstall the pinned CAO, then reinstall profiles.
+
+Nothing is deleted. CAO's state folder is moved and the Antigravity MCP config is copied
+into a timestamped backup folder first. Without ``--yes`` the command only prints the plan.
+"""
+
+import json
+import os
+import re
+import shutil
+import subprocess
+import tempfile
+import time
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .adapters import ProcessResult, Runner, default_runner
+from .doctor import CAO_PKG
+
+
+class ResetError(Exception):
+    """Raised when a reset step fails; the backup folder holds everything moved so far."""
+
+
+@dataclass
+class ResetResult:
+    """What a reset did.
+
+    Attributes:
+        backup: Folder holding the moved CAO state and the copied MCP config.
+        steps: One line per completed step.
+    """
+
+    backup: Path
+    steps: list[str] = field(default_factory=list)
+
+
+def plan(version: str, cao_home: Path) -> list[str]:
+    """Return the steps a reset would perform, in order, for display."""
+    return [
+        "stop all CAO sessions, the cao-server process and cao-* tmux sessions",
+        f"move {cao_home} into the backup folder",
+        "remove CAO entries from the Antigravity MCP config (a copy is kept in the backup)",
+        f"uv tool uninstall {CAO_PKG}, then uv tool install {CAO_PKG}=={version}",
+        "cao init, then install the company profiles",
+    ]
+
+
+def _drop_cao_servers(config: Path) -> list[str]:
+    """Remove CAO MCP servers from an Antigravity config file; return the names removed."""
+    try:
+        data = json.loads(config.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return []
+    servers = data.get("mcpServers") if isinstance(data, dict) else None
+    if not isinstance(servers, dict):
+        return []
+    drop = [
+        k
+        for k, v in servers.items()
+        if k == "cao" or k.startswith("cao-") or "cao-mcp-server" in json.dumps(v)
+    ]
+    for k in drop:
+        servers.pop(k)
+    if drop:  # write beside the file, then swap, so a crash cannot leave half a config
+        fd, tmp = tempfile.mkstemp(dir=config.parent, prefix=config.name + ".")
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            f.write(json.dumps(data, indent=2))
+        os.replace(tmp, config)
+    return drop
+
+
+def _unsafe_home(cao_home: Path) -> str | None:
+    """Return why ``cao_home`` must not be moved wholesale, or None if it is fine."""
+    if cao_home.is_symlink():
+        return f"{cao_home} is a symlink; moving it would move the link, not the data"
+    real, home = cao_home.resolve(), Path.home().resolve()
+    if real == home or real in home.parents or real.parent == real:
+        return f"{cao_home} is your home folder or above it; refusing to move it"
+    return None
+
+
+def _new_backup(root: Path) -> Path:
+    """Create a fresh timestamped backup folder, never reusing one from the same second."""
+    stamp = "cao-reset-backup-" + time.strftime("%Y%m%d-%H%M%S")
+    for n in range(100):
+        path = root / (stamp if n == 0 else f"{stamp}-{n}")
+        try:
+            path.mkdir(parents=True)
+        except FileExistsError:
+            continue
+        return path
+    raise ResetError(f"could not create a backup folder under {root}")
+
+
+def run_reset(
+    version: str,
+    cao_home: Path,
+    agy_mcp: Path,
+    backup_root: Path,
+    runner: Runner = default_runner,
+    install_profiles: Callable[[], None] = lambda: None,
+    slow_runner: Runner | None = None,
+) -> ResetResult:
+    """Back up and reinstall CAO.
+
+    Args:
+        version: CAO version to pin.
+        cao_home: CAO's state folder (moved, not deleted).
+        agy_mcp: Antigravity MCP config path (copied, then edited in place).
+        backup_root: Folder in which the timestamped backup folder is created.
+        runner: Command runner (injectable for tests).
+        install_profiles: Called last to reinstall the company's profiles.
+        slow_runner: Runner for the ``uv`` install (a cold download can exceed the default
+            runner's timeout); defaults to ``runner``.
+
+    Returns:
+        The backup folder and the steps taken.
+
+    Raises:
+        ResetError: ``cao_home`` is unsafe to move, a command failed or could not run, or the
+            installed version is not ``version``. Nothing is moved before the checks pass.
+    """
+    why = _unsafe_home(cao_home)
+    if why:
+        raise ResetError(why)
+    backup = _new_backup(backup_root)
+    res = ResetResult(backup)
+    slow = slow_runner or runner
+    try:
+        _reset_steps(version, cao_home, agy_mcp, backup, res, runner, slow, install_profiles)
+    except (OSError, subprocess.TimeoutExpired) as e:
+        raise ResetError(f"{e} (backup: {backup})") from e
+    return res
+
+
+def _reset_steps(
+    version: str,
+    cao_home: Path,
+    agy_mcp: Path,
+    backup: Path,
+    res: ResetResult,
+    runner: Runner,
+    slow: Runner,
+    install_profiles: Callable[[], None],
+) -> None:
+    def must(run: Runner, argv: list[str], what: str) -> str:
+        r = run(argv)
+        if r.returncode != 0:
+            raise ResetError(f"{what} failed: {(r.stderr or r.stdout).strip()} (backup: {backup})")
+        return r.stdout or ""
+
+    def best_effort(argv: list[str]) -> ProcessResult | None:
+        try:
+            return runner(argv)
+        except (OSError, subprocess.TimeoutExpired):  # tool missing or hung: nothing to stop
+            return None
+
+    best_effort(["cao", "shutdown", "--all"])  # the server may already be down
+    for pid in _cao_server_pids(runner):
+        best_effort(["kill", pid])
+    listed = best_effort(["tmux", "list-sessions", "-F", "#{session_name}"])
+    for name in ((listed.stdout if listed else "") or "").split():
+        if name.startswith("cao-"):
+            best_effort(["tmux", "kill-session", "-t", name])
+    res.steps.append("stopped sessions and server")
+    if cao_home.is_dir():
+        shutil.move(str(cao_home), str(backup / "cli-agent-orchestrator"))
+        res.steps.append(f"moved {cao_home} to {backup}")
+    if agy_mcp.is_file():
+        shutil.copy2(agy_mcp, backup / "gemini-mcp_config.json")
+        removed = _drop_cao_servers(agy_mcp)
+        res.steps.append("removed from MCP config: " + (", ".join(removed) or "nothing"))
+    best_effort(["uv", "tool", "uninstall", CAO_PKG])  # fine if it was not installed
+    must(slow, ["uv", "tool", "install", f"{CAO_PKG}=={version}"], "install of CAO")
+    if version not in re.findall(
+        r"\d+(?:\.\d+)*", must(runner, ["cao", "--version"], "cao --version")
+    ):
+        raise ResetError(f"cao is not {version} after install (backup: {backup})")
+    must(runner, ["cao", "init"], "cao init")
+    res.steps.append(f"installed CAO {version}")
+    try:
+        install_profiles()
+    except ResetError as e:
+        raise ResetError(f"{e} (backup: {backup})") from e
+    res.steps.append("installed company profiles")
+
+
+def _cao_server_pids(runner: Runner) -> list[str]:
+    """Return PIDs of real ``cao-server`` processes (argv0, or argv1 after a python), not greps."""
+    try:
+        r = runner(["ps", "-axo", "pid=,command="])
+    except (OSError, subprocess.TimeoutExpired):
+        return []
+    pids: list[str] = []
+    for line in (r.stdout or "").splitlines():
+        parts = line.split()
+        if len(parts) < 2:
+            continue
+        a1 = parts[1]
+        a2 = parts[2] if len(parts) > 2 else ""
+        is_server = a1.endswith("cao-server") or (
+            "python" in a1.lower() and a2.endswith("cao-server")
+        )
+        if is_server:
+            pids.append(parts[0])
+    return pids