netizen-cli 0.10.0__py3-none-any.whl

netizen_cli/cli_setup.py

@@ -0,0 +1,242 @@
+"""Explicit, per-instance setup; package installation has no setup side effects."""
+from __future__ import annotations
+
+import getpass
+import contextlib
+import json
+import os
+import pwd
+import secrets
+import stat
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+from typing import Callable, IO
+
+from .lark_app import encode_lark_app, load_lark_app
+
+
+class SetupError(RuntimeError):
+    pass
+
+
+def _write_atomic(path: Path, content: bytes, *, mode: int) -> None:
+    """Save private setup files without importing the retired installer."""
+    parent = path.parent
+    if parent.is_symlink():
+        raise SetupError(f"configuration parent must not be a symlink: {parent}")
+    parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+    descriptor, temporary_name = tempfile.mkstemp(prefix=f".{path.name}.", dir=parent)
+    temporary = Path(temporary_name)
+    try:
+        os.fchmod(descriptor, mode)
+        with os.fdopen(descriptor, "wb") as output:
+            output.write(content)
+            output.flush()
+            os.fsync(output.fileno())
+        os.replace(temporary, path)
+        directory = os.open(parent, os.O_RDONLY | getattr(os, "O_DIRECTORY", 0))
+        try:
+            os.fsync(directory)
+        finally:
+            os.close(directory)
+    except BaseException:
+        with contextlib.suppress(OSError):
+            os.close(descriptor)
+        with contextlib.suppress(OSError):
+            temporary.unlink()
+        raise
+
+
+def _private_file(path: Path) -> None:
+    metadata = path.lstat()
+    if (not stat.S_ISREG(metadata.st_mode) or metadata.st_uid != os.geteuid()
+            or stat.S_IMODE(metadata.st_mode) & 0o077):
+        raise SetupError(f"expected a private current-user regular file: {path}")
+
+
+def _helper(module: str, arguments: list[str], *, timeout: float,
+            runner: Callable = subprocess.run, progress: bool = False) -> dict:
+    """Capture credentials privately; never include stdout in an exception."""
+    try:
+        result = runner(
+            [os.path.abspath(sys.executable), "-E", "-P", "-B", "-u", "-m", module, *arguments],
+            stdin=subprocess.DEVNULL, stdout=subprocess.PIPE,
+            stderr=None if progress else subprocess.PIPE,
+            text=True, check=False, timeout=timeout,
+        )
+    except (OSError, subprocess.SubprocessError):
+        raise SetupError("setup helper failed or timed out; rerun netizen setup") from None
+    if result.returncode == 130:
+        raise KeyboardInterrupt
+    if result.returncode != 0:
+        raise SetupError("setup helper did not complete; rerun netizen setup")
+    try:
+        value = json.loads(result.stdout)
+    except (TypeError, ValueError):
+        raise SetupError("setup helper returned an invalid result") from None
+    if not isinstance(value, dict) or value.get("version") != 1:
+        raise SetupError("setup helper returned an invalid result")
+    return value
+
+
+def require_codex_login(*, runner: Callable = subprocess.run) -> None:
+    """Check the selected account context without executing shell startup code.
+
+    Login profiles run only inside the managed service boundary. An explicitly
+    selected CODEX_HOME is the same lexical absolute path used by registration.
+    """
+    account = pwd.getpwuid(os.geteuid())
+    environment = dict(os.environ)
+    selected_codex_home = environment.get("CODEX_HOME")
+    codex_home = (Path(selected_codex_home).expanduser().absolute()
+                  if selected_codex_home else Path(account.pw_dir) / ".codex")
+    environment.update(HOME=account.pw_dir, USER=account.pw_name, LOGNAME=account.pw_name,
+                       SHELL=account.pw_shell, CODEX_HOME=str(codex_home))
+    for name in ("PYTHONHOME", "PYTHONPATH", "VIRTUAL_ENV", "__PYVENV_LAUNCHER__"):
+        environment.pop(name, None)
+    try:
+        result = runner(
+            [os.path.abspath(sys.executable), "-E", "-P", "-c",
+             "import os; from codex_cli_bin import bundled_codex_path; "
+             "p = os.fspath(bundled_codex_path()); os.execv(p, [p, 'login', 'status'])"],
+            stdin=subprocess.DEVNULL, capture_output=True, text=True, check=False,
+            timeout=30, env=environment, cwd=account.pw_dir,
+        )
+    except (OSError, subprocess.SubprocessError):
+        raise SetupError("could not check the bundled Codex login") from None
+    if result.returncode != 0:
+        raise SetupError("sign in to Codex for this account, then rerun netizen setup")
+
+
+def _register(root: Path, app_id: str | None, *, runner: Callable) -> None:
+    arguments = ["--app-id", app_id] if app_id else []
+    value = _helper("netizen_cli.feishu_app_onboarding", arguments,
+                    timeout=660, runner=runner, progress=True)
+    if (set(value) != {"version", "appId", "appSecret"}
+            or not isinstance(value["appId"], str)
+            or not isinstance(value["appSecret"], str)
+            or not value["appId"] or not value["appSecret"]
+            or (app_id is not None and value["appId"] != app_id)):
+        raise SetupError("browser setup returned invalid or mismatched app credentials")
+    encoded = encode_lark_app(value["appId"], value["appSecret"])
+    _write_atomic(root / "lark-app/config.json", encoded, mode=0o600)
+
+
+def _manual_credentials(root: Path, app_id: str | None, *, source: IO[str],
+                        secret_prompt: Callable[[str], str]) -> None:
+    if not app_id:
+        print("Feishu App ID: ", end="", file=sys.stderr, flush=True)
+        app_id = source.readline().strip()
+    secret = secret_prompt("Feishu App Secret (not echoed): ").strip()
+    if not app_id or not secret:
+        raise SetupError("App ID and App Secret must not be empty")
+    _write_atomic(root / "lark-app/config.json", encode_lark_app(app_id, secret), mode=0o600)
+
+
+def _browser_or_manual(root: Path, app_id: str | None, *, runner: Callable,
+                       source: IO[str], secret_prompt: Callable[[str], str]) -> None:
+    try:
+        _register(root, app_id, runner=runner)
+    except SetupError:
+        if not source.isatty():
+            raise
+        # Only one browser attempt. Never echo helper output or retry in a loop.
+        print("Browser setup did not complete. Enter credentials manually, or press Ctrl-C to cancel.",
+              file=sys.stderr)
+        _manual_credentials(root, app_id, source=source, secret_prompt=secret_prompt)
+
+
+def _missing_permissions(root: Path, *, runner: Callable) -> list[str]:
+    from .feishu_app_onboarding import REQUIRED_TENANT_SCOPES
+
+    try:
+        value = _helper("netizen_cli.feishu_app_permissions",
+                        ["--lark-app-config", str(root / "lark-app/config.json")],
+                        timeout=90, runner=runner)
+    except SetupError:
+        raise SetupError(
+            "could not verify saved app credentials/permissions; check network and app status. "
+            "If the App Secret is invalid, clear only appSecret in this instance's "
+            "lark-app/config.json (keep appId), then rerun netizen setup for exact-App repair"
+        ) from None
+    missing = value.get("missingScopes")
+    if (set(value) != {"version", "missingScopes"} or not isinstance(missing, list)
+            or any(not isinstance(scope, str) for scope in missing)
+            or missing != [scope for scope in REQUIRED_TENANT_SCOPES if scope in missing]):
+        raise SetupError("permission helper returned an invalid result")
+    return missing
+
+
+def prepare_configuration(root: Path, *, admin_port: int | None = None,
+                          runner: Callable = subprocess.run,
+                          input_stream: IO[str] | None = None,
+                          secret_prompt: Callable[[str], str] = getpass.getpass) -> None:
+    """Root/maintenance/lifetime locks belong to the caller; no service is started."""
+    from .admin.auth import load_credential_snapshot
+    from .settings import Settings
+    import yaml
+
+    source = sys.stdin if input_stream is None else input_stream
+    config_file = root / "config.yaml"
+    if not config_file.exists() and not config_file.is_symlink():
+        config = {
+            "instance": {"dataDir": str(root / "state"),
+                         "projectRoot": str(Path(pwd.getpwuid(os.geteuid()).pw_dir) / "projects")},
+            "projects": {}, "channel": {"securityMode": "audit"},
+            "adminWeb": {"enabled": True, "host": "0.0.0.0"},
+        }
+        if admin_port is not None:
+            config["adminWeb"]["port"] = admin_port
+        _write_atomic(config_file, yaml.safe_dump(config, sort_keys=False).encode(), mode=0o600)
+    else:
+        _private_file(config_file)
+        if admin_port is not None:
+            try:
+                existing = yaml.safe_load(config_file.read_text(encoding="utf-8"))
+            except (UnicodeError, yaml.YAMLError):
+                raise SetupError("existing configuration is invalid; repair it before retrying setup") from None
+            admin = existing.get("adminWeb") if isinstance(existing, dict) else None
+            port = admin.get("port") if isinstance(admin, dict) else None
+            if type(port) is not int or port != admin_port:
+                raise SetupError("--admin-port differs from existing configuration; edit the config explicitly")
+    credential = root / "credentials/admin-web-secret"
+    if not credential.exists() and not credential.is_symlink():
+        _write_atomic(credential, secrets.token_urlsafe(32).encode("ascii"), mode=0o600)
+    _private_file(credential)
+    load_credential_snapshot(credential)
+    profile = root / "lark-app/config.json"
+    if not profile.exists() and not profile.is_symlink():
+        _write_atomic(profile, encode_lark_app("", ""), mode=0o600)
+    credentials = load_lark_app(profile, allow_incomplete=True)
+    started_flow = False
+    if not (credentials.app_id and credentials.app_secret):
+        manual = False
+        if source.isatty():
+            print("Feishu setup: [1] browser (default), [2] manual credentials", file=sys.stderr)
+            choice = source.readline().strip()
+            if choice not in {"", "1", "2"}:
+                raise SetupError("choose 1 or 2 and rerun setup")
+            manual = choice == "2"
+        if manual:
+            _manual_credentials(root, credentials.app_id or None,
+                                source=source, secret_prompt=secret_prompt)
+        else:
+            started_flow = True
+            _browser_or_manual(root, credentials.app_id or None, runner=runner,
+                               source=source, secret_prompt=secret_prompt)
+    missing = _missing_permissions(root, runner=runner)
+    if missing and not started_flow:
+        _browser_or_manual(root, load_lark_app(profile).app_id, runner=runner,
+                           source=source, secret_prompt=secret_prompt)
+        missing = _missing_permissions(root, runner=runner)
+    if missing:
+        raise SetupError("finish tenant approval, publish/install the app, then rerun setup; missing scopes: "
+                         + ", ".join(missing))
+    settings = Settings.from_file(config_file, environment={
+        "NETIZEN_ADMIN_SECRET_FILE": str(credential),
+        "NETIZEN_LARK_APP_CONFIG": str(profile),
+    })
+    if settings.data_dir.resolve() != root / "state":
+        raise SetupError("instance.dataDir must be this instance's state directory")

netizen_cli/cli_update.py

@@ -0,0 +1,303 @@
+"""Environment-scoped, stop-first package update orchestration.
+
+System service definitions remain the inventory. The small copied worker is the
+only process allowed to execute after package replacement; it uses fresh CLI
+processes for restoration and never imports the replaced package.
+"""
+
+from __future__ import annotations
+
+import fcntl
+from contextlib import ExitStack
+import hashlib
+import json
+import os
+import pwd
+import stat
+import sys
+import tempfile
+from pathlib import Path
+from typing import Any
+
+from . import cli_update_worker
+
+
+class UpdateError(RuntimeError):
+    pass
+
+
+def new_report() -> dict[str, Any]:
+    return {
+        "protocol": 1, "status": "running", "phase": "preflight",
+        "environment": None, "backend": None, "inventory_complete": False,
+        "package": {"state": "unchanged", "replacement_started": False,
+                    "before_version": None, "after_version": None},
+        "progress": {"stop_total": 0, "stopped": 0, "start_total": 0, "ready": 0},
+        "instances": [], "reason": None, "recommendation": None,
+        "unexecuted": ["stop", "package-update", "validation", "restore"],
+    }
+
+
+def _private_directory(path: Path) -> None:
+    path.mkdir(mode=0o700, parents=True, exist_ok=True)
+    info = path.lstat()
+    if (not stat.S_ISDIR(info.st_mode) or info.st_uid != os.geteuid()
+            or stat.S_IMODE(info.st_mode) != 0o700):
+        raise UpdateError(f"Update maintenance directory must be owned by this user and private: {path}")
+
+
+def maintenance_directory(prefix: Path, *, home: Path | None = None) -> Path:
+    account_home = Path(pwd.getpwuid(os.geteuid()).pw_dir) if home is None else home
+    digest = hashlib.sha256(os.fsencode(prefix.resolve())).hexdigest()[:24]
+    parent = account_home.resolve()
+    for component in (".cache", "netizen-cli", "updates"):
+        parent = parent / component
+        parent.mkdir(mode=0o700, exist_ok=True)
+        info = parent.lstat()
+        if (not stat.S_ISDIR(info.st_mode) or info.st_uid != os.geteuid()
+                or stat.S_IMODE(info.st_mode) & 0o022):
+            raise UpdateError(f"Unsafe update maintenance parent: {parent}")
+    path = parent / digest
+    _private_directory(path)
+    if path.resolve().is_relative_to(prefix.resolve()):
+        raise UpdateError("Update maintenance files would be inside the installation being replaced")
+    return path
+
+
+def _lock(directory: Path) -> int:
+    descriptor = os.open(directory / "update.lock", os.O_RDWR | os.O_CREAT | os.O_NOFOLLOW, 0o600)
+    try:
+        info = os.fstat(descriptor)
+        if (not stat.S_ISREG(info.st_mode) or info.st_uid != os.geteuid()
+                or stat.S_IMODE(info.st_mode) != 0o600):
+            raise UpdateError("Unrecognized update lock ownership or permissions")
+        try:
+            fcntl.flock(descriptor, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except BlockingIOError as error:
+            raise UpdateError("Another update is already maintaining this Python environment") from error
+        os.set_inheritable(descriptor, True)
+        return descriptor
+    except BaseException:
+        os.close(descriptor)
+        raise
+
+
+def _reject_service_context(service_names: list[str]) -> None:
+    if os.environ.get("NETIZEN_CLI_SERVICE") == "1":
+        raise UpdateError("Run netizen update from an external terminal, not inside a Netizen service")
+    if os.environ.get("XPC_SERVICE_NAME") in service_names:
+        raise UpdateError("The update process belongs to a service it would stop; use an external terminal")
+    if sys.platform == "linux":
+        try:
+            entries = Path("/proc/self/cgroup").read_text(encoding="utf-8").splitlines()
+        except OSError as error:
+            raise UpdateError("Cannot verify that the updater is outside the affected service cgroups") from error
+        for entry in entries:
+            components = entry.split(":", 2)[-1].split("/")
+            if any(name in components for name in service_names):
+                raise UpdateError("The update process belongs to a service it would stop; use an external terminal")
+
+
+def _snapshot(manager: Any, prefix: Path, python: Path) -> list[dict[str, Any]]:
+    instances = []
+    for status in manager.list_instances(prefix=prefix):
+        binding = status.binding
+        if binding.prefix.resolve() != prefix.resolve():
+            continue
+        # Prefix proves the environment, while the lexical launcher is retained.
+        # Different venvs can have the same base-interpreter realpath.
+        if binding.python.parent.resolve() != python.parent.resolve():
+            raise UpdateError(f"Ambiguous interpreter binding for instance {binding.root}")
+        if not isinstance(status.running, bool):
+            raise UpdateError(f"Cannot determine whether instance is running: {binding.root}")
+        needs_stop = _needs_stop(manager, status)
+        instances.append({
+            "root": str(binding.root), "service": manager.service_name(binding.root),
+            "python": str(binding.python), "prefix": str(binding.prefix),
+            "was_running": status.running,
+            "needs_stop": needs_stop,
+            "state": _observed_state(manager, status), "action": None,
+            "reason": None,
+        })
+    return instances
+
+
+def _needs_stop(manager: Any, status: Any) -> bool:
+    # launchd may restart a loaded KeepAlive job even while its PID is absent.
+    # A loaded inactive systemd unit, by contrast, needs no stop operation.
+    if manager.platform == "darwin":
+        if not isinstance(status.loaded, bool):
+            raise UpdateError(f"Cannot determine whether LaunchAgent is loaded: {status.binding.root}")
+        return status.running or status.loaded
+    return status.running
+
+
+def _observed_state(manager: Any, status: Any) -> str:
+    if status.running:
+        return "running"
+    return "loaded" if _needs_stop(manager, status) else "stopped"
+
+
+def _refresh_observed(manager: Any, instances: list[dict[str, Any]]) -> None:
+    for item in instances:
+        try:
+            current = manager.inspect(Path(item["root"]))
+            if current is None:
+                item["state"] = "unregistered"
+            else:
+                item["state"] = _observed_state(manager, current)
+        except Exception:
+            item["state"] = "unknown"
+
+
+def stop_recorded(manager: Any, report: dict[str, Any]) -> None:
+    """A partial stop has no compensation: preserve and report actual states."""
+    report["phase"] = "stopping"
+    for item in report["instances"]:
+        if not item["needs_stop"]:
+            continue
+        item["action"] = "stop"
+        try:
+            stopped = manager.stop(Path(item["root"]))
+            if _needs_stop(manager, stopped):
+                raise UpdateError("Stop returned without confirming process exit and LaunchAgent unload")
+            item["state"] = "stopped"
+            report["progress"]["stopped"] += 1
+        except (Exception, KeyboardInterrupt) as error:
+            item["reason"] = str(error)
+            _refresh_observed(manager, report["instances"])
+            raise UpdateError(f"Stopping {item['root']} failed: {error}") from error
+        if report.get("report_path"):
+            cli_update_worker.persist_report(Path(report["report_path"]), report)
+    # Detect already-observable external starts before the package replacement.
+    for item in report["instances"]:
+        try:
+            current = manager.inspect(Path(item["root"]))
+        except Exception:
+            item["state"] = "unknown"
+            raise
+        if (current is None
+                or current.binding.prefix.resolve() != Path(item["prefix"]).resolve()
+                or str(current.binding.python) != item["python"]):
+            item["state"] = "unknown"
+            raise UpdateError(f"Service binding changed during update: {item['root']}")
+        if _needs_stop(manager, current):
+            item["state"] = _observed_state(manager, current)
+            raise UpdateError(f"Instance started during update or its LaunchAgent is still loaded; "
+                              f"package replacement aborted: {item['root']}")
+    report["unexecuted"] = ["package-update", "validation", "restore"]
+
+
+def _stage_worker(directory: Path, report: dict[str, Any], package: dict[str, Any],
+                  *, json_output: bool, root_locks: dict[str, int]) -> tuple[Path, Path]:
+    worker = directory / "worker.py"
+    worker.write_bytes(Path(cli_update_worker.__file__).read_bytes())
+    worker.chmod(0o600)
+    plan_file = directory / "plan.json"
+    with plan_file.open("x", encoding="utf-8") as stream:
+        json.dump({"protocol": 1, "report": report, "package_plan": package,
+                   "json_output": json_output, "root_locks": root_locks}, stream)
+    plan_file.chmod(0o600)
+    return worker, plan_file
+
+
+def run_update(*, json_output: bool = False, backend: str | None = None,
+               manager: Any = None, prepare: Any = None, home: Path | None = None,
+               executor: Any = os.execv) -> int:
+    """Report early failures, or replace this process with an external worker."""
+    report = new_report()
+    report["environment"] = str(Path(sys.prefix).resolve())
+    report["backend"] = backend
+    descriptor = None
+    root_locks: dict[str, int] = {}
+    maintenance = ExitStack()
+    try:
+        if os.environ.get("NETIZEN_CLI_SERVICE") == "1":
+            raise UpdateError("Run netizen update from an external terminal, not inside a Netizen service")
+        directory = maintenance_directory(Path(sys.prefix), home=home)
+        descriptor = _lock(directory)
+        operation = Path(tempfile.mkdtemp(prefix="operation-", dir=directory))
+        report["report_path"] = str(operation / "report.json")
+        if prepare is None:
+            from .cli_packages import prepare_update
+            prepare = prepare_update
+        package = prepare(work_dir=operation, backend=backend)
+        if Path(package["prefix"]).resolve() != Path(sys.prefix).resolve():
+            raise UpdateError("Package update target does not match the locked current Python environment")
+        report.update(environment=package["prefix"], backend=package["backend"])
+        report["package"]["before_version"] = package["before_version"]
+        if manager is None:
+            from .cli_services import ServiceManager
+            manager = ServiceManager()
+        report["instances"] = _snapshot(
+            manager, Path(package["prefix"]), Path(package["environment_python"]),
+        )
+        report["inventory_complete"] = True
+        _reject_service_context([item["service"] for item in report["instances"]])
+        if package["changes_required"]:
+            from .deployment.update_protocol import install_lock, read_operation, terminal_phase
+            from .instance import require_instance_root_marker
+
+            # Use the very same locks as CLI mutations and Admin restarts. Take
+            # every known root (including stopped instances) before stopping any.
+            for item in sorted(report["instances"], key=lambda row: row["root"]):
+                try:
+                    root = Path(item["root"])
+                    require_instance_root_marker(root)
+                    lock_fd = maintenance.enter_context(install_lock(root))
+                except (OSError, RuntimeError) as error:
+                    raise UpdateError(f"Instance maintenance is busy or unsafe: {item['root']}: {error}") from error
+                os.set_inheritable(lock_fd, True)
+                root_locks[item["root"]] = lock_fd
+                pending = read_operation(root)
+                if pending is not None and not terminal_phase(pending["phase"]):
+                    raise UpdateError(
+                        f"Instance has pending maintenance ({pending['phase']}): {root}. "
+                        "Let its Admin restart finish; inspect status/logs and recover an interrupted "
+                        "restart with netizen start before retrying update."
+                    )
+            current = _snapshot(manager, Path(package["prefix"]), Path(package["environment_python"]))
+            identity = lambda rows: {(row["root"], row["python"], row["prefix"]) for row in rows}
+            if identity(current) != identity(report["instances"]):
+                raise UpdateError("Instance inventory changed while acquiring maintenance locks; retry")
+            report["instances"] = current
+        count = sum(item["was_running"] for item in report["instances"])
+        report["progress"].update(stop_total=sum(item["needs_stop"] for item in report["instances"]),
+                                  start_total=count)
+        print(f"Updating {package['prefix']} using {package['backend']}; "
+              f"{count} running instance(s) affected.", file=sys.stderr)
+        for item in report["instances"]:
+            print(f"  {item['root']}: {item['state']}", file=sys.stderr)
+        if package.get("notice"):
+            print(package["notice"], file=sys.stderr)
+        if not package["changes_required"]:
+            report.update(status="succeeded", phase="complete", reason="No package changes are required.")
+            report["package"]["after_version"] = package["before_version"]
+            report["progress"].update(stop_total=0, start_total=0)
+            report["unexecuted"] = ["stop (not needed)", "package-update (not needed)", "restore (not needed)"]
+        else:
+            print("Running tasks may be interrupted. Only previously running instances will be restored.",
+                  file=sys.stderr)
+            cli_update_worker.persist_report(Path(report["report_path"]), report)
+            stop_recorded(manager, report)
+            worker, plan_file = _stage_worker(operation, report, package,
+                                             json_output=json_output, root_locks=root_locks)
+            # A venv/tool may be recreated by its manager. Use the user's base
+            # interpreter to keep the standard-library-only coordinator outside it.
+            base_python = os.path.abspath(getattr(sys, "_base_executable", sys.executable))
+            executor(base_python, [base_python, "-I", "-B", str(worker), str(plan_file)])
+            raise UpdateError("Update helper handoff unexpectedly returned")
+    except (Exception, KeyboardInterrupt) as error:
+        report.update(status="failed", reason=f"{type(error).__name__}: {error}", recommendation=(
+            "Resolve the reported problem and retry. Package replacement has not started. "
+            "Any instances already stopped remain stopped; start them explicitly if needed. "
+            "Unsupported or ambiguous installations can be maintained manually with their package manager."
+        ))
+    finally:
+        maintenance.close()
+        if descriptor is not None:
+            os.close(descriptor)
+    if report.get("report_path"):
+        cli_update_worker.persist_report(Path(report["report_path"]), report)
+    cli_update_worker.print_report(report, json_output=json_output)
+    return 0 if report["status"] == "succeeded" else 1

netizen_cli/cli_update_restore.py

@@ -0,0 +1,53 @@
+"""Fresh-install, one-shot update restore under an inherited exact root lock.
+
+Not a public lifecycle command: unlike ``start``, this cannot register or change
+a binding. Keeping the updater's lock avoids a release/reacquire window between
+package validation and readiness, and serializes existing Admin/CLI maintenance.
+"""
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+import sys
+from typing import Any, Sequence
+
+from .deployment.update_protocol import validate_inherited_lock
+from .instance import require_instance_root_marker
+
+
+def restore(root: Path, descriptor: int, *, expected_prefix: Path,
+            expected_python: Path, manager: Any = None) -> None:
+    if root != root.resolve() or not root.is_absolute():
+        raise ValueError("Update restoration requires the recorded canonical root")
+    require_instance_root_marker(root)
+    validate_inherited_lock(root, descriptor)
+    if manager is None:
+        from .cli_services import ServiceManager
+        manager = ServiceManager()
+    status = manager.inspect(root)
+    if (status is None or status.binding.prefix != expected_prefix
+            or status.binding.python != expected_python):
+        raise RuntimeError("Service binding changed; update restoration will not register or rebind it")
+    ready = manager.start(root)
+    if not ready.ready:
+        raise RuntimeError("Instance did not confirm readiness")
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Private Netizen update restoration entry")
+    parser.add_argument("--root", type=Path, required=True)
+    parser.add_argument("--lock-fd", type=int, required=True)
+    parser.add_argument("--expected-prefix", type=Path, required=True)
+    parser.add_argument("--expected-python", type=Path, required=True)
+    args = parser.parse_args(argv)
+    try:
+        restore(args.root, args.lock_fd, expected_prefix=args.expected_prefix,
+                expected_python=args.expected_python)
+        return 0
+    except (OSError, ValueError, RuntimeError) as error:
+        print(f"Instance restoration failed: {error}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())