feat(guard): add dashboard shortcut (#179)

* feat(guard): add dashboard shortcut

Signed-off-by: Michael Kantor <6068672+kantorcodes@users.noreply.github.com>

* fix(guard): report dashboard open state

Signed-off-by: Michael Kantor <6068672+kantorcodes@users.noreply.github.com>

* fix(guard): refine dashboard launch flow

Signed-off-by: Michael Kantor <6068672+kantorcodes@users.noreply.github.com>

* fix(guard): tighten dashboard open flow

Signed-off-by: Michael Kantor <6068672+kantorcodes@users.noreply.github.com>

---------

Signed-off-by: Michael Kantor <6068672+kantorcodes@users.noreply.github.com>

Author: kantorcodes

src/codex_plugin_scanner/guard/cli/commands.py

@@ -112,6 +112,7 @@
     "Everyday protection:\n"
     "  start        First-run setup and the Guard operating loop\n"
     "  status       Current local protection state and next actions\n"
+    "  dashboard    Open the local Guard dashboard in your browser\n"
     "  run          Enforce Guard before a harness launch\n"
     "  approvals    Resolve the current request queue\n"
     "  receipts     Review recent local decisions\n"
@@ -204,7 +205,7 @@ def _configure_guard_parser(guard_parser: argparse.ArgumentParser) -> None:
         required=True,
         parser_class=FriendlyArgumentParser,
         metavar=(
-            "{start,status,bootstrap,detect,install,update,uninstall,run,protect,preflight,scan,diff,receipts,inventory,abom,"
+            "{start,status,dashboard,bootstrap,detect,install,update,uninstall,run,protect,preflight,scan,diff,receipts,inventory,abom,"
             "approvals,explain,allow,deny,policies,exceptions,advisories,events,doctor,connect,login,sync,device,bridge}"
         ),
     )
@@ -217,6 +218,17 @@ def _configure_guard_parser(guard_parser: argparse.ArgumentParser) -> None:
     _add_guard_common_args(status_parser)
     status_parser.add_argument("--json", action="store_true")
 
+    dashboard_parser = guard_subparsers.add_parser(
+        "dashboard",
+        help="Open the local Guard dashboard in your browser",
+    )
+    _add_guard_common_args(dashboard_parser)
+    dashboard_parser.add_argument("--json", action="store_true")
+
+    admin_parser = guard_subparsers.add_parser("admin", help=argparse.SUPPRESS)
+    _add_guard_common_args(admin_parser)
+    admin_parser.add_argument("--json", action="store_true")
+
     bootstrap_parser = guard_subparsers.add_parser(
         "bootstrap",
         help="Detect a harness, start the approval center, and install Guard for the best local target",
@@ -513,6 +525,7 @@ def _configure_guard_parser(guard_parser: argparse.ArgumentParser) -> None:
     hermes_mcp_proxy_parser.add_argument("--server", required=True)
     hermes_mcp_proxy_parser.add_argument("--stdio", action="store_true")
     hidden_commands = {
+        "admin",
         "hook",
         "daemon",
         "codex-mcp-proxy",
@@ -660,6 +673,43 @@ def run_guard_command(
         _emit("status", payload, getattr(args, "json", False))
         return 0
 
+    if args.guard_command in {"dashboard", "admin"}:
+        try:
+            approval_center_url = ensure_guard_daemon(guard_home)
+        except RuntimeError as error:
+            if getattr(args, "json", False):
+                _emit(
+                    "dashboard",
+                    {
+                        "generated_at": _now(),
+                        "opened": False,
+                        "error": str(error),
+                    },
+                    True,
+                )
+            else:
+                print(str(error), file=sys.stderr)
+            return 1
+        open_result = _open_approval_center(
+            approval_center_url,
+            store=store,
+            config=config,
+            open_key="dashboard",
+            force_open=True,
+        )
+        _emit(
+            "dashboard",
+            {
+                "generated_at": _now(),
+                "approval_center_url": approval_center_url,
+                "browser_url": open_result.get("browser_url"),
+                "opened": bool(open_result.get("opened")),
+                "reason": str(open_result.get("reason") or "unknown"),
+            },
+            getattr(args, "json", False),
+        )
+        return 0
+
     if args.guard_command == "bootstrap":
         try:
             payload = build_guard_bootstrap_payload(
@@ -3278,17 +3328,28 @@ def resolve(detection, payload):
     return resolve
 
 
-def _open_approval_center(approval_center_url: str, *, store: GuardStore, config, open_key: str | None = None) -> None:
+def _open_approval_center(
+    approval_center_url: str,
+    *,
+    store: GuardStore,
+    config: GuardConfig,
+    open_key: str | None = None,
+    force_open: bool = False,
+) -> dict[str, object]:
     surface_runtime = GuardSurfaceRuntime(store)
     auth_token = load_guard_daemon_auth_token(store.guard_home)
-    surface_runtime.ensure_surface(
+    browser_url = _approval_center_browser_url(approval_center_url, auth_token)
+    open_result = surface_runtime.ensure_surface(
         surface="approval-center",
         approval_center_url=approval_center_url,
-        browser_url=_approval_center_browser_url(approval_center_url, auth_token),
+        browser_url=browser_url,
         approval_surface_policy=config.approval_surface_policy,
         open_key=open_key or approval_center_url,
+        force_open=force_open,
         opener=webbrowser.open,
     )
+    open_result["browser_url"] = _public_approval_center_url(browser_url) or approval_center_url
+    return open_result
 
 
 def _approval_center_browser_url(approval_center_url: str, auth_token: str | None) -> str | None:
@@ -3304,6 +3365,18 @@ def _approval_center_browser_url(approval_center_url: str, auth_token: str | Non
     return urllib.parse.urlunparse(parsed._replace(fragment=urllib.parse.urlencode(fragment_pairs)))
 
 
+def _public_approval_center_url(browser_url: str | None) -> str | None:
+    if browser_url is None:
+        return None
+    parsed = urllib.parse.urlparse(browser_url)
+    fragment_pairs = [
+        (key, value)
+        for key, value in urllib.parse.parse_qsl(parsed.fragment, keep_blank_values=True)
+        if key != "guard-token"
+    ]
+    return urllib.parse.urlunparse(parsed._replace(fragment=urllib.parse.urlencode(fragment_pairs)))
+
+
 def _approval_surface_policy_for_flow(config_policy: str, approval_flow: dict[str, object]) -> str:
     if approval_flow.get("tier") != "approval-center":
         return "notify-only"

src/codex_plugin_scanner/guard/cli/render.py

@@ -654,6 +654,14 @@ def _render_connect(console: Console, payload: dict[str, object]) -> None:
     console.print(_build_steps_panel(_coerce_dict_list(payload.get("next_steps"))))
 
 
+def _render_dashboard(console: Console, payload: dict[str, object]) -> None:
+    body = Table.grid(padding=(0, 1))
+    body.add_row("Dashboard", str(payload.get("approval_center_url") or "unknown"))
+    if payload.get("opened") is not None:
+        body.add_row("Browser opened", _bool_label(bool(payload.get("opened"))))
+    console.print(Panel(body, title="HOL Guard dashboard", border_style="cyan"))
+
+
 def _render_sync(console: Console, payload: dict[str, object]) -> None:
     body = Table.grid(padding=(0, 1))
     body.add_row("Synced at", str(payload.get("synced_at") or "unknown"))
@@ -1615,6 +1623,7 @@ def _clean_terminal_output(value: str) -> str:
     "approvals": _render_approvals,
     "start": _render_start,
     "status": _render_status,
+    "dashboard": _render_dashboard,
     "connect": _render_connect,
     "bootstrap": _render_bootstrap,
     "detect": _render_detect,

src/codex_plugin_scanner/guard/runtime/surface_server.py

@@ -332,10 +332,15 @@ def ensure_surface(
         approval_surface_policy: str,
         open_key: str,
         opener: Callable[[str], object],
+        force_open: bool = False,
     ) -> dict[str, object]:
-        if approval_surface_policy in {"notify-only", "never-auto-open"}:
+        if approval_surface_policy in {"notify-only", "never-auto-open"} and not force_open:
             return {"surface": surface, "opened": False, "reason": "policy-disabled", "open_key": open_key}
-        if approval_surface_policy == "auto-open-once" and self.has_surface_opened(surface, open_key):
+        if (
+            approval_surface_policy == "auto-open-once"
+            and not force_open
+            and self.has_surface_opened(surface, open_key)
+        ):
             return {"surface": surface, "opened": False, "reason": "already-opened", "open_key": open_key}
         if self.has_live_surface(surface):
             return {"surface": surface, "opened": False, "reason": "live-client", "open_key": open_key}

tests/test_guard_cli.py

@@ -6048,6 +6048,100 @@ def complete_pairing() -> None:
         assert connect_output["reason"] == "Guard sync requires a Pro or Team plan."
         assert connect_output["sync_message"] == "Guard sync requires a Pro or Team plan."
 
+    def test_guard_dashboard_opens_local_approval_center(self, tmp_path, capsys, monkeypatch):
+        home_dir = tmp_path / "home"
+        opened_urls: list[str] = []
+        open_keys: list[str | None] = []
+        force_open_flags: list[bool] = []
+
+        monkeypatch.setattr(
+            guard_commands_module,
+            "ensure_guard_daemon",
+            lambda guard_home: "http://127.0.0.1:5474",
+        )
+        monkeypatch.setattr(
+            guard_commands_module,
+            "_open_approval_center",
+            lambda approval_center_url, *, store, config, open_key=None, force_open=False: (
+                opened_urls.append(approval_center_url),
+                open_keys.append(open_key),
+                force_open_flags.append(force_open),
+                {"opened": True, "reason": "opened", "browser_url": approval_center_url},
+            )[-1],
+        )
+
+        rc = main(["guard", "dashboard", "--home", str(home_dir), "--json"])
+        output = json.loads(capsys.readouterr().out)
+
+        assert rc == 0
+        assert opened_urls == ["http://127.0.0.1:5474"]
+        assert open_keys == ["dashboard"]
+        assert force_open_flags == [True]
+        assert output["approval_center_url"] == "http://127.0.0.1:5474"
+        assert output["browser_url"] == "http://127.0.0.1:5474"
+        assert output["opened"] is True
+        assert output["reason"] == "opened"
+
+    def test_guard_admin_alias_opens_local_approval_center(self, tmp_path, capsys, monkeypatch):
+        home_dir = tmp_path / "home"
+        opened_urls: list[str] = []
+        open_keys: list[str | None] = []
+        force_open_flags: list[bool] = []
+
+        monkeypatch.setattr(
+            guard_commands_module,
+            "ensure_guard_daemon",
+            lambda guard_home: "http://127.0.0.1:5474",
+        )
+        monkeypatch.setattr(
+            guard_commands_module,
+            "_open_approval_center",
+            lambda approval_center_url, *, store, config, open_key=None, force_open=False: (
+                opened_urls.append(approval_center_url),
+                open_keys.append(open_key),
+                force_open_flags.append(force_open),
+                {"opened": False, "reason": "policy-disabled", "browser_url": approval_center_url},
+            )[-1],
+        )
+
+        rc = main(["guard", "admin", "--home", str(home_dir), "--json"])
+        output = json.loads(capsys.readouterr().out)
+
+        assert rc == 0
+        assert opened_urls == ["http://127.0.0.1:5474"]
+        assert open_keys == ["dashboard"]
+        assert force_open_flags == [True]
+        assert output["approval_center_url"] == "http://127.0.0.1:5474"
+        assert output["browser_url"] == "http://127.0.0.1:5474"
+        assert output["opened"] is False
+        assert output["reason"] == "policy-disabled"
+
+    def test_guard_dashboard_returns_error_when_daemon_start_fails(self, tmp_path, capsys, monkeypatch):
+        home_dir = tmp_path / "home"
+
+        monkeypatch.setattr(
+            guard_commands_module,
+            "ensure_guard_daemon",
+            lambda guard_home: (_ for _ in ()).throw(RuntimeError("dashboard_unavailable")),
+        )
+
+        rc = main(["guard", "dashboard", "--home", str(home_dir), "--json"])
+        output = json.loads(capsys.readouterr().out)
+
+        assert rc == 1
+        assert output["opened"] is False
+        assert output["error"] == "dashboard_unavailable"
+
+    def test_public_approval_center_url_strips_guard_token(self):
+        browser_url = guard_commands_module._approval_center_browser_url(
+            "http://127.0.0.1:5474#section=inbox",
+            "secret-token",
+        )
+
+        assert browser_url is not None
+        assert "guard-token=secret-token" in browser_url
+        assert "guard-token=" not in guard_commands_module._public_approval_center_url(browser_url)
+
     def test_guard_connect_pending_output_uses_product_copy_for_sign_in_gap(self, capsys):
         emit_guard_payload(
             "connect",

tests/test_guard_surface_server.py

@@ -1620,3 +1620,46 @@ def test_copilot_adapter_implements_surface_runtime_contract(self, tmp_path) ->
         assert operation["operation_type"] == "run"
         assert approval["request_ids"] == ["req-1", "req-2"]
         assert resumed["status"] == "completed"
+
+    def test_guard_surface_runtime_force_open_bypasses_auto_open_once(self, tmp_path) -> None:
+        store = GuardStore(tmp_path / "guard-home")
+        runtime = GuardSurfaceRuntime(store)
+        opened_urls: list[str] = []
+
+        first_result = runtime.ensure_surface(
+            surface="approval-center",
+            approval_center_url="http://127.0.0.1:5474",
+            approval_surface_policy="auto-open-once",
+            open_key="dashboard",
+            opener=lambda url: opened_urls.append(url) or True,
+        )
+        second_result = runtime.ensure_surface(
+            surface="approval-center",
+            approval_center_url="http://127.0.0.1:5474",
+            approval_surface_policy="auto-open-once",
+            open_key="dashboard",
+            force_open=True,
+            opener=lambda url: opened_urls.append(url) or True,
+        )
+
+        assert first_result["opened"] is True
+        assert second_result["opened"] is True
+        assert opened_urls == ["http://127.0.0.1:5474", "http://127.0.0.1:5474"]
+
+    def test_guard_surface_runtime_force_open_overrides_disabled_policy(self, tmp_path) -> None:
+        store = GuardStore(tmp_path / "guard-home")
+        runtime = GuardSurfaceRuntime(store)
+        opened_urls: list[str] = []
+
+        result = runtime.ensure_surface(
+            surface="approval-center",
+            approval_center_url="http://127.0.0.1:5474",
+            approval_surface_policy="never-auto-open",
+            open_key="dashboard",
+            force_open=True,
+            opener=lambda url: opened_urls.append(url) or True,
+        )
+
+        assert result["opened"] is True
+        assert result["reason"] == "opened"
+        assert opened_urls == ["http://127.0.0.1:5474"]