bookmark-research 0.5.0-beta.1

package/scripts/host_assets.py

@@ -0,0 +1,70 @@
+"""Assemble host-owned workflows; this module never starts a host or an agent."""
+
+import json
+from pathlib import Path
+
+
+HOST_SOURCE_FILES = (
+    "hosts/shared/workflow.json", "hosts/shared/research-flow.js", "hosts/shared/research-call.py",
+    "hosts/claude/runtime.js", "hosts/dsh/runtime.js", "hosts/dsh/workflow-call.py", "hosts/dsh/plugin.js",
+    "hosts/pi/runtime.js", "hosts/pi/register-workflow.py",
+    "hosts/codex/delegate.md", "hosts/codex/prepare.py",
+)
+
+
+def read_asset(root, relative):
+    """Read a curated asset without following source symlinks."""
+    current = Path(root)
+    for part in Path(relative).parts:
+        current = current / part
+        if current.is_symlink():
+            raise ValueError("Source symlinks are not exported: " + relative)
+    if not current.is_file():
+        raise ValueError("Required host asset is missing: " + relative)
+    return current.read_bytes()
+
+
+def build_workflow(root, host):
+    if host not in ("claude", "dsh", "pi"):
+        raise ValueError("Unknown workflow host: " + str(host))
+    definition = json.loads(read_asset(root, "hosts/shared/workflow.json"))
+    script = read_asset(root, "hosts/" + host + "/runtime.js").decode("utf-8")
+    script += "\n" + read_asset(root, "hosts/shared/research-flow.js").decode("utf-8")
+    if host == "claude":
+        script = "export const meta = " + json.dumps(definition["meta"], ensure_ascii=False, indent=2) + ";\n\n" + script
+    return definition, script
+
+
+def export_host_assets(source, stage, host):
+    """Return concrete, host-specific assets in the staged distribution."""
+    if host == "agent-plugin":
+        return []  # Do not mix client-specific components into the standard format.
+    files = {"hosts/shared/research-call.py": read_asset(source, "hosts/shared/research-call.py")}
+    if host == "codex":
+        for name in ("delegate.md", "prepare.py"):
+            relative = "hosts/codex/" + name
+            files[relative] = read_asset(source, relative)
+    else:
+        definition, script = build_workflow(source, host)
+        if host == "claude":
+            files["workflows/bookmark-research.js"] = script.encode("utf-8")
+        else:
+            files["workflows/bookmark-research/script.js"] = script.encode("utf-8")
+            if host == "pi":
+                parameters = definition["parameters"]
+                parameters["bridge_path"]["required"] = True
+                workflow = {**definition["meta"], "parameters": parameters}
+                files["workflows/bookmark-research/workflow.json"] = (
+                    json.dumps(workflow, ensure_ascii=False, indent=2) + "\n").encode("utf-8")
+                relative = "hosts/pi/register-workflow.py"
+            else:
+                files["hosts/dsh/plugin.js"] = read_asset(source, "hosts/dsh/plugin.js")
+                files["workflows/bookmark-research/meta.json"] = (
+                    json.dumps(definition["meta"], ensure_ascii=False, indent=2) + "\n").encode("utf-8")
+                relative = "hosts/dsh/workflow-call.py"
+            files[relative] = read_asset(source, relative)
+    for relative, content in files.items():
+        destination = stage / relative
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        destination.write_bytes(content)
+    return sorted(files)

package/scripts/host_clients.py

@@ -0,0 +1,196 @@
+"""Native client commands and read-only registration checks for exported hosts."""
+
+import json
+import os
+from pathlib import Path
+import shutil
+import subprocess
+
+from export_bundle import NAME
+
+
+SELECTOR = NAME + "@" + NAME
+
+
+def executable(binary):
+    """Resolve a CLI, including .cmd/.exe shims that Windows Python 3.9 misses for full paths."""
+    found = shutil.which(binary)
+    if os.name == "nt" and (not found or not Path(found).suffix):
+        for extension in os.environ.get("PATHEXT", ".COM;.EXE;.BAT;.CMD").split(";"):
+            found = shutil.which(binary + extension) or found
+            if found and Path(found).suffix:
+                break
+    return found
+
+
+def read_json(path, default=None):
+    if not path.exists():
+        return default
+    if path.is_symlink():
+        raise ValueError("Refusing a symlink state file: " + str(path))
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def local_path(value, base):
+    if not isinstance(value, str):
+        return None
+    for prefix in ("link:", "file:"):
+        if value.startswith(prefix):
+            value = value[len(prefix):]
+    if ":" in value and not value.startswith("/") and not Path(value).is_absolute():
+        return None
+    path = Path(value).expanduser()
+    return (path if path.is_absolute() else base / path).resolve()
+
+
+class HostClient:
+    def __init__(self, host, binary, timeout, scope=None, project=None, profile=None):
+        self.host, self.binary, self.timeout = host, binary, timeout
+        self.scope = scope or "user"
+        self.cwd = Path(project).expanduser().resolve() if project else Path.cwd()
+        self.profile = profile
+        if host == "dsh":
+            if scope or project:
+                raise ValueError("DSH uses --profile, not --scope or --project")
+            if not profile or not all(c.isalnum() or c in "._-" for c in profile) or profile.startswith("."):
+                raise ValueError("DSH requires --profile NAME (letters, numbers, dots, underscores or hyphens)")
+            self.home = Path(os.environ.get("DSH_HOME", str(Path.home() / ".dsh"))).expanduser().resolve()
+            self.settings = self.home / "profiles" / profile / "package.json"
+        else:
+            if profile:
+                raise ValueError("--profile is only supported for DSH")
+            if self.scope not in (("user", "project", "local") if host == "claude" else ("user", "project")):
+                raise ValueError("Unsupported installation scope for " + host)
+            if self.scope != "user" and not project:
+                raise ValueError("Project/local scope requires --project PATH")
+            if not self.cwd.is_dir():
+                raise ValueError("Project directory does not exist: " + str(self.cwd))
+            variable, default = (("CLAUDE_CONFIG_DIR", Path.home() / ".claude") if host == "claude"
+                                 else ("PI_CODING_AGENT_DIR", Path.home() / ".pi/agent"))
+            self.home = Path(os.environ.get(variable, str(default))).expanduser().resolve()
+            self.settings = (self.home / "settings.json" if self.scope == "user"
+                             else self.cwd / ".pi/settings.json")
+
+    @property
+    def target(self):
+        return {"host": self.host, "client_home": str(self.home),
+                "scope": self.scope if self.host != "dsh" else None,
+                "project": str(self.cwd) if self.host != "dsh" and self.scope != "user" else None,
+                "profile": self.profile}
+
+    def require(self):
+        if not executable(self.binary):
+            raise ValueError(self.host + " CLI was not found: " + self.binary)
+        if self.host == "dsh" and not shutil.which("pnpm"):
+            # dsh plugin forwards to pnpm; fail before creating a profile.
+            raise ValueError("DSH installs profile plugins with pnpm, which was not found on PATH; "
+                             "install it (npm install -g pnpm, or corepack enable pnpm) and retry")
+
+    def run(self, arguments, structured=False, quiet_error=False):
+        result = subprocess.run([executable(self.binary) or self.binary, *arguments], cwd=self.cwd, text=True, encoding="utf-8", errors="replace",
+                                capture_output=True, timeout=self.timeout)
+        if result.returncode:
+            detail = "" if quiet_error else "\n" + (result.stderr or result.stdout).strip()[-3000:]
+            raise RuntimeError(self.host + " command failed: " + " ".join(arguments[:3]) + detail)
+        if not structured:
+            return result.stdout
+        return json.loads(result.stdout)
+
+    def registration(self, bundle):
+        """Reject another source before mutations, and return this target's native state."""
+        if self.host == "claude":
+            marketplaces = self.run(["plugin", "marketplace", "list", "--json"], True)
+            plugins = self.run(["plugin", "list", "--json"], True)
+            if not isinstance(marketplaces, list) or not isinstance(plugins, list):
+                raise ValueError("Unexpected Claude plugin list JSON")
+            if any(not isinstance(row, dict) for row in marketplaces + plugins):
+                raise ValueError("Unexpected Claude plugin list entry")
+            matches = [row for row in marketplaces if row.get("name") == NAME]
+            if len(matches) > 1 or (matches and (matches[0].get("source") != "directory"
+                    or local_path(matches[0].get("path"), self.cwd) != bundle.resolve())):
+                raise ValueError("Claude marketplace bookmark-research uses another source; resolve it in Claude first")
+            other = [row for row in plugins if row.get("scope") == self.scope
+                     and str(row.get("id", "")).startswith(NAME + "@") and row.get("id") != SELECTOR]
+            if other:
+                raise ValueError("Bookmark Research is already installed from another Claude marketplace")
+            rows = [row for row in plugins if row.get("id") == SELECTOR and row.get("scope") == self.scope]
+            if len(rows) > 1:
+                raise ValueError("Multiple Claude registrations match this scope")
+            return {"marketplace": bool(matches), "installed": bool(rows), "plugin": rows[0] if rows else None}
+        settings = read_json(self.settings, {})
+        if not isinstance(settings, dict):
+            raise ValueError("Unexpected client settings object: " + str(self.settings))
+        if self.host == "pi":
+            packages = settings.get("packages", [])
+            if not isinstance(packages, list):
+                raise ValueError("Pi packages must be an array")
+            matches = []
+            for entry in packages:
+                source = entry.get("source") if isinstance(entry, dict) else entry
+                path = local_path(source, self.settings.parent)
+                if path == bundle.resolve():
+                    if isinstance(entry, dict) and (entry.get("skills") == [] or entry.get("autoload") is False):
+                        raise ValueError("The registered Pi package disables its Skill; enable it in Pi first")
+                    matches.append(entry)
+                elif path and path.is_dir():
+                    metadata = read_json(path / "package.json", {})
+                    if isinstance(metadata, dict) and metadata.get("name") == NAME:
+                        raise ValueError("Pi already registers Bookmark Research at another path")
+                elif isinstance(source, str) and ("/Bookmark-Research" in source or source.startswith("npm:" + NAME)):
+                    raise ValueError("Pi already registers another Bookmark Research source")
+            if len(matches) > 1:
+                raise ValueError("Duplicate Pi registrations; resolve them in Pi first")
+            return {"installed": bool(matches)}
+        dependencies, dsh = settings.get("dependencies", {}), settings.get("dsh", {})
+        if not isinstance(dependencies, dict) or not isinstance(dsh, dict) or not isinstance(dsh.get("profile", {}), dict):
+            raise ValueError("Unexpected DSH profile manifest")
+        dependency = dependencies.get(NAME)
+        if dependency and local_path(dependency, self.settings.parent) != bundle.resolve():
+            raise ValueError("DSH profile already installs Bookmark Research from another source")
+        bundles = settings.get("dsh", {}).get("profile", {}).get("bundles", [])
+        if not isinstance(bundles, list):
+            raise ValueError("DSH profile bundles must be an array")
+        return {"installed": bool(dependency), "enabled": NAME in bundles}
+
+    def commands(self, bundle, registration, changed=False):
+        if self.host == "claude":
+            commands = []
+            if not registration["marketplace"]:
+                commands.append(["plugin", "marketplace", "add", str(bundle), "--scope", self.scope])
+            if registration["installed"]:
+                if changed:
+                    commands.extend([["plugin", "marketplace", "update", NAME],
+                                     ["plugin", "update", SELECTOR, "--scope", self.scope]])
+                if not registration["plugin"].get("enabled"):
+                    raise ValueError("The Claude plugin is disabled; enable it in Claude before reinstalling")
+            else:
+                commands.append(["plugin", "install", SELECTOR, "--scope", self.scope])
+            return commands
+        if self.host == "pi":
+            return [] if registration["installed"] else [["install", str(bundle), *(["-l"] if self.scope == "project" else [])]]
+        return [] if registration["installed"] and registration["enabled"] and not changed else [
+            ["plugin", "--profile", self.profile, "add", str(bundle)]]
+
+    def installed_path(self, bundle, version):
+        registration = self.registration(bundle)
+        if not registration["installed"]:
+            raise RuntimeError(self.host + " did not confirm the expected native registration")
+        if self.host == "claude":
+            plugin = registration["plugin"]
+            if not plugin.get("enabled") or plugin.get("version") != version:
+                raise RuntimeError("Claude did not activate the expected plugin version")
+            path = plugin.get("installPath")
+            if not isinstance(path, str) or not Path(path).is_dir():
+                raise RuntimeError("Claude did not return a valid installed cache path")
+            return Path(path).resolve()
+        if self.host == "dsh":
+            if not registration["enabled"]:
+                raise RuntimeError("DSH installed the dependency without enabling its bundle")
+            composition = self.run(["--profile", self.profile, "--dump-config"], quiet_error=True)
+            if not all(name in composition for name in ("bookmark-research-skill", "bookmark-research-mcp", "bookmarkResearchPaths")):
+                raise RuntimeError("DSH composition is missing the Bookmark Research Skill or MCP configuration")
+            package = self.settings.parent / "node_modules" / NAME
+            if not package.is_dir():
+                raise RuntimeError("DSH did not retain the installed bundle in its profile")
+            return package.resolve()
+        return bundle

package/scripts/host_install.py

@@ -0,0 +1,277 @@
+"""Persist complete host exports and delegate registration to native clients."""
+
+from contextlib import contextmanager
+import hashlib
+import json
+import os
+from pathlib import Path
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+
+from export_bundle import SOURCE_ROOT, _write_adapter, export_bundle, read_plugin_manifest
+from host_clients import HostClient, read_json
+
+
+def _write_json(path, value):
+    with tempfile.NamedTemporaryFile(mode="w", encoding="utf-8", newline="", dir=path.parent, delete=False) as stream:
+        temporary = Path(stream.name)
+        json.dump(value, stream, ensure_ascii=False, indent=2)
+        stream.write("\n")
+        stream.flush()
+        os.fsync(stream.fileno())
+    try:
+        os.replace(temporary, path)
+    finally:
+        temporary.unlink(missing_ok=True)
+
+
+def _files(root):
+    result = {}
+    for path in sorted(root.rglob("*")):
+        relative = path.relative_to(root)
+        if any(part in ("__pycache__", "node_modules", ".git") for part in relative.parts) or path.suffix in (".pyc", ".pyo"):
+            continue
+        if path.is_symlink():
+            raise ValueError("Unexpected link in managed package: " + str(relative))
+        if path.is_file():
+            result[relative.as_posix()] = hashlib.sha256(path.read_bytes()).hexdigest()
+    return result
+
+
+def _check_files(root, expected, exact=False):
+    if exact and _files(root) != expected:
+        raise RuntimeError("Installed package differs from its verified source; preserve local edits before updating")
+    for relative, digest in expected.items():
+        path = root / relative
+        current = root
+        for part in Path(relative).parts:
+            if current.is_symlink():
+                raise RuntimeError("Unexpected link in installed package: " + relative)
+            current = current / part
+        if path.is_symlink() or not path.is_file() or hashlib.sha256(path.read_bytes()).hexdigest() != digest:
+            raise RuntimeError("Installed package differs from its verified source: " + relative)
+
+
+def _source(value, ref=None):
+    # Keep Git URL normalization identical to the existing Codex installer.
+    from install import _repository
+    value = str(value)
+    if not value or any(ord(char) < 32 for char in value):
+        raise ValueError("Source must be a nonempty path or Git repository")
+    path = Path(value).expanduser()
+    if path.exists() or value.startswith(("/", "./", "../", "~")):
+        if ref:
+            raise ValueError("--ref only applies to Git; update local source files yourself")
+        root = path.resolve()
+        read_plugin_manifest(root)
+        return {"sourceType": "local", "source": str(root)}
+    if ref and (ref.startswith("-") or not re.fullmatch(r"[A-Za-z0-9_./-]+", ref)):
+        raise ValueError("Invalid Git ref")
+    return {"sourceType": "git", "source": _repository(value), "ref": ref}
+
+
+@contextmanager
+def _checkout(source, timeout):
+    if source["sourceType"] == "local":
+        yield Path(source["source"]), None
+        return
+    with tempfile.TemporaryDirectory(prefix="bookmark-host-source-") as directory:
+        root = Path(directory)
+        environment = dict(os.environ, GIT_TERMINAL_PROMPT="0")
+        for arguments in (["init", "--quiet"], ["remote", "add", "origin", source["source"]],
+                          ["fetch", "--quiet", "--depth", "1", "origin", source.get("ref") or "HEAD"],
+                          ["checkout", "--quiet", "--detach", "FETCH_HEAD"]):
+            completed = subprocess.run(["git", "-C", str(root), *arguments], env=environment,
+                                       capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=timeout)
+            if completed.returncode:
+                raise RuntimeError("Could not prepare the registered Git source: " + completed.stderr.strip()[-2000:])
+        revision = subprocess.run(["git", "-C", str(root), "rev-parse", "HEAD"], capture_output=True,
+                                  text=True, encoding="utf-8", errors="replace", check=True, timeout=timeout).stdout.strip()
+        yield root, revision
+
+
+def runtime_check(root, timeout):
+    """Check the exported CLI and stdio protocol using an empty, disposable store."""
+    requests = [
+        {"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {
+            "protocolVersion": "2025-11-25", "capabilities": {},
+            "clientInfo": {"name": "bookmark-host-installer", "version": "1"}}},
+        {"jsonrpc": "2.0", "method": "notifications/initialized"},
+        {"jsonrpc": "2.0", "id": 2, "method": "tools/list"},
+    ]
+    with tempfile.TemporaryDirectory(prefix="bookmark-host-probe-") as directory:
+        data = Path(directory)
+        environment = dict(os.environ, PYTHONDONTWRITEBYTECODE="1",
+                           BOOKMARK_RESEARCH_DATA_DIR=str(data / "data"),
+                           BOOKMARK_RESEARCH_CONFIG=str(data / "settings.json"))
+        command = [sys.executable, "-B", str(root / "src/cli.py")]
+        doctor = subprocess.run([*command, "doctor"], cwd=data, env=environment, capture_output=True,
+                                text=True, encoding="utf-8", errors="replace", timeout=timeout)
+        if doctor.returncode or json.loads(doctor.stdout).get("fts5") is not True:
+            raise RuntimeError("Exported Python runtime requires Python 3.9+ and SQLite FTS5")
+        mcp = subprocess.run([*command, "serve"], cwd=data, env=environment, capture_output=True,
+                             text=True, encoding="utf-8", errors="replace", input="".join(json.dumps(row) + "\n" for row in requests), timeout=timeout)
+        if mcp.returncode:
+            raise RuntimeError("Exported MCP runtime failed to start")
+        responses = {row.get("id"): row for row in map(json.loads, mcp.stdout.splitlines())}
+        names = sorted(row["name"] for row in responses.get(2, {}).get("result", {}).get("tools", []))
+        if "result" not in responses.get(1, {}) or not {"search_bookmarks", "search_web", "fetch_web"} <= set(names):
+            raise RuntimeError("Exported MCP runtime did not expose the expected tools")
+        if (data / "data/index.sqlite3").exists():
+            raise RuntimeError("Runtime discovery unexpectedly created a database")
+        return {"fts5": True, "mcp_tools": names, "network_checked": False,
+                "database_created": False, "host_session_checked": False}
+
+
+def _load_receipt(path, target):
+    receipt = read_json(path)
+    if receipt is None:
+        return None
+    if not isinstance(receipt, dict) or receipt.get("schema") != 1 or receipt.get("target") != target:
+        raise ValueError("Invalid or mismatched installation receipt: " + str(path))
+    files = receipt.get("files")
+    if not isinstance(files, dict) or not files:
+        raise ValueError("Installation receipt has no package checksums")
+    for relative, digest in files.items():
+        if Path(relative).is_absolute() or ".." in Path(relative).parts or not re.fullmatch(r"[a-f0-9]{64}", str(digest)):
+            raise ValueError("Invalid package checksum in installation receipt")
+    if receipt.get("source", {}).get("sourceType") not in ("git", "local"):
+        raise ValueError("Invalid source in installation receipt")
+    return receipt
+
+
+def _verify(client, bundle, receipt):
+    _check_files(bundle, receipt["files"], exact=True)
+    root = client.installed_path(bundle, receipt["version"])
+    _check_files(root, receipt["files"])
+    return {"host": client.host, "installed": True, "verified": True,
+            "version": receipt["version"], "release_version": receipt["release_version"],
+            "installed_path": str(root), "source": receipt["source"], "target": client.target,
+            "runtime": runtime_check(root, client.timeout)}
+
+
+def _manage(action, client, base, source, ref, dry_run):
+    bundle, receipt_path = base / "bundle", base / "receipt.json"
+    receipt = _load_receipt(receipt_path, client.target)
+    if action == "verify":
+        if not receipt:
+            raise ValueError("No managed installation for this host and scope/profile; run install first")
+        result = _verify(client, bundle, receipt)
+        if receipt.get("state") != "verified":
+            receipt["state"] = "verified"
+            _write_json(receipt_path, receipt)
+        return result
+    if receipt:
+        if source is not None:
+            requested = _source(source, ref)
+            old = receipt["source"]
+            if (requested["sourceType"], requested["source"]) != (old["sourceType"], old["source"]) or (ref is not None and ref != old.get("ref")):
+                raise ValueError("Existing installation retains its source and ref; choose a separate installation directory for another source")
+        elif ref is not None and ref != receipt["source"].get("ref"):
+            raise ValueError("Existing installation retains its registered ref")
+        requested = receipt["source"]
+        if bundle.exists():
+            _check_files(bundle, receipt["files"], exact=True)
+    else:
+        if action == "update":
+            raise ValueError("No managed installation for this target; run install first with the intended scope/profile")
+        if bundle.exists() or bundle.is_symlink():
+            raise ValueError("Refusing an existing package without an installation receipt")
+        requested = _source(source if source is not None else SOURCE_ROOT, ref)
+    if requested["sourceType"] == "local" and (Path(requested["source"]) == base or Path(requested["source"]) in base.parents):
+        raise ValueError("The managed installation directory must be outside the source checkout")
+    registration = client.registration(bundle)
+    with _checkout(requested, client.timeout) as (root, revision), tempfile.TemporaryDirectory(
+            prefix=".bookmark-stage-", dir=base if not dry_run else None) as temporary:
+        stage = Path(temporary) / "bundle"
+        # Windows has no python3 alias by default; pin the interpreter running the installer.
+        python = sys.executable if os.name == "nt" else "python3"
+        export_bundle(client.host, stage, root, python)
+        manifest = read_plugin_manifest(root)
+        # Render path-dependent manual instructions for the persistent location.
+        _write_adapter(stage, client.host, bundle, manifest, python)
+        content = _files(stage)
+        digest = hashlib.sha256(json.dumps(content, sort_keys=True).encode()).hexdigest()
+        version = manifest["version"]
+        if client.host == "claude":
+            # Claude caches explicit versions. Content changes on main must get a
+            # new native cache entry without modifying the source release version.
+            version = version.split("+", 1)[0] + "+source." + digest[:16]
+            path = stage / ".claude-plugin/plugin.json"
+            metadata = read_json(path)
+            metadata["version"] = version
+            _write_json(path, metadata)
+            for relative in (".claude-plugin/plugin.json", ".claude-plugin/marketplace.json"):
+                client.run(["plugin", "validate", "--strict", str(stage / relative)])
+        files = _files(stage)
+        runtime_check(stage, client.timeout)
+        changed = not receipt or files != receipt["files"]
+        commands = client.commands(bundle, registration, changed or (receipt and receipt.get("state") != "verified"))
+        plan = {"host": client.host, "action": action, "source": requested, "target": client.target,
+                "bundle_path": str(bundle), "receipt_path": str(receipt_path), "dry_run": dry_run,
+                "version": version, "release_version": manifest["version"], "revision": revision,
+                "commands": [[client.binary, *arguments] for arguments in commands], "changed": changed}
+        if dry_run:
+            return plan
+        new_receipt = {"schema": 1, "state": "pending", "target": client.target, "source": requested,
+                       "revision": revision, "version": version, "release_version": manifest["version"], "files": files}
+        previous = Path(temporary) / "previous"
+        if bundle.exists():
+            bundle.rename(previous)
+        try:
+            stage.rename(bundle)
+            _write_json(receipt_path, new_receipt)
+            for arguments in commands:
+                client.run(arguments)
+            checked = _verify(client, bundle, new_receipt)
+            new_receipt["state"] = "verified"
+            _write_json(receipt_path, new_receipt)
+        except BaseException:
+            if previous.exists():
+                if bundle.exists():
+                    bundle.rename(Path(temporary) / "failed")
+                previous.rename(bundle)
+                failed_receipt = dict(receipt)
+            else:
+                # A native command may already reference this path. Keep it for
+                # recovery instead of leaving a newly registered package dangling.
+                failed_receipt = new_receipt
+            failed_receipt["state"] = "needs_verification"
+            _write_json(receipt_path, failed_receipt)
+            raise
+        return {**plan, **checked, "next_step": "Restart " + client.host + " to load the installed Skill and tools."}
+
+
+def manage_host(action, host, binary=None, timeout=60, source=None, ref=None, dry_run=False,
+                scope=None, project=None, profile=None, install_dir=None):
+    if host not in ("claude", "pi", "dsh"):
+        raise ValueError("Unsupported host: " + host)
+    client = HostClient(host, binary or host, timeout, scope, project, profile)
+    client.require()
+    data_home = Path(os.environ.get("XDG_DATA_HOME", str(Path.home() / ".local/share"))).expanduser()
+    if not data_home.is_absolute():
+        data_home = Path.home() / ".local/share"
+    home = Path(install_dir or os.environ.get("BOOKMARK_RESEARCH_INSTALL_DIR", str(data_home / "bookmark-research/installations"))).expanduser().resolve()
+    key = hashlib.sha256(json.dumps(client.target, sort_keys=True).encode()).hexdigest()[:16]
+    base = home / (host + "-" + key)
+    if base.is_symlink():
+        raise ValueError("Refusing a symlink installation directory")
+    if dry_run or (action == "verify" and not base.exists()):
+        return _manage(action, client, base, source, ref, dry_run)
+    base.mkdir(parents=True, exist_ok=True)
+    # The OS releases these locks on a crash; they stop two installers from
+    # replacing the same persistent package.
+    with (base / "install.lock").open("a") as lock:
+        try:
+            if os.name == "nt":
+                import msvcrt
+                msvcrt.locking(lock.fileno(), msvcrt.LK_NBLCK, 1)
+            else:
+                import fcntl
+                fcntl.flock(lock, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except OSError as error:
+            raise RuntimeError("Another installer is already changing this target") from error
+        return _manage(action, client, base, source, ref, dry_run)