agentmetry 0.9.8__tar.gz → 0.9.9__tar.gz

{agentmetry-0.9.8 → agentmetry-0.9.9}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.5
 Name: agentmetry
-Version: 0.9.8
-Summary: Local-first flight recorder for AI coding agents: hash-chained audit trail, MITRE-mapped sequence detection, DLP
+Version: 0.9.9
+Summary: Local-first endpoint sensor for AI coding agents: hash-chained audit trail, MITRE-mapped sequence detection, DLP
 Project-URL: Homepage, https://agentmetry.ai
 Project-URL: Source, https://github.com/blitzcrieg1/agentmetry
 Project-URL: Issues, https://github.com/blitzcrieg1/agentmetry/issues
@@ -37,12 +37,12 @@ Provides-Extra: dev
 Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
 Requires-Dist: pytest-cov>=6.0; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
-Requires-Dist: ruff==0.16.10; extra == 'dev'
+Requires-Dist: ruff==0.17.1; extra == 'dev'
 Description-Content-Type: text/markdown
 
 # Agentmetry
 
-A local-first flight recorder for AI coding agents.
+A local-first endpoint sensor for AI coding agents.
 
 Agentmetry hooks the tool lifecycle of Claude Code, Cursor, Codex and Antigravity,
 writes every tool call, approval and denial to a hash-chained JSONL trail on your

{agentmetry-0.9.8 → agentmetry-0.9.9}/README.md

@@ -1,6 +1,6 @@
 # Agentmetry
 
-A local-first flight recorder for AI coding agents.
+A local-first endpoint sensor for AI coding agents.
 
 Agentmetry hooks the tool lifecycle of Claude Code, Cursor, Codex and Antigravity,
 writes every tool call, approval and denial to a hash-chained JSONL trail on your

{agentmetry-0.9.8 → agentmetry-0.9.9}/agentmetry/api/routes/audit.py

@@ -105,7 +105,7 @@ class ExternalIngestBody(BaseModel):
     )
     event_type: str = Field(
         ...,
-        description="session_start | session_end | tool_called | tool_denied | tool_failed | approval_request | approval_response | mcp_schema",
+        description="session_start | session_end | tool_called | tool_denied | tool_failed | approval_request | approval_response | mcp_schema | hook_remediation",
     )
     correlation_id: str = ""
     session_id: str = ""

{agentmetry-0.9.8 → agentmetry-0.9.9}/agentmetry/cli/__init__.py

@@ -48,6 +48,70 @@ def _api_base_url(port: int) -> str:
     return os.environ.get("AGENTMETRY_URL", "").strip().rstrip("/") or _base_url(port)
 
 
+def _add_dir_flags(parser: argparse.ArgumentParser) -> None:
+    """The path split. Omit the flags and nothing moves.
+
+    `SUPPRESS`, so the same flag on `agentmetry` and on the subcommand do not
+    overwrite each other with a default of None.
+    """
+    parser.add_argument(
+        "--data-dir", default=argparse.SUPPRESS,
+        help="trail, spool, token and logs (env AGENTMETRY_DATA_DIR)",
+    )
+    parser.add_argument(
+        "--user-profile-dir", default=argparse.SUPPRESS,
+        help="the developer home whose IDE configs to install into and check "
+        "(env AGENTMETRY_USER_PROFILE_DIR); for a recorder run as root or LocalSystem",
+    )
+    parser.add_argument(
+        "--policy-dir", default=argparse.SUPPRESS,
+        help="an extra managed policy location, checked like the platform one "
+        "(env AGENTMETRY_POLICY_DIR)",
+    )
+
+
+def _apply_dir_flags(args: argparse.Namespace) -> None:
+    """Export the path flags before a command reads data_dir() or the profile.
+
+    Exported, not passed: `start` spawns `serve`, and the hook commands it
+    writes run in other processes, all of which read the environment.
+    """
+    global _DATA_DIR, _PID_FILE
+    if getattr(args, "user_profile_dir", None):
+        os.environ["AGENTMETRY_USER_PROFILE_DIR"] = args.user_profile_dir
+    if getattr(args, "policy_dir", None):
+        os.environ["AGENTMETRY_POLICY_DIR"] = args.policy_dir
+    if getattr(args, "data_dir", None):
+        os.environ["AGENTMETRY_DATA_DIR"] = args.data_dir
+        # Only when the flag was given: a caller that already pointed these at
+        # a temp tree must not have them recomputed under it.
+        _DATA_DIR = data_dir()
+        _PID_FILE = _DATA_DIR / "agentmetry.pid"
+
+
+def _apply_managed_policy(args: argparse.Namespace) -> None:
+    """Locks over flags and environment, for this process and everything it starts.
+
+    After `_apply_dir_flags`, so `--data-dir` cannot move a trail a fleet
+    locked. Says so when it overrides a flag: a silently ignored flag reads as
+    a bug.
+    """
+    global _DATA_DIR, _PID_FILE
+    from agentmetry.core import managed_policy
+
+    try:
+        policy = managed_policy.apply_locks()
+    except Exception as exc:
+        print(f"Managed policy was not applied: {exc}", file=sys.stderr)
+        return
+    if "data_dir" not in policy.locked:
+        return
+    if getattr(args, "data_dir", None):
+        print("--data-dir ignored: managed policy locks data_dir.", file=sys.stderr)
+    _DATA_DIR = data_dir()
+    _PID_FILE = _DATA_DIR / "agentmetry.pid"
+
+
 def _api_headers() -> dict[str, str]:
     from agentmetry.core.api_token import client_token
 
@@ -636,11 +700,12 @@ def _hooks_status() -> int:
     """
     from agentmetry.core.diagnostics import hook_coverage
 
-    if hook_coverage.is_service_profile():
+    if hook_coverage.profile_blind():
         print(
             "UNDETERMINABLE: running under a service profile. Hook configuration "
             "lives in each developer's profile and none is visible from here. "
-            "Run this in the user's context.",
+            "Run this in the user's context, or name the developer's home with "
+            "--user-profile-dir.",
             file=sys.stderr,
         )
         return 2
@@ -1414,10 +1479,10 @@ def cmd_demo(args: argparse.Namespace) -> int:
 def cmd_doctor(args: argparse.Namespace) -> int:
     """SIEM preflight: manifests, trail chain, orchestrator health, hooks."""
     sys.path.insert(0, str(_ORCH_ROOT))
-    from agentmetry.core.diagnostics.doctor import format_report, run_doctor
+    from agentmetry.core.diagnostics.doctor import print_report, run_doctor
 
     report = run_doctor(fix_drivers=getattr(args, "fix", False))
-    print("Agentmetry doctor\n" + format_report(report))
+    print_report(report, as_json=getattr(args, "json", False))
     return report.exit_code
 
 
@@ -1451,6 +1516,7 @@ def main(argv: list[str] | None = None) -> int:
         prog="agentmetry",
         description="Agentmetry local ops. New here? Start with `agentmetry demo`.",
     )
+    _add_dir_flags(parser)
     parser.add_argument("--port", type=int, default=8000)
     sub = parser.add_subparsers(dest="command", required=True)
     # First, so it heads the help: it is the one command that needs nothing set up.
@@ -1465,6 +1531,7 @@ def main(argv: list[str] | None = None) -> int:
 
     sub.add_parser("stop", help="stop the orchestrator")
     start = sub.add_parser("start", help="start the orchestrator (detached)")
+    _add_dir_flags(start)
     start.add_argument(
         "--host",
         default="127.0.0.1",
@@ -1474,12 +1541,14 @@ def main(argv: list[str] | None = None) -> int:
         "serve",
         help="run the orchestrator in the foreground (what autostart registers)",
     )
+    _add_dir_flags(serve)
     serve.add_argument("--host", default="127.0.0.1")
     serve.add_argument("--port", type=int, default=8000)
     hooks = sub.add_parser(
         "hooks",
         help="install IDE hook configs for the agents on this machine",
     )
+    _add_dir_flags(hooks)
     hooks.add_argument(
         "action",
         choices=("install", "status"),
@@ -1681,6 +1750,13 @@ def main(argv: list[str] | None = None) -> int:
     doctor = sub.add_parser(
         "doctor", help="SIEM preflight (manifests, trail chain, health, hooks)"
     )
+    _add_dir_flags(doctor)
+    doctor.add_argument(
+        "--json",
+        action="store_true",
+        help="the report as JSON, for a deployment script: exit_code, "
+        "orchestrator_reachable, hooks, policy and findings",
+    )
     doctor.add_argument(
         "--fix",
         action="store_true",
@@ -1708,6 +1784,8 @@ def main(argv: list[str] | None = None) -> int:
     replay.add_argument("--trail", default="", help="trail to read (default: the configured trail)")
 
     args = parser.parse_args(argv)
+    _apply_dir_flags(args)
+    _apply_managed_policy(args)
     handlers = {
         "demo": cmd_demo,
         "start": cmd_start,

{agentmetry-0.9.8 → agentmetry-0.9.9}/agentmetry/core/audit/external.py

@@ -38,8 +38,20 @@ _ACTION_MAP = {
     "tool_failed": ("tool_called", "error"),
     "approval_request": ("approval_request", "pending"),
     "approval_response": ("approval_response", "success"),
+    # A deployment tool (an Intune remediation, a LaunchAgent) reinstalled
+    # hooks. That changes this machine's configuration; it is not a tool call.
+    # Unmapped it was stored as `tool_called`, which tool-sequence rules count.
+    "hook_remediation": ("config_change", "success"),
 }
 
+#: The only payload fields a remediation notice keeps. Anything session- or
+#: tool-shaped a client attached is dropped: it would join the notice to an
+#: agent's session, or give a detection a tool to read.
+_REMEDIATION_FIELDS = frozenset({
+    "event_type", "source_app", "outcome", "reason", "timestamp_utc", "adapter",
+    "triggered_by", "initiator", "operator",
+})
+
 
 def _utc_now() -> str:
     return datetime.now(timezone.utc).isoformat()
@@ -82,8 +94,14 @@ def build_external_canonical(payload: dict[str, Any]) -> dict[str, Any]:
     source_app, claimed_app = _resolve_source_app(payload.get("source_app"))
 
     event_type = str(payload.get("event_type") or "tool_called")
+    if event_type == "hook_remediation":
+        payload = {k: v for k, v in payload.items() if k in _REMEDIATION_FIELDS}
     action_type, default_outcome = _ACTION_MAP.get(event_type, ("tool_called", "success"))
     outcome = str(payload.get("outcome") or default_outcome)
+    if event_type == "hook_remediation" and outcome not in ("success", "error"):
+        # Anything else is not a confirmed success, and a fleet alerting on
+        # failed remediations must not have one hidden by a spelling.
+        outcome = "error"
     reason = str(payload.get("reason") or "")
 
     correlation_id = str(payload.get("correlation_id") or payload.get("thread_id") or "")

{agentmetry-0.9.8 → agentmetry-0.9.9}/agentmetry/core/audit/heartbeat.py

@@ -98,7 +98,31 @@ def _hook_facts() -> dict[str, Any]:
         "hook_coverage": states,
         "hooks_uncovered": hook_coverage.uncovered(states),
         "hooks_unverified": hook_coverage.unverified(states),
-        "hook_profile": "service" if hook_coverage.is_service_profile() else "user",
+        "hook_profile": hook_coverage.attestation_profile(),
+    }
+
+
+def _policy_facts() -> dict[str, Any]:
+    """What a managed policy locks here, and which managed sources were refused.
+
+    Read from disk every beat, so a policy an admin broke after the recorder
+    started shows up before the next restart would have applied it. A refused
+    source means the fleet's locks may not be in force on this machine, which
+    is a fleet-level fact to alert on, not a log line on one laptop.
+
+    Locations only, never the reason: a reason can name the SID of the user
+    who could edit the file, and the beat attests configuration, not people.
+    `doctor` gives the reason on the machine itself.
+    """
+    from agentmetry.core import managed_policy
+
+    try:
+        policy = managed_policy.load_policy()
+    except Exception as exc:
+        return {"policy_locked": [], "policy_rejected": [f"unreadable ({type(exc).__name__})"]}
+    return {
+        "policy_locked": sorted(policy.locked),
+        "policy_rejected": [s.location for s in policy.rejected],
     }
 
 
@@ -198,6 +222,7 @@ def attestation(root: tuple[str, int] | None = None) -> dict[str, Any]:
     schema_digest, schema_servers = _mcp_schema_facts()
     return {
         **_hook_facts(),
+        **_policy_facts(),
         "spool_depth": _spool_depth(),
         "trail_head_seq": _trail_head(),
         "trail_merkle_root": merkle,
@@ -226,7 +251,8 @@ def build_heartbeat_event(now_utc: str, root: tuple[str, int] | None = None) ->
     # Code degrade forever, which is how a fleet learns to ignore the signal.
     # A service profile does set it: from there no developer's configuration is
     # visible at all, so a confident green would be the worst of the answers.
-    degraded = bool(uncovered) or facts["spool_depth"] > 0 or service_profile
+    rejected = facts["policy_rejected"]
+    degraded = bool(uncovered) or facts["spool_depth"] > 0 or service_profile or bool(rejected)
 
     reason = "recorder attesting"
     if service_profile:
@@ -234,6 +260,8 @@ def build_heartbeat_event(now_utc: str, root: tuple[str, int] | None = None) ->
             "recorder attesting from a service profile; no developer hook "
             "configuration is visible from here, so coverage is unknown"
         )
+    elif rejected:
+        reason = f"recorder attesting; managed policy REFUSED, its locks are not in force: {', '.join(rejected)}"
     elif uncovered:
         reason = f"recorder attesting; agents present but NOT recorded: {', '.join(uncovered)}"
     elif facts["spool_depth"] > 0:

{agentmetry-0.9.8 → agentmetry-0.9.9}/agentmetry/core/audit/hook_bootstrap.py

@@ -10,6 +10,8 @@ import sys
 from pathlib import Path
 from typing import Any
 
+from agentmetry.core.paths import user_profile_dir
+
 logger = logging.getLogger(__name__)
 
 # Hook subprocesses read these from orchestrator .env (Claude also gets them in settings env).
@@ -78,7 +80,7 @@ def install_cursor_global_hooks(
         return None
 
     py = python or sys.executable
-    hooks_dir = Path.home() / ".cursor"
+    hooks_dir = user_profile_dir() / ".cursor"
     hooks_path = hooks_dir / "hooks.json"
     payload = cursor_hooks_payload(python=py, ingest=ingest, repo_root=root)
 
@@ -371,7 +373,7 @@ def install_claude_global_hooks(
         return None
 
     py = python or sys.executable
-    settings_dir = Path.home() / ".claude"
+    settings_dir = user_profile_dir() / ".claude"
     settings_path = settings_dir / "settings.json"
 
     settings: dict[str, Any] = {}
@@ -400,7 +402,7 @@ def _qwen_settings_dir() -> Path:
     home = os.environ.get("QWEN_HOME", "").strip()
     if home:
         return Path(home).expanduser()
-    return Path.home() / ".qwen"
+    return user_profile_dir() / ".qwen"
 
 
 def install_qwen_global_hooks(
@@ -413,7 +415,7 @@ def install_qwen_global_hooks(
 
 
 def _qoder_settings_dir() -> Path:
-    return Path.home() / ".qoder"
+    return user_profile_dir() / ".qoder"
 
 
 def install_qoder_global_hooks(
@@ -426,7 +428,7 @@ def install_qoder_global_hooks(
 
 
 def _codebuddy_settings_dir() -> Path:
-    return Path.home() / ".codebuddy"
+    return user_profile_dir() / ".codebuddy"
 
 
 def install_codebuddy_global_hooks(
@@ -561,7 +563,7 @@ def install_codex_global_hooks(
         return None
 
     py = python or sys.executable
-    hooks_dir = Path.home() / ".codex"
+    hooks_dir = user_profile_dir() / ".codex"
     hooks_path = hooks_dir / "hooks.json"
 
     doc: dict[str, Any] = {}
@@ -617,7 +619,7 @@ COPILOT_HOOK_EVENTS: tuple[tuple[str, str], ...] = (
 
 def copilot_hooks_dir() -> Path:
     home = os.environ.get("COPILOT_HOME", "").strip()
-    return (Path(home).expanduser() if home else Path.home() / ".copilot") / "hooks"
+    return (Path(home).expanduser() if home else user_profile_dir() / ".copilot") / "hooks"
 
 
 def copilot_hooks_document(
@@ -666,7 +668,7 @@ def _kimi_config_dir() -> Path:
     home = os.environ.get("KIMI_CODE_HOME", "").strip()
     if home:
         return Path(home).expanduser()
-    return Path.home() / ".kimi-code"
+    return user_profile_dir() / ".kimi-code"
 
 
 def kimi_hooks_toml_block(*, python: str, ingest: Path, repo_root: Path | None = None) -> str:

{agentmetry-0.9.8 → agentmetry-0.9.9}/agentmetry/core/config.py

@@ -1,10 +1,21 @@
+import logging
 from pathlib import Path
 
 from pydantic import AliasChoices, Field
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
+from agentmetry.core import managed_policy
 from agentmetry.core.paths import data_dir, env_file
 
+# Before anything below reads the environment: a locked data_dir decides where
+# `.env` is looked for, and every locked key must beat the `.env` Settings reads.
+# A broken policy degrades to the environment rather than stopping the
+# recorder; doctor and the heartbeat report the source it refused.
+try:
+    managed_policy.apply_locks()
+except Exception:
+    logging.getLogger(__name__).exception("Managed policy was not applied")
+
 _ORCHESTRATOR_ROOT = Path(__file__).resolve().parents[2]
 # Data and .env no longer live beside the package in an installed wheel
 # (they were in site-packages). See core/paths.py.

{agentmetry-0.9.8 → agentmetry-0.9.9}/agentmetry/core/diagnostics/doctor.py

@@ -36,6 +36,16 @@ class Finding:
 @dataclass
 class DoctorReport:
     findings: list[Finding] = field(default_factory=list)
+    #: Facts for `doctor --json`, set by the checks that establish them. A
+    #: deployment script reads these rather than the sentences, which get
+    #: reworded, and a compliance check that breaks on a wording change fails
+    #: silently.
+    hooks: dict[str, str] = field(default_factory=dict)
+    hook_profile: str = ""
+    orchestrator_reachable: bool = False
+    policy_locked: list[str] = field(default_factory=list)
+    policy_pinned: list[str] = field(default_factory=list)
+    policy_rejected: list[str] = field(default_factory=list)
 
     def ok(self, code: str, message: str) -> None:
         self.findings.append(Finding("ok", code, message))
@@ -61,6 +71,7 @@ def _check_health_endpoint(report: DoctorReport) -> None:
     try:
         with urllib.request.urlopen(url, timeout=2) as resp:  # noqa: S310
             if resp.status == 200:
+                report.orchestrator_reachable = True
                 report.ok("orchestrator_up", f"Orchestrator responding at {url}")
                 return
             report.warn("orchestrator_up", f"Orchestrator returned HTTP {resp.status} at {url}")
@@ -210,7 +221,9 @@ def _check_hooks_installed(report: DoctorReport) -> None:
     """
     from agentmetry.core.diagnostics import hook_coverage
 
-    if hook_coverage.is_service_profile():
+    report.hook_profile = hook_coverage.attestation_profile()
+    if hook_coverage.profile_blind():
+        report.hooks = {s.name: hook_coverage.UNKNOWN for s in hook_coverage.SURFACES}
         report.fail(
             "hooks",
             f"Running under a service profile ({Path.home()}). Hook configuration "
@@ -221,6 +234,7 @@ def _check_hooks_installed(report: DoctorReport) -> None:
         return
 
     states = hook_coverage.coverage()
+    report.hooks = dict(states)
     covered = sorted(n for n, st in states.items() if st == hook_coverage.COVERED)
     uncovered = hook_coverage.uncovered(states)
     unverified = hook_coverage.unverified(states)
@@ -707,6 +721,60 @@ def _check_ask_gate(report: DoctorReport) -> None:
         )
 
 
+def _check_managed_policy(report: DoctorReport) -> None:
+    """Which keys a fleet locked, and every managed source that was refused.
+
+    A refused file fails rather than warns: an admin put it there to lock
+    something, and on this machine nothing it says is in force. The fix for a
+    file the developer could have edited is to take that ability away, never
+    to honour it, so the message says how.
+    """
+    from agentmetry.core import managed_policy
+
+    try:
+        policy = managed_policy.load_policy()
+    except Exception as exc:
+        report.fail("managed_policy", f"Managed policy could not be read: {exc}")
+        return
+    report.policy_locked = sorted(policy.locked)
+    report.policy_pinned = list(policy.pinned)
+    report.policy_rejected = [s.location for s in policy.rejected]
+    for source in policy.rejected:
+        hint = "" if source.location == managed_policy.REGISTRY_LOCATION else (
+            " " + managed_policy.remediation(source.location)
+        )
+        report.fail("managed_policy", f"Managed policy {source.location} {source.reason}.{hint}")
+    for source in policy.sources:
+        if source.accepted and source.unknown:
+            report.warn(
+                "managed_policy",
+                f"{source.location} sets keys this release does not know, ignored: "
+                f"{', '.join(source.unknown)}",
+            )
+    if not policy.locked:
+        if not policy.rejected:
+            report.ok("managed_policy", "No managed policy; the environment and .env apply")
+        return
+    where = ", ".join(s.location for s in policy.sources if s.accepted)
+    report.ok("managed_policy", f"Managed policy locks {', '.join(sorted(policy.locked))} ({where})")
+    for key in policy.pinned:
+        report.ok(
+            "managed_policy",
+            f"{key} pinned to the built-in manifest because {managed_policy.PINNED_BY[key]} "
+            f"is locked; lock {key} too to use another",
+        )
+    for key in managed_policy.PINNED_BY:
+        if key not in policy.locked:
+            continue
+        try:
+            managed_policy.read_trusted(Path(str(policy.locked[key])))
+        except (managed_policy.Untrusted, OSError) as exc:
+            report.warn(
+                "managed_policy",
+                f"Locked {key} is a file the developer may be able to edit: {exc}",
+            )
+
+
 def run_doctor(
     *,
     vault_path: Path | None = None,
@@ -779,6 +847,7 @@ def run_doctor(
     except OSError as exc:
         report.fail("data", f"Data directory not writable ({data_dir}): {exc}")
 
+    _check_managed_policy(report)
     _check_manifests(report)
     _check_ask_gate(report)
     _check_exposure(report)
@@ -808,14 +877,55 @@ def format_report(report: DoctorReport) -> str:
     return "\n".join(lines)
 
 
+#: Bumped when a field changes meaning or goes away. Adding one does not bump it.
+JSON_SCHEMA = 1
+
+
+def report_payload(report: DoctorReport) -> dict:
+    """`doctor --json`: the report as fields a deployment script can test.
+
+    `hooks` uses the coverage vocabulary (`covered`, `uncovered`, `absent`,
+    `unknown`), and `absent` is an agent that is not installed, not drift.
+    `orchestrator_reachable` is true only when the health route answered 200.
+    `exit_code` is the one the command returns.
+    """
+    from agentmetry.core.version import __version__
+
+    return {
+        "schema": JSON_SCHEMA,
+        "version": __version__,
+        "exit_code": report.exit_code,
+        "orchestrator_reachable": report.orchestrator_reachable,
+        "hook_profile": report.hook_profile,
+        "hooks": dict(report.hooks),
+        "policy": {
+            "locked": list(report.policy_locked),
+            "pinned": list(report.policy_pinned),
+            "rejected": list(report.policy_rejected),
+        },
+        "findings": [
+            {"severity": f.severity, "code": f.code, "message": f.message}
+            for f in report.findings
+        ],
+    }
+
+
+def print_report(report: DoctorReport, *, as_json: bool = False) -> None:
+    if as_json:
+        print(json.dumps(report_payload(report), indent=2))
+    else:
+        print("Agentmetry doctor\n" + format_report(report))
+
+
 def main(argv: list[str] | None = None) -> int:
     import argparse
 
     parser = argparse.ArgumentParser(prog="agentmetry-doctor")
     parser.add_argument("--fix", action="store_true", help="rewrite drivers.json to portable tokens")
+    parser.add_argument("--json", action="store_true", help="print the report as JSON")
     args = parser.parse_args(argv)
     report = run_doctor(fix_drivers=args.fix)
-    print("Agentmetry doctor\n" + format_report(report))
+    print_report(report, as_json=args.json)
     return report.exit_code
 
 

{agentmetry-0.9.8 → agentmetry-0.9.9}/agentmetry/core/diagnostics/hook_coverage.py

@@ -45,6 +45,10 @@ found there, and reported as installed, while no developer's IDE ever reads that
 directory. A per-machine install would then attest full coverage for a fleet
 recording nothing. So a service profile is a definite failure rather than an
 unknown, and it degrades the beat.
+
+`AGENTMETRY_USER_PROFILE_DIR` (or `--user-profile-dir`) is the way out: a
+service told whose home to read reads that developer's configs, and is not
+blind. `profile_blind()` is the one test for "nothing here can be seen".
 """
 
 from __future__ import annotations
@@ -53,6 +57,8 @@ import os
 from dataclasses import dataclass
 from pathlib import Path
 
+from agentmetry.core.paths import named_user_profile, user_profile_dir
+
 #: What our hook command looks like in a config we merged into. Checking for the
 #: marker rather than for the file means an IDE config the user owns is judged on
 #: our half of it. `agentaudit_ingest` is the pre-rename name, still on disk for
@@ -109,7 +115,7 @@ class Surface:
         override = os.environ.get(self.home_env, "").strip() if self.home_env else ""
         if override:
             return Path(override).expanduser()
-        return Path.home() / self.home_rel
+        return user_profile_dir() / self.home_rel
 
     def installed(self) -> bool:
         """Whether this agent is on the machine, as far as the disk can say.
@@ -183,6 +189,18 @@ def is_service_profile(home: Path | None = None) -> bool:
     return "/config/systemprofile" in text or "/windows/serviceprofiles/" in text
 
 
+def profile_blind() -> bool:
+    """True when no developer's configs are in view: a service profile with no
+    `AGENTMETRY_USER_PROFILE_DIR` naming whose home to read."""
+    return is_service_profile() and not named_user_profile()
+
+
+def attestation_profile() -> str:
+    """What a heartbeat says about whose configs it attests: `service` when
+    blind, else `user`, including a service that was named a developer."""
+    return "service" if profile_blind() else "user"
+
+
 def _has_marker(path: Path, markers: tuple[str, ...]) -> bool:
     try:
         if not path.is_file():
@@ -200,7 +218,7 @@ def coverage() -> dict[str, str]:
     a value captured at boot keeps asserting the configuration the machine had
     when it last restarted, which is precisely the lie being hunted.
     """
-    if is_service_profile():
+    if profile_blind():
         # Every path below would describe the service's own profile. Reporting
         # confident per-agent answers from it is worse than reporting none.
         return {s.name: UNKNOWN for s in SURFACES}
@@ -256,7 +274,7 @@ def unverified(states: dict[str, str] | None = None) -> list[str]:
 
 def summary_lines(states: dict[str, str] | None = None) -> list[str]:
     states = states if states is not None else coverage()
-    if is_service_profile():
+    if profile_blind():
         return [
             "  hooks: UNKNOWN, running under a service profile "
             f"({Path.home()}); no developer's configuration is visible from here"

{agentmetry-0.9.8 → agentmetry-0.9.9}/agentmetry/core/diagnostics/machine_view.py

@@ -44,7 +44,7 @@ def snapshot() -> dict[str, Any]:
     from agentmetry.core.audit.identity import host_id
     from agentmetry.core.audit.policy_settings import policy_settings
     from agentmetry.core.audit.tool_policy.loader import load_tool_policy
-    from agentmetry.core.diagnostics.hook_coverage import SURFACES, coverage, is_service_profile
+    from agentmetry.core.diagnostics.hook_coverage import SURFACES, attestation_profile, coverage
     from agentmetry.core.diagnostics.mcp_inventory import collect as collect_mcp
     from agentmetry.core.diagnostics.mcp_schema import load_store
     from agentmetry.core.diagnostics.posture import NOT_CHECKED, collect as collect_posture
@@ -67,7 +67,7 @@ def snapshot() -> dict[str, Any]:
 
     return {
         "host_id": host_id(),
-        "profile": "service" if is_service_profile() else "user",
+        "profile": attestation_profile(),
         "agents": agents,
         "posture": {
             "findings": [{**item.wire(), "why": item.why} for item in posture.sorted()],

{agentmetry-0.9.8 → agentmetry-0.9.9}/agentmetry/core/diagnostics/mcp_inventory.py

@@ -32,13 +32,14 @@ from __future__ import annotations
 
 import hashlib
 import json
-import os
 import re
 from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any, Iterable
 from urllib.parse import urlparse
 
+from agentmetry.core.paths import user_profile_dir
+
 #: Fetch-and-run launchers. These resolve a package over the network on every
 #: invocation, so the bytes executed are decided later than the config was read.
 _FETCHING_LAUNCHER = re.compile(r"^(npx|uvx|pnpx|bunx|pipx)$", re.IGNORECASE)
@@ -192,7 +193,7 @@ def config_locations(project: Path | None = None) -> list[tuple[str, str, Path]]
     A missing file is normal rather than an error: a machine running Cursor and
     not Claude Code should report on Cursor and stay silent about the rest.
     """
-    home = Path(os.path.expanduser("~"))
+    home = user_profile_dir()
     found: list[tuple[str, str, Path]] = [
         ("claude", "user", home / ".claude.json"),
         ("claude", "user", home / ".claude" / "settings.json"),