netizen-cli 0.10.0__py3-none-any.whl

netizen_cli/defaults/store.py

@@ -0,0 +1,260 @@
+"""Defaults metadata on the existing Channel database and transaction boundary."""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+import uuid
+from typing import TYPE_CHECKING, Any
+
+from ..session_settings import SessionSettings
+from .models import DefaultConfigurationError, DefaultRule
+
+if TYPE_CHECKING:
+    from ..bindings import BindingStore
+
+
+MAX_GROUP_RULES = 200
+SCHEMA = (
+    """CREATE TABLE session_defaults (
+        id TEXT PRIMARY KEY,
+        app_id TEXT NOT NULL CHECK(length(app_id) > 0),
+        kind TEXT NOT NULL CHECK(kind IN ('chat', 'group_name')),
+        chat_id TEXT, keyword TEXT,
+        project TEXT NOT NULL CHECK(length(project) > 0),
+        session_settings_json TEXT NOT NULL,
+        revision INTEGER NOT NULL CHECK(typeof(revision) = 'integer' AND revision >= 1),
+        position INTEGER,
+        CHECK((kind = 'chat' AND chat_id IS NOT NULL AND length(chat_id) > 0
+            AND keyword IS NULL AND position IS NULL) OR
+            (kind = 'group_name' AND chat_id IS NULL AND keyword IS NOT NULL
+            AND length(trim(keyword)) > 0 AND typeof(position) = 'integer' AND position >= 0))
+    )""",
+    "CREATE UNIQUE INDEX session_defaults_chat ON session_defaults(app_id, chat_id) WHERE kind = 'chat'",
+    "CREATE UNIQUE INDEX session_defaults_position ON session_defaults(app_id, position) WHERE kind = 'group_name'",
+    """CREATE TABLE session_defaults_order (
+        app_id TEXT PRIMARY KEY CHECK(length(app_id) > 0),
+        revision INTEGER NOT NULL CHECK(typeof(revision) = 'integer' AND revision >= 1)
+    )""",
+)
+
+
+def create_schema(connection: sqlite3.Connection) -> None:
+    for statement in SCHEMA:
+        connection.execute(statement)
+
+
+def require_schema(connection: sqlite3.Connection) -> None:
+    expected = {
+        "session_defaults": {
+            "id": ("TEXT", 0, 1), "app_id": ("TEXT", 1, 0),
+            "kind": ("TEXT", 1, 0), "chat_id": ("TEXT", 0, 0),
+            "keyword": ("TEXT", 0, 0), "project": ("TEXT", 1, 0),
+            "session_settings_json": ("TEXT", 1, 0),
+            "revision": ("INTEGER", 1, 0), "position": ("INTEGER", 0, 0),
+        },
+        "session_defaults_order": {"app_id": ("TEXT", 0, 1), "revision": ("INTEGER", 1, 0)},
+    }
+    for table, columns in expected.items():
+        actual = {row["name"]: (row["type"].upper(), row["notnull"], row["pk"])
+                  for row in connection.execute(f"PRAGMA table_info({table})")}
+        if any(actual.get(name) != shape for name, shape in columns.items()):
+            raise RuntimeError(f"current Channel database has invalid {table} columns")
+    indexes = {row["name"]: row for row in connection.execute("PRAGMA index_list(session_defaults)")}
+    for name, columns, predicate in (
+        ("session_defaults_chat", ("app_id", "chat_id"), "kind = 'chat'"),
+        ("session_defaults_position", ("app_id", "position"), "kind = 'group_name'"),
+    ):
+        index = indexes.get(name)
+        if index is None or not index["unique"] or not index["partial"]:
+            raise RuntimeError(f"current defaults identity index is missing or invalid: {name}")
+        actual_columns = tuple(row["name"] for row in connection.execute(f"PRAGMA index_info({name})"))
+        sql = connection.execute("SELECT sql FROM sqlite_master WHERE name = ?", (name,)).fetchone()[0]
+        if actual_columns != columns or " ".join(sql.lower().split()).partition(" where ")[2] != predicate:
+            raise RuntimeError(f"current defaults identity index has invalid shape: {name}")
+    for table in expected:
+        if connection.execute(f"PRAGMA foreign_key_list({table})").fetchone():
+            raise RuntimeError("default configuration must not link Project lifecycle")
+    if connection.execute(
+        "SELECT 1 FROM session_defaults_order WHERE app_id IS NULL OR app_id = '' "
+        "OR typeof(revision) != 'integer' OR revision < 1 LIMIT 1"
+    ).fetchone():
+        raise RuntimeError("current defaults order revision is invalid")
+    positions: dict[str, list[int]] = {}
+    for row in connection.execute("SELECT * FROM session_defaults ORDER BY app_id, position"):
+        try:
+            rule = _rule(row)
+            if not all(isinstance(value, str) and value for value in (rule.id, rule.app_id, rule.project)):
+                raise ValueError("missing identity")
+            if type(rule.revision) is not int or rule.revision < 1:
+                raise ValueError("invalid revision")
+            if rule.kind == "chat":
+                if not rule.chat_id or rule.keyword is not None or rule.position is not None:
+                    raise ValueError("invalid chat rule")
+            elif rule.kind == "group_name":
+                if (rule.chat_id is not None or not isinstance(rule.keyword, str)
+                        or not rule.keyword.strip() or rule.keyword != rule.keyword.strip()
+                        or type(rule.position) is not int or rule.position < 0):
+                    raise ValueError("invalid group rule")
+                positions.setdefault(rule.app_id, []).append(rule.position)
+            else:
+                raise ValueError("invalid rule kind")
+        except (TypeError, ValueError) as error:
+            raise RuntimeError("current default configuration is invalid") from error
+    for app_id, values in positions.items():
+        if len(values) > MAX_GROUP_RULES or values != list(range(len(values))):
+            raise RuntimeError("current defaults group order is invalid")
+        if connection.execute("SELECT 1 FROM session_defaults_order WHERE app_id = ?", (app_id,)).fetchone() is None:
+            raise RuntimeError("current defaults group order revision is missing")
+
+
+def _rule(row: sqlite3.Row) -> DefaultRule:
+    return DefaultRule(
+        id=row["id"], app_id=row["app_id"], kind=row["kind"],
+        chat_id=row["chat_id"], keyword=row["keyword"], project=row["project"],
+        session_settings=SessionSettings.from_dict(json.loads(row["session_settings_json"])),
+        revision=row["revision"], position=row["position"],
+    )
+
+
+class DefaultsStore:
+    def __init__(self, owner: BindingStore) -> None:
+        self.owner = owner
+
+    @property
+    def _db(self) -> sqlite3.Connection:
+        return self.owner._connection
+
+    def get(self, app_id: str, rule_id: str) -> DefaultRule:
+        with self.owner._lock:
+            row = self._db.execute("SELECT * FROM session_defaults WHERE app_id = ? AND id = ?", (app_id, rule_id)).fetchone()
+            if row is None:
+                raise DefaultConfigurationError("默认会话配置不存在，请刷新后重试。", code="not_found")
+            return _rule(row)
+
+    def exact(self, app_id: str, chat_id: str) -> DefaultRule | None:
+        with self.owner._lock:
+            row = self._db.execute(
+                "SELECT * FROM session_defaults WHERE app_id = ? AND kind = 'chat' AND chat_id = ?", (app_id, chat_id),
+            ).fetchone()
+            return _rule(row) if row else None
+
+    def group_rules(self, app_id: str) -> tuple[DefaultRule, ...]:
+        with self.owner._lock:
+            return tuple(_rule(row) for row in self._db.execute(
+                "SELECT * FROM session_defaults WHERE app_id = ? AND kind = 'group_name' ORDER BY position LIMIT ?",
+                (app_id, MAX_GROUP_RULES),
+            ))
+
+    async def list(self, app_id: str, kind: str, *, offset: int, limit: int) -> dict[str, Any]:
+        def query(connection: sqlite3.Connection) -> dict[str, Any]:
+            connection.execute("BEGIN")
+            try:
+                rows = connection.execute(
+                    "SELECT * FROM session_defaults WHERE app_id = ? AND kind = ? "
+                    "ORDER BY position, id LIMIT ? OFFSET ?", (app_id, kind, limit + 1, offset),
+                ).fetchall()
+                return {"items": [_rule(row).to_dict() for row in rows[:limit]],
+                        "has_more": len(rows) > limit, "offset": offset,
+                        "order_revision": self._order_revision(connection, app_id)}
+            finally:
+                connection.rollback()
+        return await self.owner._submit_query(query, deadline_seconds=2)
+
+    @staticmethod
+    def _order_revision(connection: sqlite3.Connection, app_id: str) -> int:
+        row = connection.execute("SELECT revision FROM session_defaults_order WHERE app_id = ?", (app_id,)).fetchone()
+        return row[0] if row else 1
+
+    def _bump_order(self, app_id: str) -> int:
+        self._db.execute(
+            "INSERT INTO session_defaults_order(app_id, revision) VALUES (?, 2) "
+            "ON CONFLICT(app_id) DO UPDATE SET revision = revision + 1", (app_id,),
+        )
+        return self._order_revision(self._db, app_id)
+
+    def save(
+        self, *, app_id: str, kind: str, chat_id: str | None, keyword: str | None,
+        project: str, session_settings: SessionSettings, rule_id: str | None,
+        expected_revision: int | None, checked_project_revision: int | None = None,
+    ) -> DefaultRule:
+        with self.owner._transaction():
+            if checked_project_revision is not None:
+                self._require_checked_project(project, checked_project_revision)
+            if expected_revision is None:
+                if rule_id is not None:
+                    raise DefaultConfigurationError("新增默认配置不能指定已有 ID。")
+                if kind == "chat" and self.exact(app_id, chat_id or "") is not None:
+                    raise DefaultConfigurationError("该聊天已有默认配置，请刷新后修改。", code="revision_conflict")
+                position = None
+                if kind == "group_name":
+                    position = self._db.execute(
+                        "SELECT count(*) FROM session_defaults WHERE app_id = ? AND kind = 'group_name'", (app_id,),
+                    ).fetchone()[0]
+                    if position >= MAX_GROUP_RULES:
+                        raise DefaultConfigurationError(f"群名规则最多支持 {MAX_GROUP_RULES} 条。", code="capacity")
+                    self._bump_order(app_id)
+                rule_id = str(uuid.uuid4())
+                self._db.execute(
+                    "INSERT INTO session_defaults VALUES (?, ?, ?, ?, ?, ?, ?, 1, ?)",
+                    (rule_id, app_id, kind, chat_id, keyword, project,
+                     json.dumps(session_settings.to_dict(), ensure_ascii=False), position),
+                )
+            else:
+                if rule_id is None:
+                    raise DefaultConfigurationError("修改默认配置需要 ID。")
+                previous = self.get(app_id, rule_id)
+                self._check_revision(previous, expected_revision)
+                if kind != previous.kind or chat_id != previous.chat_id:
+                    raise DefaultConfigurationError("默认配置的类型和聊天不可修改；请新建配置。")
+                self._db.execute(
+                    "UPDATE session_defaults SET keyword = ?, project = ?, session_settings_json = ?, "
+                    "revision = revision + 1 WHERE id = ? AND app_id = ?",
+                    (keyword, project, json.dumps(session_settings.to_dict(), ensure_ascii=False), rule_id, app_id),
+                )
+            return self.get(app_id, rule_id)
+
+    def _require_checked_project(self, alias: str, checked_revision: int) -> None:
+        from ..bindings import ProjectConflict, ProjectNotFound
+
+        try:
+            self.owner.require_project_not_deleting(alias)
+            project = self.owner.get_project(alias)
+        except (ProjectConflict, ProjectNotFound) as error:
+            raise DefaultConfigurationError("Project 已不可用于新建会话，请刷新后重试。", code="project_unavailable") from error
+        if project.revision != checked_revision or not project.enabled:
+            raise DefaultConfigurationError("Project 已被其他操作修改，请刷新后重试。", code="project_unavailable")
+
+    @staticmethod
+    def _check_revision(rule: DefaultRule, revision: int) -> None:
+        if rule.revision != revision:
+            raise DefaultConfigurationError("默认配置已被其他操作修改，请刷新后重试。", code="revision_conflict")
+
+    def delete(self, app_id: str, rule_id: str, expected_revision: int) -> None:
+        with self.owner._transaction():
+            rule = self.get(app_id, rule_id)
+            self._check_revision(rule, expected_revision)
+            self._db.execute("DELETE FROM session_defaults WHERE app_id = ? AND id = ?", (app_id, rule_id))
+            if rule.kind == "group_name":
+                self._write_order(app_id, [item.id for item in self.group_rules(app_id)])
+                self._bump_order(app_id)
+
+    def reorder(self, app_id: str, rule_ids: list[str], order_revision: int) -> int:
+        with self.owner._transaction():
+            if self._order_revision(self._db, app_id) != order_revision:
+                raise DefaultConfigurationError("群名规则顺序已变化，请刷新后重试。", code="revision_conflict")
+            current = [rule.id for rule in self.group_rules(app_id)]
+            if len(rule_ids) != len(set(rule_ids)) or set(rule_ids) != set(current):
+                raise DefaultConfigurationError("排序必须包含当前应用下全部群名规则，且不能重复。")
+            self._write_order(app_id, rule_ids)
+            return self._bump_order(app_id)
+
+    def _write_order(self, app_id: str, rule_ids: list[str]) -> None:
+        # Move out of the dense final range before assigning the new positions;
+        # the unique index remains valid throughout the transaction.
+        self._db.execute(
+            "UPDATE session_defaults SET position = position + ? WHERE app_id = ? AND kind = 'group_name'",
+            (MAX_GROUP_RULES + 1, app_id),
+        )
+        for position, rule_id in enumerate(rule_ids):
+            self._db.execute("UPDATE session_defaults SET position = ? WHERE app_id = ? AND id = ?", (position, app_id, rule_id))

netizen_cli/deployment/__init__.py

@@ -0,0 +1 @@
+"""Shared deployment support; safe to import before candidate setup."""

netizen_cli/deployment/restart_worker.py

@@ -0,0 +1,134 @@
+"""One-shot, instance-only restart dispatched by the service manager."""
+
+from __future__ import annotations
+
+import argparse
+import os
+from pathlib import Path
+import time
+from typing import Any
+
+from .update_protocol import (
+    UpdateProtocolError, acquire_install_lock, advance_operation, read_operation,
+    terminal_phase, validate_inherited_lock,
+)
+
+START_HANDOFF_SECONDS = 60
+
+
+def assert_no_pending_restart(root: Path, *, lock_descriptor: int,
+                              now: float | None = None) -> dict[str, Any] | None:
+    """Fence delayed Admin work before a CLI mutation, under the exact lock.
+
+    A fresh accepted dispatch keeps its bounded handoff window. Acquiring this
+    lock proves no worker is currently in its stop/start critical section. A
+    stale record is therefore fenced before returning, and a delayed worker
+    will reject it without recreating a service or maintenance record.
+    """
+    validate_inherited_lock(root, lock_descriptor)
+    operation = read_operation(root)
+    if operation is None or terminal_phase(operation["phase"]):
+        return operation
+    if operation.get("schema") != 3:
+        raise UpdateProtocolError(
+            "Legacy maintenance is unresolved; inspect the old installation before manual conversion"
+        )
+    if operation["phase"] == "accepted":
+        observed_at = time.time() if now is None else now
+        if observed_at - operation["createdAt"] < START_HANDOFF_SECONDS:
+            raise UpdateProtocolError(
+                f"Admin restart {operation['operationId']} is pending dispatch; "
+                "wait for maintenance to finish, then retry this command"
+            )
+        # The worker writes restarting before stop, while retaining this lock.
+        # Accepted + lock ownership proves that this request never began stop.
+        return advance_operation(root, operation["operationId"], "failed", "dispatch_failed")
+    # The only other nonterminal schema-3 phase is restarting. Retain unknown
+    # side effects; a succeeding explicit CLI operation may prove recovery.
+    return advance_operation(root, operation["operationId"], "recovery_required", "worker_lost")
+
+
+def finish_manual_restart(root: Path, *, lock_descriptor: int, status: Any,
+                          executor: Any = None) -> dict[str, Any] | None:
+    """Reconcile a failed Admin restart after an explicit CLI ready result.
+
+    The caller still owns the root's maintenance lock and just obtained the
+    exact service manager's private ready proof. This records recovery only;
+    it never rewrites the original request as success or changes its target.
+    """
+    from .update_executor import UpdateExecutor, UpdateExecutorError
+    import pwd
+
+    validate_inherited_lock(root, lock_descriptor)
+    if (status is None or not status.running or not status.ready
+            or status.binding.root != root):
+        raise UpdateProtocolError("manual recovery requires the exact ready instance")
+    operation = read_operation(root)
+    if (operation is None or operation.get("schema") != 3
+            or operation["phase"] != "recovery_required"):
+        return operation
+    manager = executor or UpdateExecutor(Path(pwd.getpwuid(os.geteuid()).pw_dir), root=root)
+    try:
+        # launchd retains exited jobs as loaded. Cleanup under the held lock
+        # can unload that once-only job; querying presence first would block
+        # macOS recovery forever. Linux collect needs no explicit cleanup.
+        manager.cleanup(operation["operationId"])
+        if manager.is_active(operation["operationId"]):
+            return operation
+    except UpdateExecutorError:
+        return operation
+    return advance_operation(root, operation["operationId"], "recovered", "manual_recovery")
+
+
+def run(root: Path, operation_id: str, *, manager: Any = None) -> int:
+    from ..cli_services import ServiceError, ServiceManager
+    from ..management.updates import installed_package
+
+    descriptor = acquire_install_lock(root, blocking=True)
+    try:
+        operation = read_operation(root)
+        if (operation is None or operation.get("schema") != 3
+                or operation["operationId"] != operation_id
+                or operation["phase"] != "accepted"):
+            return 1  # Never claim a superseded or already executed request.
+        if time.time() - operation["createdAt"] >= START_HANDOFF_SECONDS:
+            advance_operation(root, operation_id, "failed", "dispatch_failed")
+            return 1
+        current = installed_package()
+        manager = manager or ServiceManager()
+        status = manager.inspect(root)
+        if (operation["target"]["installationId"] != current.identity
+                or status is None or status.binding.python != current.python
+                or status.binding.prefix != current.prefix):
+            advance_operation(root, operation_id, "failed", "previous_release_changed")
+            return 1
+        advance_operation(root, operation_id, "restarting")
+        try:
+            manager.stop(root)
+            # start preserves the exact existing service binding and only
+            # returns after a held lifetime lock + the private ready proof.
+            manager.start(root)
+        except (ServiceError, OSError, RuntimeError):
+            advance_operation(root, operation_id, "recovery_required", "restart_failed")
+            return 1
+        advance_operation(root, operation_id, "succeeded")
+        return 0
+    finally:
+        os.close(descriptor)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--root", type=Path, required=True)
+    parser.add_argument("--operation-id", required=True)
+    options = parser.parse_args()
+    try:
+        return run(options.root, options.operation_id)
+    except (UpdateProtocolError, OSError, RuntimeError):
+        # Leave the durable operation for bounded Admin reconciliation. Never
+        # print manager output, credentials, or guessed success.
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

netizen_cli/deployment/update_executor.py

@@ -0,0 +1,258 @@
+"""Dispatch an instance restart outside the Netizen service's lifetime."""
+
+from __future__ import annotations
+
+import os
+import plistlib
+import re
+import stat
+import subprocess
+import sys
+from pathlib import Path
+
+from ..instance import instance_digest, resolve_instance_root
+
+
+COMMAND_TIMEOUT_SECONDS = 10.0
+_OPERATION_ID = re.compile(r"[0-9a-f]{32}\Z")
+_BOOTSTRAP_PATH = "/usr/local/bin:/usr/bin:/bin"
+_CLEARED_ENVIRONMENT = (
+    "NETIZEN_ROOT",
+    "FEISHU_APP_SECRET",
+    "NETIZEN_ADMIN_SECRET",
+    "FEISHU_APP_SECRET_FILE",
+    "NETIZEN_LARK_APP_CONFIG",
+    "NETIZEN_ADMIN_SECRET_FILE",
+    "NETIZEN_CONFIG_PATH",
+    "NETIZEN_LIFETIME_LOCK_FD",
+    "NETIZEN_LIFETIME_LOCK_FILE",
+    "NETIZEN_READY_FILE",
+    "NETIZEN_LOG_FILE",
+    "NETIZEN_MANAGED_LAUNCH_AGENT",
+    "NETIZEN_CLI_SERVICE",
+    "NETIZEN_CLI_PREFIX",
+    "NETIZEN_CLI_PYTHON",
+    "NETIZEN_UPDATE_OPERATION_ID",
+    "NETIZEN_UPDATE_LOCK_FD",
+    "NETIZEN_UPDATE_VERSION",
+    "NETIZEN_UPDATE_ARCHIVE_SHA256",
+    "PYTHONHOME",
+    "PYTHONPATH",
+    "VIRTUAL_ENV",
+    "__PYVENV_LAUNCHER__",
+)
+
+
+class UpdateExecutorError(RuntimeError):
+    """A platform operation could not be completed or safely observed."""
+
+
+class UpdateDispatchUnknown(UpdateExecutorError):
+    """The manager may have accepted this operation; do not dispatch it again."""
+
+
+class UpdateExecutor:
+    def __init__(self, home: Path, platform_name: str | None = None,
+                 *, root: Path | None = None) -> None:
+        if not home.is_absolute() or home == Path(home.anchor):
+            raise UpdateExecutorError("update home must be an absolute non-root path")
+        self.home = home.resolve()
+        try:
+            self.product_root = resolve_instance_root(root, account_home=self.home)
+        except (OSError, ValueError, RuntimeError) as error:
+            raise UpdateExecutorError("invalid update instance root") from error
+        self.platform_name = sys.platform if platform_name is None else platform_name
+        if self.platform_name not in {"linux", "darwin"}:
+            raise UpdateExecutorError("updates require Linux or macOS")
+        self._uid = os.geteuid()
+
+    @staticmethod
+    def _validate_operation_id(operation_id: str) -> None:
+        if not isinstance(operation_id, str) or _OPERATION_ID.fullmatch(operation_id) is None:
+            raise UpdateExecutorError("invalid update operation ID")
+
+    def _label(self, operation_id: str) -> str:
+        self._validate_operation_id(operation_id)
+        return f"netizen-update-{instance_digest(self.product_root)}-{operation_id}"
+
+    def _plist_path(self, operation_id: str) -> Path:
+        return self.product_root / "state" / f"{self._label(operation_id)}.plist"
+
+    def _worker_arguments(self, operation_id: str, python: Path) -> list[str]:
+        self._validate_operation_id(operation_id)
+        if (not python.is_absolute() or not python.is_file()
+                or not os.access(python, os.X_OK)
+                or any(character in str(python) for character in "\r\n\0")):
+            raise UpdateExecutorError("the bound Python executable is unavailable")
+        return [str(python), "-E", "-P", "-B", "-u", "-m", "netizen_cli.deployment.restart_worker",
+                "--root", str(self.product_root), "--operation-id", operation_id]
+
+    def _command(
+        self, arguments: list[str], *, dispatch: bool = False, capture: bool = False
+    ) -> subprocess.CompletedProcess[str]:
+        environment = dict(os.environ)
+        for key in tuple(environment):
+            if key.startswith("NETIZEN_") or key in _CLEARED_ENVIRONMENT:
+                environment.pop(key, None)
+        environment["HOME"] = str(self.home)
+        if self.platform_name == "linux":
+            environment.setdefault("XDG_RUNTIME_DIR", f"/run/user/{self._uid}")
+            environment.setdefault("DBUS_SESSION_BUS_ADDRESS", f"unix:path=/run/user/{self._uid}/bus")
+        try:
+            return subprocess.run(
+                arguments,
+                stdin=subprocess.DEVNULL,
+                stdout=subprocess.PIPE if capture else subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+                text=True,
+                check=False,
+                close_fds=True,
+                cwd=self.home,
+                env=environment,
+                timeout=COMMAND_TIMEOUT_SECONDS,
+            )
+        except subprocess.TimeoutExpired as error:
+            exception = UpdateDispatchUnknown if dispatch else UpdateExecutorError
+            raise exception("update service manager command timed out") from error
+        except (FileNotFoundError, PermissionError) as error:
+            # Popen did not start the manager command. Its output and inherited
+            # environment are deliberately never included in user-visible errors.
+            raise UpdateExecutorError("could not execute the update service manager") from error
+        except OSError as error:
+            exception = UpdateDispatchUnknown if dispatch else UpdateExecutorError
+            raise exception("could not complete the update service manager command") from error
+
+    def launch(self, operation_id: str, python: Path) -> None:
+        """Submit once, without waiting for the instance lock or its result.
+
+        A dispatch error after submission is ambiguous even when the manager
+        command returns nonzero. The caller must inspect the operation result
+        and execution lock; it must never retry this operation automatically.
+        """
+
+        label = self._label(operation_id)
+        arguments = self._worker_arguments(operation_id, python)
+        if self.platform_name == "linux":
+            # systemd-run expands $ in argv, including argv[0]. A fixed env
+            # executable lets every environment path be escaped as an argument,
+            # then execs the real Python in place. Doubling argv[0] itself would
+            # make systemd-run look for a nonexistent executable. Unlike unit
+            # file syntax, transient D-Bus properties preserve literal %.
+            worker_arguments = [value.replace("$", "$$") for value in arguments]
+            result = self._command(
+                [
+                    "systemd-run", "--user", "--no-ask-password", f"--unit={label}.service", "--collect",
+                    "--service-type=exec", "--property=Restart=no",
+                    "--property=KillMode=control-group", "--property=UMask=0077",
+                    "--property=StandardInput=null", "--property=StandardOutput=null",
+                    "--property=StandardError=null", f"--working-directory={self.home}",
+                    f"--setenv=HOME={self.home}", f"--setenv=PATH={_BOOTSTRAP_PATH}",
+                    "--property=UnsetEnvironment=" + " ".join(_CLEARED_ENVIRONMENT),
+                    "--", "/usr/bin/env", "--", *worker_arguments,
+                ],
+                dispatch=True,
+            )
+        else:
+            domain = f"gui/{self._uid}"
+            if self._command(["launchctl", "print", domain]).returncode != 0:
+                raise UpdateExecutorError("the current macOS GUI launchd domain is unavailable")
+            path = self._plist_path(operation_id)
+            self._write_plist(path, label, arguments)
+            result = self._command(["launchctl", "bootstrap", domain, str(path)], dispatch=True)
+        if result.returncode != 0:
+            raise UpdateDispatchUnknown("the update service manager did not confirm dispatch")
+
+    def _write_plist(self, path: Path, label: str, arguments: list[str]) -> None:
+        # A state-directory plist is submitted explicitly. It is not installed
+        # in Library/LaunchAgents and cannot replay an update at the next login.
+        try:
+            metadata = path.parent.lstat()
+            if (
+                not stat.S_ISDIR(metadata.st_mode)
+                or metadata.st_uid != self._uid
+                or stat.S_IMODE(metadata.st_mode) & 0o022
+            ):
+                raise UpdateExecutorError("the update state directory is not private to this user")
+            payload = plistlib.dumps(
+                {
+                    "Label": label,
+                    "ProgramArguments": arguments,
+                    "WorkingDirectory": str(self.home),
+                    "RunAtLoad": True,
+                    "KeepAlive": False,
+                    "Umask": 0o077,
+                    "EnvironmentVariables": {"HOME": str(self.home), "PATH": _BOOTSTRAP_PATH},
+                    "StandardOutPath": "/dev/null",
+                    "StandardErrorPath": "/dev/null",
+                },
+                sort_keys=True,
+            )
+            descriptor = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+            with os.fdopen(descriptor, "wb") as stream:
+                stream.write(payload)
+                stream.flush()
+                os.fsync(stream.fileno())
+        except FileExistsError as error:
+            raise UpdateDispatchUnknown("this update already has a manager submission file") from error
+        except OSError as error:
+            raise UpdateExecutorError("could not prepare the update LaunchAgent") from error
+
+    def is_active(self, operation_id: str) -> bool:
+        """Return conservative manager presence, never infer absence on timeout.
+
+        launchd's print exit status proves only that a job is loaded. The caller
+        also uses the updater's execution lock to identify an exited worker.
+        No launchctl print text or process identity is parsed here.
+        """
+
+        label = self._label(operation_id)
+        if self.platform_name == "darwin":
+            domain = f"gui/{self._uid}"
+            if self._command(["launchctl", "print", domain]).returncode != 0:
+                raise UpdateExecutorError("the current macOS GUI launchd domain is unavailable")
+            result = self._command(["launchctl", "print", f"{domain}/{label}"])
+            if result.returncode not in {0, 113}:
+                raise UpdateExecutorError("could not determine the update LaunchAgent state")
+            return result.returncode == 0
+        result = self._command(
+            [
+                "systemctl", "--user", "show", "--property=LoadState",
+                "--property=ActiveState", "--", f"{label}.service",
+            ],
+            capture=True,
+        )
+        if result.returncode != 0:
+            raise UpdateExecutorError("could not determine the update service state")
+        fields = dict(line.split("=", 1) for line in result.stdout.splitlines() if "=" in line)
+        if fields.get("LoadState") == "not-found" and fields.get("ActiveState") == "inactive":
+            return False
+        if fields.get("LoadState") != "loaded":
+            raise UpdateExecutorError("the update service state is unrecognized")
+        state = fields.get("ActiveState")
+        if state in {"active", "activating", "reloading", "deactivating", "refreshing"}:
+            return True
+        if state in {"inactive", "failed"}:
+            return False
+        raise UpdateExecutorError("the update service state is unrecognized")
+
+    def cleanup(self, operation_id: str) -> None:
+        """Remove a completed job from the service manager.
+
+        The Admin process or explicit CLI must own the instance lock and have
+        read a durable terminal result; acquiring that lock proves the worker
+        has released execution. The updater must not bootout itself: launchd
+        could kill it before it finishes writing its result.
+        Linux's --collect performs automatic transient-unit removal.
+        """
+
+        label = self._label(operation_id)
+        if self.platform_name == "linux":
+            return
+        if self.is_active(operation_id):
+            result = self._command(["launchctl", "bootout", f"gui/{self._uid}/{label}"])
+            if result.returncode != 0 and self.is_active(operation_id):
+                raise UpdateExecutorError("could not remove the completed update LaunchAgent")
+        try:
+            self._plist_path(operation_id).unlink(missing_ok=True)
+        except OSError as error:
+            raise UpdateExecutorError("could not remove the completed update submission file") from error