fix(augment): make hook installation transactional

tests/augment_support.py

@@ -0,0 +1,201 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+import json
+import os
+from pathlib import Path
+import subprocess  # nosec B404
+from threading import Thread
+from typing import Any, Mapping
+
+import pytest
+
+from elydora.plugins import augment_contract as contract
+from elydora.plugins.augment import AugmentPlugin
+from elydora.plugins.base import InstallConfig
+from elydora.utils import base64url_encode
+
+
+AGENT_ID = "agent-1"
+MISSING = object()
+VALID_PRIVATE_KEY = base64url_encode(bytes(range(32)))
+
+
+@dataclass
+class AugmentFixture:
+    root_dir: Path
+    home_dir: Path
+    project_dir: Path
+    config_path: Path
+    agent_dir: Path
+    guard_path: Path
+    hook_path: Path
+    guard_wrapper_path: Path
+    audit_wrapper_path: Path
+    runtime_config_path: Path
+    private_key_path: Path
+    plugin: AugmentPlugin
+    config: InstallConfig
+
+    def install(self) -> None:
+        self.plugin.install(self.config)
+
+    def settings(self) -> dict[str, Any]:
+        return json.loads(self.config_path.read_text(encoding="utf-8"))
+
+
+class ElydoraApiHandler(BaseHTTPRequestHandler):
+    agent_status: Any = "active"
+    operation_status = 201
+    requests: list[dict[str, Any]] = []
+
+    @classmethod
+    def reset(cls, status: Any, operation_status: int) -> None:
+        cls.agent_status = status
+        cls.operation_status = operation_status
+        cls.requests = []
+
+    def _respond(self, status: int, value: object) -> None:
+        body = json.dumps(value).encode()
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def do_GET(self) -> None:
+        type(self).requests.append(
+            {
+                "method": "GET",
+                "path": self.path,
+                "authorization": self.headers.get("Authorization"),
+            }
+        )
+        self._respond(200, {"agent": {"status": type(self).agent_status}})
+
+    def do_POST(self) -> None:
+        length = int(self.headers.get("Content-Length", "0"))
+        raw = self.rfile.read(length)
+        type(self).requests.append(
+            {
+                "method": "POST",
+                "path": self.path,
+                "authorization": self.headers.get("Authorization"),
+                "raw": raw,
+                "json": json.loads(raw),
+            }
+        )
+        self._respond(
+            type(self).operation_status,
+            {"operation": {"accepted": True}},
+        )
+
+    def log_message(self, _format: str, *_args: object) -> None:
+        return
+
+
+def start_api_server(
+    *, status: Any = "active", operation_status: int = 201
+) -> ThreadingHTTPServer:
+    ElydoraApiHandler.reset(status, operation_status)
+    server = ThreadingHTTPServer(("127.0.0.1", 0), ElydoraApiHandler)
+    Thread(target=server.serve_forever, daemon=True).start()
+    return server
+
+
+def server_base_url(server: ThreadingHTTPServer) -> str:
+    return f"http://127.0.0.1:{server.server_port}"
+
+
+def write_text(path: Path, source: str, mode: int = 0o600) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(source, encoding="utf-8")
+    os.chmod(path, mode)
+
+
+def write_json(path: Path, value: object, mode: int = 0o600) -> None:
+    source = value if isinstance(value, str) else json.dumps(value, indent=2) + "\n"
+    write_text(path, source, mode)
+
+
+def prepare_fixture(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+    *,
+    existing_settings: object = MISSING,
+    base_url: str = "http://127.0.0.1:9",
+) -> AugmentFixture:
+    home_dir = tmp_path / "home with spaces and 'quote %AUGGIE%"
+    project_dir = tmp_path / "project with spaces"
+    project_dir.mkdir(parents=True)
+    monkeypatch.setenv("HOME", str(home_dir))
+    monkeypatch.setenv("USERPROFILE", str(home_dir))
+    monkeypatch.chdir(project_dir)
+    monkeypatch.setattr(contract, "home_dir", lambda: str(home_dir))
+    config_path = home_dir / ".augment" / "settings.json"
+    agent_dir = home_dir / ".elydora" / AGENT_ID
+    guard_path = agent_dir / contract.GUARD_SCRIPT
+    hook_path = agent_dir / contract.AUDIT_SCRIPT
+    if existing_settings is not MISSING:
+        write_json(config_path, existing_settings)
+    return AugmentFixture(
+        root_dir=tmp_path,
+        home_dir=home_dir,
+        project_dir=project_dir,
+        config_path=config_path,
+        agent_dir=agent_dir,
+        guard_path=guard_path,
+        hook_path=hook_path,
+        guard_wrapper_path=agent_dir / contract.GUARD_WRAPPER,
+        audit_wrapper_path=agent_dir / contract.AUDIT_WRAPPER,
+        runtime_config_path=agent_dir / "config.json",
+        private_key_path=agent_dir / "private.key",
+        plugin=AugmentPlugin(),
+        config={
+            "org_id": "org-1",
+            "agent_id": AGENT_ID,
+            "agent_name": "augment",
+            "private_key": VALID_PRIVATE_KEY,
+            "kid": "key-1",
+            "token": "token-1",
+            "base_url": base_url,
+            "guard_script_path": str(guard_path),
+        },
+    )
+
+
+def managed_handler(
+    settings: Mapping[str, Any], event: str, wrapper_path: Path
+) -> dict[str, Any]:
+    command = contract.build_command(str(wrapper_path))
+    for group in settings["hooks"][event]:
+        for handler in group["hooks"]:
+            if handler.get("command") == command:
+                return handler
+    raise AssertionError(f"managed handler for {event!r} not found")
+
+
+def run_handler(
+    handler: Mapping[str, Any], payload: bytes, fixture: AugmentFixture
+) -> subprocess.CompletedProcess[bytes]:
+    return subprocess.run(  # nosec B602
+        str(handler["command"]),
+        shell=True,
+        input=payload,
+        capture_output=True,
+        check=False,
+        cwd=fixture.project_dir,
+        env={
+            **os.environ,
+            "HOME": str(fixture.home_dir),
+            "USERPROFILE": str(fixture.home_dir),
+        },
+    )
+
+
+def symlink_or_skip(target: Path, link: Path, *, directory: bool = False) -> None:
+    try:
+        link.symlink_to(target, target_is_directory=directory)
+    except OSError as error:
+        pytest.skip(f"Symbolic links unavailable: {error}")

tests/test_augment_official.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+import shutil
+import subprocess  # nosec B404
+
+import pytest
+
+from augment_support import prepare_fixture
+
+
+AUGGIE_ENTRY = os.environ.get("ELYDORA_AUGGIE_ENTRY")
+
+
+@pytest.mark.skipif(
+    AUGGIE_ENTRY is None,
+    reason="set ELYDORA_AUGGIE_ENTRY to the official Auggie entry file",
+)
+def test_official_auggie_accepts_installed_user_hook_contract(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    node = shutil.which("node")
+    assert node is not None
+    assert AUGGIE_ENTRY is not None
+    fixture = prepare_fixture(monkeypatch, tmp_path)
+    fixture.install()
+    environment = {
+        **os.environ,
+        "HOME": str(fixture.home_dir),
+        "USERPROFILE": str(fixture.home_dir),
+    }
+    version = subprocess.run(  # nosec B603
+        [node, AUGGIE_ENTRY, "--version"],
+        capture_output=True,
+        check=False,
+        cwd=fixture.project_dir,
+        env=environment,
+        text=True,
+        timeout=10,
+    )
+    assert version.returncode == 0, version.stderr
+    assert "0.33.0" in version.stdout
+
+    load = subprocess.run(  # nosec B603
+        [node, AUGGIE_ENTRY, "tools", "list"],
+        capture_output=True,
+        check=False,
+        cwd=fixture.project_dir,
+        env=environment,
+        text=True,
+        timeout=15,
+    )
+    assert load.returncode == 0, load.stderr
+    output = f"{load.stdout}\n{load.stderr}".lower()
+    for error in (
+        "invalid settings",
+        "settings validation",
+        "failed to parse",
+        "hook configuration error",
+    ):
+        assert error not in output

tests/test_augment_plugin.py

@@ -1,141 +1,37 @@
 from __future__ import annotations
 
-from dataclasses import dataclass
 import json
 import os
 from pathlib import Path
-import subprocess
-from typing import Any
+import subprocess  # nosec B404
+import sys
 
 import pytest
 
+from augment_support import (
+    AGENT_ID,
+    VALID_PRIVATE_KEY,
+    managed_handler,
+    prepare_fixture,
+    write_text,
+)
 from elydora import cli
 from elydora.plugins import augment
 from elydora.plugins import augment_contract as contract
-from elydora.plugins.base import InstallConfig
 from elydora.plugins.registry import SUPPORTED_AGENTS
 
 
-AGENT_ID = "agent-1"
-MISSING = object()
-
-
-@dataclass(frozen=True)
-class AugmentFixture:
-    plugin: augment.AugmentPlugin
-    config: InstallConfig
-    home_dir: Path
-    workspace_dir: Path
-    agent_dir: Path
-    config_path: Path
-    guard_path: Path
-    hook_path: Path
-    guard_wrapper_path: Path
-    audit_wrapper_path: Path
-    runtime_config_path: Path
-    private_key_path: Path
-
-
-def prepare_fixture(
-    monkeypatch: pytest.MonkeyPatch,
-    tmp_path: Path,
-    *,
-    existing_settings: object = MISSING,
-    create_guard: bool = True,
-) -> AugmentFixture:
-    home_dir = tmp_path / "home with spaces and 'quote"
-    workspace_dir = home_dir / "workspace"
-    agent_dir = home_dir / ".elydora" / AGENT_ID
-    config_path = home_dir / ".augment" / "settings.json"
-    guard_path = agent_dir / contract.GUARD_SCRIPT
-    hook_path = agent_dir / contract.AUDIT_SCRIPT
-    guard_wrapper_path = agent_dir / contract.GUARD_WRAPPER
-    audit_wrapper_path = agent_dir / contract.AUDIT_WRAPPER
-    workspace_dir.mkdir(parents=True)
-    agent_dir.mkdir(parents=True)
-    if create_guard:
-        guard_path.write_text(
-            "import sys\nsys.stdin.read()\n"
-            "sys.stderr.write('Agent is frozen by Elydora.')\n"
-            "raise SystemExit(2)\n",
-            encoding="utf-8",
-        )
-    if existing_settings is not MISSING:
-        config_path.parent.mkdir(parents=True, exist_ok=True)
-        raw = (
-            str(existing_settings)
-            if isinstance(existing_settings, str)
-            else json.dumps(existing_settings, indent=2)
-        )
-        config_path.write_text(raw, encoding="utf-8")
-
-    monkeypatch.setattr(contract, "home_dir", lambda: str(home_dir))
-    config: InstallConfig = {
-        "agent_id": AGENT_ID,
-        "agent_name": "augment",
-        "org_id": "org-1",
-        "private_key": "test-key",
-        "kid": "kid-1",
-        "base_url": "https://api.elydora.test",
-        "guard_script_path": str(guard_path),
-    }
-    return AugmentFixture(
-        plugin=augment.AugmentPlugin(),
-        config=config,
-        home_dir=home_dir,
-        workspace_dir=workspace_dir,
-        agent_dir=agent_dir,
-        config_path=config_path,
-        guard_path=guard_path,
-        hook_path=hook_path,
-        guard_wrapper_path=guard_wrapper_path,
-        audit_wrapper_path=audit_wrapper_path,
-        runtime_config_path=agent_dir / "config.json",
-        private_key_path=agent_dir / "private.key",
-    )
-
-
-def managed_handler(
-    settings: dict[str, Any], event: str, wrapper_path: Path
-) -> dict[str, Any]:
-    command = contract.build_command(str(wrapper_path))
-    for group in settings["hooks"][event]:
-        for handler in group["hooks"]:
-            if handler.get("command") == command:
-                return handler
-    raise AssertionError(f"managed {event} handler not found")
-
-
-def run_command(
-    command: str,
-    home_dir: Path,
-    payload: str,
-) -> subprocess.CompletedProcess[str]:
-    return subprocess.run(
-        command,
-        shell=True,
-        capture_output=True,
-        check=False,
-        env={
-            **os.environ,
-            "HOME": str(home_dir),
-            "USERPROFILE": str(home_dir),
-        },
-        input=payload,
-        text=True,
-    )
-
-
-def test_augment_is_registered_in_sdk_and_cli() -> None:
+def test_augment_is_registered_and_owns_its_complete_runtime() -> None:
     assert SUPPORTED_AGENTS["augment"] == {
         "name": "Augment Code CLI",
         "hook_event": "PreToolUse/PostToolUse",
         "config_path": "~/.augment/settings.json",
     }
     assert cli.PLUGIN_MAP["augment"] is augment.AugmentPlugin
+    assert augment.AugmentPlugin.manages_guard_runtime is True
 
 
-def test_install_preserves_user_settings_and_is_idempotent(
+def test_install_preserves_official_settings_and_is_idempotent(
     monkeypatch: pytest.MonkeyPatch,
     tmp_path: Path,
     capsys: pytest.CaptureFixture[str],
@@ -153,34 +49,42 @@ def test_install_preserves_user_settings_and_is_idempotent(
                             "timeout": 5_000,
                         }
                     ],
-                    "metadata": {"includeUserContext": True},
+                    "metadata": {
+                        "includeConversationData": True,
+                        "includeMCPMetadata": False,
+                        "includeUserContext": True,
+                    },
                     "label": "keep group metadata",
                 }
             ],
+            "PromptSubmit": [
+                {"hooks": [{"type": "command", "command": "prompt-hook"}]}
+            ],
+            "Notification": [
+                {"hooks": [{"type": "command", "command": "notification-hook"}]}
+            ],
             "PreToolUse": [
                 {
                     "matcher": "(?<tool>launch-process)",
-                    "hooks": [
-                        {
-                            "type": "command",
-                            "command": "user-command",
-                        }
-                    ],
+                    "hooks": [{"type": "command", "command": "user-command"}],
                 }
             ],
         },
     }
     fixture = prepare_fixture(monkeypatch, tmp_path, existing_settings=existing)
-    fixture.plugin.install(fixture.config)
-    fixture.plugin.install(fixture.config)
+    fixture.install()
+    first = fixture.config_path.read_text(encoding="utf-8")
+    fixture.install()
+    assert fixture.config_path.read_text(encoding="utf-8") == first
     assert "user-level PreToolUse and PostToolUse" in capsys.readouterr().out
-    settings = json.loads(fixture.config_path.read_text(encoding="utf-8"))
+
+    settings = fixture.settings()
     assert settings["telemetryEnabled"] is False
-    assert settings["hooks"]["SessionStart"] == existing["hooks"]["SessionStart"]
+    for event in ("SessionStart", "PromptSubmit", "Notification"):
+        assert settings["hooks"][event] == existing["hooks"][event]
     assert settings["hooks"]["PreToolUse"][0] == existing["hooks"]["PreToolUse"][0]
     assert len(settings["hooks"]["PreToolUse"]) == 2
     assert len(settings["hooks"]["PostToolUse"]) == 1
-    assert settings["hooks"]["PreToolUse"][1]["matcher"] == ".*"
     for event, wrapper_path in (
         ("PreToolUse", fixture.guard_wrapper_path),
         ("PostToolUse", fixture.audit_wrapper_path),
@@ -189,97 +93,67 @@ def test_install_preserves_user_settings_and_is_idempotent(
         assert set(handler) == {"type", "command", "timeout"}
         assert handler["type"] == "command"
         assert handler["timeout"] == 10_000
+
+    assert json.loads(fixture.runtime_config_path.read_text(encoding="utf-8")) == {
+        "org_id": "org-1",
+        "agent_id": AGENT_ID,
+        "kid": "key-1",
+        "base_url": "http://127.0.0.1:9",
+        "agent_name": "augment",
+        "token": "token-1",
+    }
+    assert fixture.private_key_path.read_text(encoding="utf-8") == VALID_PRIVATE_KEY
+    assert "NATIVE_PAYLOAD = True" in fixture.hook_path.read_text(encoding="utf-8")
     guard_wrapper = fixture.guard_wrapper_path.read_text(encoding="utf-8")
-    audit_wrapper = fixture.audit_wrapper_path.read_text(encoding="utf-8")
     assert fixture.guard_path.name in guard_wrapper
-    assert fixture.hook_path.name in audit_wrapper
+    assert fixture.hook_path.name in fixture.audit_wrapper_path.read_text(
+        encoding="utf-8"
+    )
     if os.name == "nt":
         assert guard_wrapper.startswith("@echo off\n")
         assert "exit /b %errorlevel%" in guard_wrapper
     else:
         assert fixture.guard_wrapper_path.stat().st_mode & 0o111
         assert guard_wrapper.startswith("#!/bin/sh\nexec ")
-    assert (
-        json.loads(fixture.runtime_config_path.read_text(encoding="utf-8"))[
-            "agent_name"
-        ]
-        == "augment"
-    )
-    assert fixture.private_key_path.read_text(encoding="utf-8") == "test-key"
-    assert (fixture.workspace_dir / ".augment" / "settings.json").exists() is False
-    assert (
-        fixture.workspace_dir / ".augment" / "settings.local.json"
-    ).exists() is False
+    assert not (fixture.project_dir / ".augment" / "settings.json").exists()
 
 
-def test_wrappers_block_and_forward_official_payload_byte_for_byte(
+def test_install_replaces_stale_handlers_and_preserves_empty_groups(
     monkeypatch: pytest.MonkeyPatch, tmp_path: Path
 ) -> None:
     fixture = prepare_fixture(monkeypatch, tmp_path)
-    fixture.plugin.install(fixture.config)
-    capture_path = tmp_path / "captured-event.json"
-    fixture.hook_path.write_text(
-        "from pathlib import Path\nimport sys\n"
-        f"Path({str(capture_path)!r}).write_text("
-        "sys.stdin.read(), encoding='utf-8')\n",
-        encoding="utf-8",
+    fixture.install()
+    settings = fixture.settings()
+    settings["hooks"]["PreToolUse"].insert(
+        0, {"hooks": [], "label": "keep empty group"}
     )
-    settings = json.loads(fixture.config_path.read_text(encoding="utf-8"))
-    pre_payload = json.dumps(
-        {
-            "hook_event_name": "PreToolUse",
-            "conversation_id": "conversation-1",
-            "workspace_roots": [str(fixture.workspace_dir)],
-            "tool_name": "launch-process",
-            "tool_input": {"command": "echo test"},
-            "is_mcp_tool": False,
-        },
-        separators=(",", ":"),
-    )
-    guard = managed_handler(settings, "PreToolUse", fixture.guard_wrapper_path)
-    guard_result = run_command(guard["command"], fixture.home_dir, pre_payload)
-    assert guard_result.returncode == 2
-    assert "Agent is frozen by Elydora" in guard_result.stderr
-
-    post_payload = json.dumps(
-        {
-            "hook_event_name": "PostToolUse",
-            "conversation_id": "conversation-1",
-            "workspace_roots": [str(fixture.workspace_dir)],
-            "tool_name": "launch-process",
-            "tool_input": {"command": "echo test"},
-            "tool_output": "test",
-            "is_mcp_tool": False,
-        },
-        separators=(",", ":"),
-    )
-    audit = managed_handler(settings, "PostToolUse", fixture.audit_wrapper_path)
-    audit_result = run_command(audit["command"], fixture.home_dir, post_payload)
-    assert audit_result.returncode == 0
-    assert capture_path.read_text(encoding="utf-8") == post_payload
-
-
-def test_status_requires_complete_pair_core_runtimes_and_wrappers(
-    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
-) -> None:
-    fixture = prepare_fixture(monkeypatch, tmp_path)
-    fixture.plugin.install(fixture.config)
-    assert fixture.plugin.status()["installed"] is True
-
-    fixture.guard_wrapper_path.unlink()
-    status = fixture.plugin.status()
-    assert status["installed"] is False
-    assert "wrappers missing" in status["details"]
-
-    fixture.plugin.install(fixture.config)
-    fixture.hook_path.unlink()
-    assert fixture.plugin.status()["installed"] is False
-
-    fixture.plugin.install(fixture.config)
-    settings = json.loads(fixture.config_path.read_text(encoding="utf-8"))
-    del settings["hooks"]["PostToolUse"]
-    fixture.config_path.write_text(json.dumps(settings), encoding="utf-8")
-    assert fixture.plugin.status()["installed"] is False
+    for event, wrapper_name in (
+        ("PreToolUse", contract.GUARD_WRAPPER),
+        ("PostToolUse", contract.AUDIT_WRAPPER),
+    ):
+        settings["hooks"][event].append(
+            {
+                "hooks": [
+                    {
+                        "type": "command",
+                        "command": contract.build_command(
+                            str(fixture.agent_dir.parent / "agent-old" / wrapper_name)
+                        ),
+                        "timeout": 10_000,
+                    }
+                ]
+            }
+        )
+    fixture.config_path.write_text(json.dumps(settings, indent=2), encoding="utf-8")
+    fixture.install()
+    current = fixture.settings()
+    assert "agent-old" not in json.dumps(current)
+    assert current["hooks"]["PreToolUse"][0] == {
+        "hooks": [],
+        "label": "keep empty group",
+    }
+    assert len(current["hooks"]["PreToolUse"]) == 2
+    assert len(current["hooks"]["PostToolUse"]) == 1
 
 
 def test_uninstall_removes_exact_ownership_and_preserves_user_groups(
@@ -290,16 +164,10 @@ def test_uninstall_removes_exact_ownership_and_preserves_user_groups(
         tmp_path,
         existing_settings={"owner": "user", "hooks": {"Notification": []}},
     )
-    fixture.plugin.install(fixture.config)
-    settings = json.loads(fixture.config_path.read_text(encoding="utf-8"))
-    settings["hooks"]["PreToolUse"].insert(
-        0, {"hooks": [], "label": "keep empty group"}
-    )
-    settings["hooks"]["PreToolUse"][1]["hooks"].append(
-        {
-            "type": "command",
-            "command": "user-command",
-        }
+    fixture.install()
+    settings = fixture.settings()
+    settings["hooks"]["PreToolUse"][0]["hooks"].append(
+        {"type": "command", "command": "user-command"}
     )
     settings["hooks"]["PreToolUse"].append(
         {
@@ -334,19 +202,11 @@ def test_uninstall_removes_exact_ownership_and_preserves_user_groups(
     fixture.config_path.write_text(json.dumps(settings, indent=2), encoding="utf-8")
     uninstall_id = "AGENT-1" if os.name == "nt" else AGENT_ID
     fixture.plugin.uninstall(uninstall_id)
-    remaining = json.loads(fixture.config_path.read_text(encoding="utf-8"))
+    remaining = fixture.settings()
     assert remaining["owner"] == "user"
     assert remaining["hooks"]["Notification"] == []
-    assert len(remaining["hooks"]["PreToolUse"]) == 4
-    assert remaining["hooks"]["PreToolUse"][0] == {
-        "hooks": [],
-        "label": "keep empty group",
-    }
-    assert remaining["hooks"]["PreToolUse"][1]["hooks"] == [
-        {
-            "type": "command",
-            "command": "user-command",
-        }
+    assert remaining["hooks"]["PreToolUse"][0]["hooks"] == [
+        {"type": "command", "command": "user-command"}
     ]
     raw = fixture.config_path.read_text(encoding="utf-8")
     assert "augment-guard" in raw and "backup" in raw
@@ -354,51 +214,81 @@ def test_uninstall_removes_exact_ownership_and_preserves_user_groups(
     assert "PostToolUse" not in remaining["hooks"]
 
 
-def test_install_replaces_stale_handlers_and_preserves_empty_groups(
-    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
-) -> None:
-    fixture = prepare_fixture(monkeypatch, tmp_path)
-    fixture.plugin.install(fixture.config)
-    settings = json.loads(fixture.config_path.read_text(encoding="utf-8"))
-    settings["hooks"]["PreToolUse"].insert(
-        0, {"hooks": [], "label": "keep empty group"}
-    )
-    for event, wrapper_name in (
-        ("PreToolUse", contract.GUARD_WRAPPER),
-        ("PostToolUse", contract.AUDIT_WRAPPER),
-    ):
-        settings["hooks"][event].append(
-            {
-                "hooks": [
-                    {
-                        "type": "command",
-                        "command": contract.build_command(
-                            str(fixture.agent_dir.parent / "agent-old" / wrapper_name)
-                        ),
-                        "timeout": 10_000,
-                    }
-                ]
-            }
-        )
-    fixture.config_path.write_text(json.dumps(settings, indent=2), encoding="utf-8")
-    fixture.plugin.install(fixture.config)
-    current = json.loads(fixture.config_path.read_text(encoding="utf-8"))
-    assert "agent-old" not in json.dumps(current)
-    assert current["hooks"]["PreToolUse"][0] == {
-        "hooks": [],
-        "label": "keep empty group",
-    }
-    assert len(current["hooks"]["PreToolUse"]) == 2
-    assert len(current["hooks"]["PostToolUse"]) == 1
-
-
 def test_uninstall_removes_settings_owned_entirely_by_elydora(
     monkeypatch: pytest.MonkeyPatch, tmp_path: Path
 ) -> None:
     fixture = prepare_fixture(monkeypatch, tmp_path)
-    fixture.plugin.install(fixture.config)
+    fixture.install()
     fixture.plugin.uninstall(AGENT_ID)
-    assert fixture.config_path.exists() is False
+    assert not fixture.config_path.exists()
+
+
+def test_cli_install_status_and_uninstall_end_to_end(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    fixture = prepare_fixture(monkeypatch, tmp_path)
+    key_path = tmp_path / "install-private.key"
+    token_path = tmp_path / "install-token.txt"
+    write_text(key_path, VALID_PRIVATE_KEY + "\n")
+    write_text(token_path, "token-1\n")
+    environment = {
+        **os.environ,
+        "HOME": str(fixture.home_dir),
+        "USERPROFILE": str(fixture.home_dir),
+    }
+    root = Path(__file__).parents[1]
+    base = [sys.executable, "-m", "elydora.cli"]
+    install = subprocess.run(  # nosec B603
+        [
+            *base,
+            "install",
+            "--agent",
+            "augment",
+            "--org_id",
+            "org-1",
+            "--agent_id",
+            AGENT_ID,
+            "--private_key_file",
+            str(key_path),
+            "--token_file",
+            str(token_path),
+            "--kid",
+            "key-1",
+            "--base_url",
+            "http://127.0.0.1:9",
+        ],
+        capture_output=True,
+        check=False,
+        cwd=root,
+        env=environment,
+        text=True,
+    )
+    assert install.returncode == 0, install.stderr
+    assert "PreToolUse and PostToolUse hooks installed" in install.stdout
+
+    status = subprocess.run(  # nosec B603
+        [*base, "status"],
+        capture_output=True,
+        check=False,
+        cwd=root,
+        env=environment,
+        text=True,
+    )
+    assert status.returncode == 0, status.stderr
+    assert "Augment Code CLI" in status.stdout
+    assert "[installed]" in status.stdout
+
+    uninstall = subprocess.run(  # nosec B603
+        [*base, "uninstall", "--agent", "augment", "--agent_id", AGENT_ID],
+        capture_output=True,
+        check=False,
+        cwd=root,
+        env=environment,
+        text=True,
+    )
+    assert uninstall.returncode == 0, uninstall.stderr
+    assert not fixture.config_path.exists()
+    assert not fixture.agent_dir.exists()
 
 
 @pytest.mark.parametrize(
@@ -407,6 +297,7 @@ def test_uninstall_removes_settings_owned_entirely_by_elydora(
         "{ malformed",
         "null",
         "[]",
+        '{"hooks":{},"hooks":{}}',
         {"hooks": None},
         {"hooks": {"UnknownEvent": []}},
         {"hooks": {"PreToolUse": None}},
@@ -443,56 +334,20 @@ def test_uninstall_removes_settings_owned_entirely_by_elydora(
         },
     ],
 )
-def test_install_rejects_malformed_settings_before_writes(
-    monkeypatch: pytest.MonkeyPatch,
-    tmp_path: Path,
-    existing: object,
+def test_install_rejects_invalid_settings_before_writes(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path, existing: object
 ) -> None:
     fixture = prepare_fixture(monkeypatch, tmp_path, existing_settings=existing)
     original = fixture.config_path.read_text(encoding="utf-8")
-
-    with pytest.raises(ValueError):
-        fixture.plugin.install(fixture.config)
-
+    with pytest.raises((FileNotFoundError, ValueError)):
+        fixture.install()
     assert fixture.config_path.read_text(encoding="utf-8") == original
-    assert fixture.hook_path.exists() is False
-    assert fixture.runtime_config_path.exists() is False
-    assert fixture.private_key_path.exists() is False
-    assert fixture.guard_wrapper_path.exists() is False
-    assert fixture.audit_wrapper_path.exists() is False
-
-
-def test_install_rejects_missing_guard_before_creating_files(
-    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
-) -> None:
-    fixture = prepare_fixture(monkeypatch, tmp_path, create_guard=False)
-
-    with pytest.raises(FileNotFoundError, match="guard runtime is missing"):
-        fixture.plugin.install(fixture.config)
-
-    assert fixture.config_path.exists() is False
-    assert fixture.hook_path.exists() is False
-    assert fixture.runtime_config_path.exists() is False
-    assert fixture.private_key_path.exists() is False
-    assert fixture.guard_wrapper_path.exists() is False
-
-
-def test_status_surfaces_malformed_referenced_runtime_metadata(
-    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
-) -> None:
-    fixture = prepare_fixture(monkeypatch, tmp_path)
-    fixture.plugin.install(fixture.config)
-    fixture.runtime_config_path.write_text("{ malformed", encoding="utf-8")
-
-    with pytest.raises(ValueError, match="parse Elydora runtime config"):
-        fixture.plugin.status()
-
-
-def test_atomic_writes_leave_no_temporary_files(
-    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
-) -> None:
-    fixture = prepare_fixture(monkeypatch, tmp_path)
-    fixture.plugin.install(fixture.config)
-
-    for directory in (fixture.agent_dir, fixture.config_path.parent):
-        assert all(path.suffix != ".tmp" for path in directory.iterdir())
+    for path in (
+        fixture.guard_path,
+        fixture.hook_path,
+        fixture.runtime_config_path,
+        fixture.private_key_path,
+        fixture.guard_wrapper_path,
+        fixture.audit_wrapper_path,
+    ):
+        assert not path.exists()

tests/test_augment_runtime.py

@@ -0,0 +1,194 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+
+from augment_support import (
+    ElydoraApiHandler,
+    managed_handler,
+    prepare_fixture,
+    run_handler,
+    server_base_url,
+    start_api_server,
+)
+
+
+def encoded(value: object) -> bytes:
+    return json.dumps(value, separators=(",", ":")).encode()
+
+
+def official_payload(event: str, **overrides: object) -> dict[str, object]:
+    value: dict[str, object] = {
+        "hook_event_name": event,
+        "conversation_id": "conversation-1",
+        "workspace_roots": ["/workspace"],
+        "tool_name": "launch-process",
+        "tool_input": {"command": "pytest", "nested": {"preserve": True}},
+        "is_mcp_tool": False,
+        "conversation_data": [{"role": "user", "content": "preserve this"}],
+        "mcp_metadata": {"server": "local", "transport": "stdio"},
+        "user_context": {"account": "user-1"},
+        "future_field": {"survives": ["exactly", 2]},
+    }
+    value.update(overrides)
+    return value
+
+
+@pytest.mark.parametrize("status", ["frozen", "revoked"])
+def test_guard_propagates_official_blocking_exit_code(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+    status: str,
+) -> None:
+    server = start_api_server(status=status)
+    try:
+        fixture = prepare_fixture(
+            monkeypatch, tmp_path, base_url=server_base_url(server)
+        )
+        fixture.install()
+        handler = managed_handler(
+            fixture.settings(), "PreToolUse", fixture.guard_wrapper_path
+        )
+        result = run_handler(handler, encoded(official_payload("PreToolUse")), fixture)
+    finally:
+        server.shutdown()
+        server.server_close()
+
+    assert result.returncode == 2
+    assert result.stdout == b""
+    assert status.encode() in result.stderr.lower()
+    assert b"Tool execution blocked" in result.stderr
+
+
+def test_audit_preserves_complete_native_hook_payload(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    server = start_api_server()
+    payload = official_payload(
+        "PostToolUse",
+        tool_output={"stdout": "passed", "stderr": "", "exit_code": 0},
+    )
+    try:
+        fixture = prepare_fixture(
+            monkeypatch, tmp_path, base_url=server_base_url(server)
+        )
+        fixture.install()
+        handler = managed_handler(
+            fixture.settings(), "PostToolUse", fixture.audit_wrapper_path
+        )
+        result = run_handler(handler, encoded(payload), fixture)
+    finally:
+        server.shutdown()
+        server.server_close()
+
+    assert result.returncode == 0
+    request = next(
+        item for item in ElydoraApiHandler.requests if item["method"] == "POST"
+    )
+    assert request["json"]["payload"] == payload
+    assert request["authorization"] == "Bearer token-1"
+
+
+def test_status_requires_exact_runtime_identity_key_scripts_and_wrappers(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    fixture = prepare_fixture(monkeypatch, tmp_path)
+    fixture.install()
+    assert fixture.plugin.status()["installed"] is True
+
+    fixture.guard_wrapper_path.unlink()
+    assert fixture.plugin.status()["installed"] is False
+    fixture.install()
+
+    fixture.hook_path.unlink()
+    assert fixture.plugin.status()["installed"] is False
+    fixture.install()
+
+    fixture.audit_wrapper_path.write_text("tampered wrapper\n", encoding="utf-8")
+    assert fixture.plugin.status()["installed"] is False
+    fixture.install()
+
+    fixture.private_key_path.write_text("invalid", encoding="utf-8")
+    with pytest.raises(ValueError, match="private key.*canonical 32-byte"):
+        fixture.plugin.status()
+
+
+@pytest.mark.parametrize(
+    ("source", "pattern"),
+    [
+        ("{ malformed", "parse Elydora runtime config"),
+        ('{"agent_name":"augment","agent_name":"augment"}', "duplicate field"),
+        (
+            json.dumps(
+                {
+                    "org_id": "org-1",
+                    "agent_id": "other-agent",
+                    "kid": "key-1",
+                    "base_url": "https://api.elydora.com",
+                    "agent_name": "augment",
+                }
+            ),
+            "identity does not match",
+        ),
+        (
+            json.dumps(
+                {
+                    "org_id": "org-1",
+                    "agent_id": "agent-1",
+                    "kid": "key-1",
+                    "base_url": "https://api.elydora.com",
+                    "agent_name": "augment",
+                    "hidden": True,
+                }
+            ),
+            "unsupported field",
+        ),
+    ],
+)
+def test_status_surfaces_invalid_runtime_metadata(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+    source: str,
+    pattern: str,
+) -> None:
+    fixture = prepare_fixture(monkeypatch, tmp_path)
+    fixture.install()
+    fixture.runtime_config_path.write_text(source, encoding="utf-8")
+    with pytest.raises(ValueError, match=pattern):
+        fixture.plugin.status()
+
+
+def test_status_ignores_incomplete_managed_hook_pairs(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    fixture = prepare_fixture(monkeypatch, tmp_path)
+    fixture.install()
+    settings = fixture.settings()
+    del settings["hooks"]["PostToolUse"]
+    fixture.config_path.write_text(json.dumps(settings), encoding="utf-8")
+    status = fixture.plugin.status()
+    assert status["installed"] is False
+    assert status["details"] == "Not installed"
+
+
+def test_runtime_failures_remain_observable_and_fail_open(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    fixture = prepare_fixture(monkeypatch, tmp_path)
+    fixture.install()
+    settings = fixture.settings()
+    guard = managed_handler(settings, "PreToolUse", fixture.guard_wrapper_path)
+    audit = managed_handler(settings, "PostToolUse", fixture.audit_wrapper_path)
+    guard_result = run_handler(guard, encoded(official_payload("PreToolUse")), fixture)
+    audit_result = run_handler(audit, encoded(official_payload("PostToolUse")), fixture)
+    malformed = run_handler(audit, b"{ malformed", fixture)
+
+    assert guard_result.returncode == 0
+    assert b"Failed to resolve agent status" in guard_result.stderr
+    assert audit_result.returncode == 0
+    assert malformed.returncode == 0
+    log = (fixture.agent_dir / "error.log").read_text(encoding="utf-8")
+    assert "invalid JSON" in log
+    assert "refused" in log.lower() or "urlopen" in log.lower()

tests/test_augment_transaction.py

@@ -0,0 +1,259 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+import subprocess  # nosec B404
+import sys
+
+import pytest
+
+from augment_support import (
+    AGENT_ID,
+    VALID_PRIVATE_KEY,
+    prepare_fixture,
+    symlink_or_skip,
+    write_json,
+    write_text,
+)
+from elydora.plugins import _transaction, augment, augment_installation
+from elydora.plugins.augment_contract import render_augment_document
+from elydora.plugins.augment_io import read_augment_document
+
+
+RUNTIME_NAMES = (
+    "guard.py",
+    "config.json",
+    "private.key",
+    "hook.py",
+    "augment-guard.cmd" if os.name == "nt" else "augment-guard.sh",
+    "augment-hook.cmd" if os.name == "nt" else "augment-hook.sh",
+)
+
+
+def prepare_installation(fixture: object) -> list[_transaction.FileChange]:
+    document = read_augment_document()
+    paths = augment_installation.preflight_augment_installation(
+        fixture.config, document
+    )
+    rendered = render_augment_document(
+        document, augment._installed_hooks(document.hooks, paths)
+    )
+    return augment_installation.prepare_augment_installation(
+        fixture.config, paths, rendered
+    )
+
+
+def assert_no_transaction_files(root: Path) -> None:
+    assert not list(root.rglob("*.tmp"))
+    assert not list(root.rglob("*.rollback"))
+
+
+def test_transaction_rolls_back_all_seven_files(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    original = '{"telemetryEnabled":true}\n'
+    fixture = prepare_fixture(monkeypatch, tmp_path, existing_settings=original)
+    real_replace = _transaction.os.replace
+    failed = False
+
+    def fail_settings_once(source: str, destination: str) -> None:
+        nonlocal failed
+        if os.path.abspath(destination) == str(fixture.config_path) and not failed:
+            failed = True
+            raise OSError("injected Auggie settings failure")
+        real_replace(source, destination)
+
+    monkeypatch.setattr(_transaction.os, "replace", fail_settings_once)
+    with pytest.raises(OSError, match="injected Auggie settings failure"):
+        fixture.install()
+
+    assert fixture.config_path.read_text(encoding="utf-8") == original
+    for name in RUNTIME_NAMES:
+        assert not (fixture.agent_dir / name).exists()
+    assert_no_transaction_files(fixture.home_dir)
+
+
+def test_concurrent_settings_change_is_detected_before_runtime_commits(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    fixture = prepare_fixture(
+        monkeypatch, tmp_path, existing_settings={"telemetryEnabled": True}
+    )
+    changes = prepare_installation(fixture)
+    concurrent = '{"telemetryEnabled":false,"hooks":{"Notification":[]}}\n'
+    fixture.config_path.write_text(concurrent, encoding="utf-8")
+
+    with pytest.raises(OSError, match="changed during installation"):
+        augment_installation.commit_augment_installation(changes)
+
+    assert fixture.config_path.read_text(encoding="utf-8") == concurrent
+    for name in RUNTIME_NAMES:
+        assert not (fixture.agent_dir / name).exists()
+    assert_no_transaction_files(fixture.home_dir)
+
+
+def test_stale_settings_are_rejected_before_staging(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    fixture = prepare_fixture(monkeypatch, tmp_path)
+    document = read_augment_document()
+    paths = augment_installation.preflight_augment_installation(
+        fixture.config, document
+    )
+    rendered = render_augment_document(
+        document, augment._installed_hooks(document.hooks, paths)
+    )
+    write_text(fixture.config_path, '{"hooks":{"Notification":[]}}\n')
+    with pytest.raises(OSError, match="changed before staging"):
+        augment_installation.prepare_augment_installation(
+            fixture.config, paths, rendered
+        )
+    assert not fixture.agent_dir.exists()
+    assert_no_transaction_files(fixture.home_dir)
+
+
+@pytest.mark.parametrize(
+    "runtime_name",
+    [
+        "private.key",
+        "guard.py",
+        "hook.py",
+        "augment-guard.cmd" if os.name == "nt" else "augment-guard.sh",
+        "augment-hook.cmd" if os.name == "nt" else "augment-hook.sh",
+        "chain-state.json",
+        "status-cache.json",
+        "error.log",
+    ],
+)
+def test_orphan_runtime_artifacts_fail_before_settings_writes(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+    runtime_name: str,
+) -> None:
+    fixture = prepare_fixture(monkeypatch, tmp_path)
+    artifact = fixture.agent_dir / runtime_name
+    write_text(artifact, "orphan\n")
+    with pytest.raises(ValueError, match="identity cannot be verified"):
+        fixture.install()
+    assert artifact.read_text(encoding="utf-8") == "orphan\n"
+    assert not fixture.config_path.exists()
+
+
+def test_mismatched_runtime_identity_fails_before_writes(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    fixture = prepare_fixture(monkeypatch, tmp_path)
+    write_json(
+        fixture.runtime_config_path,
+        {
+            "agent_id": "another-agent",
+            "agent_name": "augment",
+        },
+    )
+    original = fixture.runtime_config_path.read_text(encoding="utf-8")
+    with pytest.raises(ValueError, match="identity does not match"):
+        fixture.install()
+    assert fixture.runtime_config_path.read_text(encoding="utf-8") == original
+    assert not fixture.config_path.exists()
+
+
+@pytest.mark.parametrize("kind", ["configuration", "settings", "runtime", "wrapper"])
+def test_linked_settings_runtime_and_wrapper_paths_are_rejected(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+    kind: str,
+) -> None:
+    fixture = prepare_fixture(monkeypatch, tmp_path)
+    target = tmp_path / f"{kind}-target"
+    if kind == "settings":
+        write_text(target, "{}\n")
+        fixture.config_path.parent.mkdir(parents=True)
+        symlink_or_skip(target, fixture.config_path)
+    elif kind == "configuration":
+        target.mkdir()
+        fixture.config_path.parent.parent.mkdir(parents=True)
+        symlink_or_skip(target, fixture.config_path.parent, directory=True)
+    elif kind == "runtime":
+        target.mkdir()
+        fixture.agent_dir.parent.parent.mkdir(parents=True)
+        symlink_or_skip(target, fixture.agent_dir.parent, directory=True)
+    else:
+        fixture.install()
+        write_text(target, "external wrapper\n")
+        fixture.guard_wrapper_path.unlink()
+        symlink_or_skip(target, fixture.guard_wrapper_path)
+
+    with pytest.raises(OSError, match="physical (file|directory)"):
+        fixture.install()
+
+
+@pytest.mark.parametrize(
+    ("field", "value", "pattern"),
+    [
+        ("agent_name", "codex", "requires agent_name augment"),
+        ("agent_id", "../escape", "Invalid agent ID"),
+        ("private_key", "invalid", "canonical 32-byte"),
+        ("token", "", "non-empty string"),
+        ("base_url", "https://api.elydora.com?q=1", "query parameters"),
+        ("guard_script_path", "outside", "managed agent directory"),
+    ],
+)
+def test_install_validates_runtime_inputs_before_writes(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+    field: str,
+    value: str,
+    pattern: str,
+) -> None:
+    fixture = prepare_fixture(monkeypatch, tmp_path)
+    fixture.config[field] = value
+    with pytest.raises(ValueError, match=pattern):
+        fixture.install()
+    assert not fixture.config_path.exists()
+    assert not fixture.agent_dir.exists()
+
+
+def test_installation_leaves_no_transaction_artifacts(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    fixture = prepare_fixture(monkeypatch, tmp_path)
+    fixture.install()
+    assert_no_transaction_files(fixture.home_dir)
+
+
+def test_cli_preflight_preserves_malformed_settings(tmp_path: Path) -> None:
+    home_dir = tmp_path / "cli-home"
+    settings_path = home_dir / ".augment" / "settings.json"
+    key_path = tmp_path / "private.key"
+    write_text(settings_path, "{ malformed")
+    write_text(key_path, VALID_PRIVATE_KEY)
+    environment = {**os.environ, "HOME": str(home_dir), "USERPROFILE": str(home_dir)}
+    result = subprocess.run(  # nosec B603
+        [
+            sys.executable,
+            "-m",
+            "elydora.cli",
+            "install",
+            "--agent",
+            "augment",
+            "--org_id",
+            "org-1",
+            "--agent_id",
+            AGENT_ID,
+            "--private_key_file",
+            str(key_path),
+            "--kid",
+            "key-1",
+            "--base_url",
+            "https://api.elydora.com",
+        ],
+        capture_output=True,
+        check=False,
+        cwd=Path(__file__).parents[1],
+        env=environment,
+        text=True,
+    )
+    assert result.returncode == 1
+    assert "parse Auggie user settings" in result.stderr
+    assert settings_path.read_text(encoding="utf-8") == "{ malformed"
+    assert not (home_dir / ".elydora").exists()