chore: close audit cleanup and clean-room install fix

Author: alessiolidoz-hash

agents/main/README.md

@@ -7,5 +7,5 @@ Public role:
 
 Private-only items that must not be copied here:
 - personal identity details
-- private family routing
+- private household routing
 - private Telegram/WhatsApp doctrine

docs/EXTRACTION-MAP.md

@@ -30,10 +30,10 @@ Classification:
 
 ### Rewrite
 
-- dist patch ledger shape from `/root/.openclaw/patches/apply-patches.sh`
+- dist patch ledger shape from the private runtime patch ledger
 - patch application helpers that currently assume the private compiled dist path
 - pre-start sync helpers such as `workspace/scripts/sync_agent_main_thinking.py`
-- any control-plane helper that assumes live session stores under `/root/.openclaw/agents/`
+- any control-plane helper that assumes live session stores under the private runtime root
 
 ### Exclude
 
@@ -94,9 +94,9 @@ Classification:
 
 ### Exclude
 
-- `/root/.openclaw/memory/main.sqlite`
+- live Tier 1 SQLite stores
 - live graph stores and caches
-- `/root/.openclaw/arscontexta/`
+- live synthesis stores
 - private operator memory and live episodic traces
 
 ## Operational Fabric

fixtures/ops_fabric/system-operational-watchdog.sample.json

@@ -9,7 +9,7 @@
     "candidates": 1,
     "dispatches": 1,
     "deliverableActivity": 1,
-    "normalizedPrincipalVisibleTasks": 1,
+    "normalizedOwnerVisibleTasks": 1,
     "resolved": 0
   },
   "incidents": {

src/hyperclaw_max/first_run.py

@@ -103,15 +103,15 @@ def run_first_run(
 def main() -> int:
     ap = argparse.ArgumentParser(description="Run the public HyperClaw-Max first-run bootstrap")
     ap.add_argument("target_root", type=Path, help="Destination root for the materialized public pack")
-    ap.add_argument("--repo", type=Path, default=repo_root())
+    ap.add_argument("--repo", type=Path, default=None)
     ap.add_argument("--include-optional", action="append", default=[], help="Optional agent id to materialize")
     ap.add_argument("--all-optional", action="store_true", help="Materialize all optional overlay agents")
     ap.add_argument("--force", action="store_true", help="Overwrite existing materialized files")
     ap.add_argument("--format", choices=["json", "human"], default="human")
     args = ap.parse_args()
 
     payload = run_first_run(
-        args.repo,
+        args.repo.resolve() if args.repo is not None else repo_root(),
         args.target_root,
         include_optional=set(args.include_optional),
         include_all_optional=args.all_optional,

src/hyperclaw_max/materialize_pack.py

@@ -13,10 +13,35 @@
 BOOT_FILES = ("README.md", "AGENTS.md", "BOOTSTRAP.md", "TOOLS.md")
 LIST_SECTIONS = {"required_agents", "optional_agents", "pack_rules"}
 REQUIRED_MANIFEST_KEYS = {"version", "name", "status", "required_agents", "optional_agents", "pack_rules"}
+REPO_ROOT_MARKERS = (
+    "pyproject.toml",
+    "agents/PACK-MANIFEST.yaml",
+    "config/openclaw.public.example.jsonc",
+)
 
 
-def repo_root() -> Path:
-    return Path(__file__).resolve().parents[2]
+def looks_like_repo_root(path: Path) -> bool:
+    return all((path / marker).exists() for marker in REPO_ROOT_MARKERS)
+
+
+def repo_root(cwd: Path | None = None, module_path: Path | None = None) -> Path:
+    candidates: list[Path] = []
+    if cwd is not None:
+        candidates.append(cwd.resolve())
+    else:
+        candidates.append(Path.cwd().resolve())
+
+    source_path = module_path.resolve() if module_path is not None else Path(__file__).resolve()
+    candidates.extend(source_path.parents)
+
+    seen: set[Path] = set()
+    for candidate in candidates:
+        if candidate in seen:
+            continue
+        seen.add(candidate)
+        if looks_like_repo_root(candidate):
+            return candidate
+    raise FileNotFoundError("Unable to locate the HyperClaw-Max repository root; pass --repo explicitly.")
 
 
 def now_iso() -> str:
@@ -205,15 +230,15 @@ def materialize_pack(
 def main() -> int:
     ap = argparse.ArgumentParser(description="Materialize the public HyperClaw-Max pack over a target root")
     ap.add_argument("target_root", type=Path, help="Destination root that will host config, workspaces, and runtime state")
-    ap.add_argument("--repo", type=Path, default=repo_root())
+    ap.add_argument("--repo", type=Path, default=None)
     ap.add_argument("--include-optional", action="append", default=[], help="Optional agent id to materialize")
     ap.add_argument("--all-optional", action="store_true", help="Materialize all optional overlay agents")
     ap.add_argument("--force", action="store_true", help="Overwrite existing materialized files")
     ap.add_argument("--format", choices=["json", "human"], default="human")
     args = ap.parse_args()
 
     payload = materialize_pack(
-        args.repo,
+        args.repo.resolve() if args.repo is not None else repo_root(),
         args.target_root,
         include_optional=set(args.include_optional),
         include_all_optional=args.all_optional,

src/hyperclaw_max/ops_fabric/contracts.py

@@ -48,7 +48,7 @@ def empty_watchdog() -> dict[str, Any]:
             "candidates": 0,
             "dispatches": 0,
             "deliverableActivity": 0,
-            "normalizedPrincipalVisibleTasks": 0,
+            "normalizedOwnerVisibleTasks": 0,
             "resolved": 0,
         },
         "incidents": {},

tests/test_materialize_pack.py

@@ -1,9 +1,10 @@
 import json
+import os
 import unittest
 from pathlib import Path
 from tempfile import TemporaryDirectory
 
-from hyperclaw_max.materialize_pack import load_pack_manifest, materialize_pack
+from hyperclaw_max.materialize_pack import load_pack_manifest, materialize_pack, repo_root
 from hyperclaw_max.ops_fabric.cli import validate_state_dir
 
 
@@ -49,6 +50,18 @@ def test_materialize_pack_can_enable_optional_overlay(self) -> None:
             self.assertTrue((Path(tmp) / "workspace-finance" / "AGENTS.md").exists())
             self.assertFalse((Path(tmp) / "workspace-legal").exists())
 
+    def test_repo_root_prefers_cwd_when_module_path_is_external(self) -> None:
+        with TemporaryDirectory() as tmp:
+            fake_module = Path(tmp) / ".venv" / "lib" / "python3.12" / "site-packages" / "hyperclaw_max" / "materialize_pack.py"
+            fake_module.parent.mkdir(parents=True)
+            fake_module.write_text("# synthetic module path for repo root discovery\n", encoding="utf-8")
+            old_cwd = Path.cwd()
+            try:
+                os.chdir(REPO_ROOT)
+                self.assertEqual(repo_root(module_path=fake_module), REPO_ROOT)
+            finally:
+                os.chdir(old_cwd)
+
 
 if __name__ == "__main__":
     unittest.main()