agentgov-cli 0.1.1__tar.gz → 0.1.4__tar.gz

{agentgov_cli-0.1.1 → agentgov_cli-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentgov-cli
-Version: 0.1.1
+Version: 0.1.4
 Summary: AgentGov CLI — wrap Claude Code, bind work items, check gateway health.
 Author: AgentGov Contributors
 License: Apache-2.0

agentgov_cli-0.1.4/agentgov_cli/commands/gateway.py

@@ -0,0 +1,84 @@
+"""`agentgov gateway` — manage the local gateway process.
+
+`install` is the recommended path: a supervised service (systemd --user on
+Linux/WSL, launchd on macOS) that starts at login and restarts on failure, so
+the port Claude Code targets is bound whenever the developer is working.
+"""
+
+from __future__ import annotations
+
+import typer
+from rich.console import Console
+
+from .. import gateway_process as gp
+
+console = Console()
+
+app = typer.Typer(name="gateway", help="Manage the local AgentGov gateway process.")
+
+_GATEWAY_OPT = typer.Option(None, "--gateway", envvar="AGENTGOV_GATEWAY_URL")
+
+
+def _url(gateway_url: str | None) -> str:
+    return gateway_url or "http://localhost:8000"
+
+
+@app.command("install")
+def install(gateway_url: str = _GATEWAY_OPT) -> None:
+    """Install + start the gateway as a supervised background service."""
+    url = _url(gateway_url)
+    ok, detail = gp.install_service()
+    if not ok:
+        console.print(f"[yellow]Could not install a service:[/] {detail}")
+        console.print("Falling back to a detached one-off start.")
+        ok, detail = gp.ensure_running(url)
+        if not ok:
+            console.print(f"[red]Gateway did not start.[/] {detail}")
+            raise typer.Exit(1)
+        console.print(f"[green]Gateway running[/] at {url} ({detail})")
+        return
+
+    console.print(f"[green]{detail}[/]")
+    # Wait for boot rather than probing once. The service manager returns as
+    # soon as it has spawned the process, but the gateway only binds its port
+    # after rehydrating sessions and fetching the first policy snapshot — two
+    # round-trips to the control tower. A single probe here reports a false
+    # failure on a gateway that is simply still starting.
+    console.print(f"Waiting for {url}/health ...")
+    if gp.wait_until_healthy(url):
+        console.print(f"[green]Gateway healthy[/] at {url}")
+    else:
+        # Genuinely not answering — surface the log rather than claiming success.
+        console.print(f"[yellow]Service installed but {url}/health did not answer in time.[/]")
+        console.print(gp.log_tail())
+        raise typer.Exit(1)
+
+
+@app.command("start")
+def start(gateway_url: str = _GATEWAY_OPT) -> None:
+    """Start the gateway now, detached from this terminal."""
+    url = _url(gateway_url)
+    ok, detail = gp.ensure_running(url)
+    if not ok:
+        console.print(f"[red]Gateway did not start.[/] {detail}")
+        raise typer.Exit(1)
+    console.print(f"[green]Gateway running[/] at {url} ({detail})")
+
+
+@app.command("status")
+def status(gateway_url: str = _GATEWAY_OPT) -> None:
+    """Report whether the gateway is answering."""
+    url = _url(gateway_url)
+    if gp.is_healthy(url):
+        console.print(f"[green]RUNNING[/] — {url}/health answered.")
+        return
+    console.print(f"[red]NOT RUNNING[/] — nothing answering at {url}/health.")
+    console.print("Start it with: [cyan]agentgov gateway install[/]")
+    console.print(gp.log_tail())
+    raise typer.Exit(1)
+
+
+@app.command("logs")
+def logs(lines: int = typer.Option(40, "--lines", "-n")) -> None:
+    """Show the tail of the gateway log."""
+    console.print(gp.log_tail(lines))

{agentgov_cli-0.1.1 → agentgov_cli-0.1.4}/agentgov_cli/commands/install.py

@@ -37,13 +37,25 @@ def run(
         help="URL of the local AgentGov gateway (usually http://localhost:8000).",
     ),
     force: bool = typer.Option(False, "--force", help="Overwrite existing hooks/statusline."),
+    user_settings: bool = typer.Option(
+        True,
+        "--user-settings/--no-user-settings",
+        help=(
+            "Register the hooks + statusline in ~/.claude/settings.json so they take "
+            "effect immediately, with no sudo. Disable for admin-managed installs."
+        ),
+    ),
 ) -> None:
     """Install hooks + statusline + slash commands into ~/.claude/.
 
+    By default this also REGISTERS them in ~/.claude/settings.json, so the
+    governance hooks run in every Claude Code session on this machine — the VS
+    Code / Cursor extension included — without sudo and without launching
+    anything through a wrapper.
+
     Also writes a ready-to-copy managed-settings.json to
-    ~/.agentgov/managed-settings.json — save that file at the OS-managed path
-    (needs sudo/admin) to force ALL Claude Code processes on this machine —
-    terminal AND VS Code extension — through the gateway.
+    ~/.agentgov/managed-settings.json. Installing THAT (needs sudo/admin) is
+    what makes governance non-overridable, for team/enterprise deployments.
     """
     src = _find_assets()
     dest = Path.home() / ".claude"
@@ -77,6 +89,16 @@ def run(
     settings = _build_managed_settings(gateway_url, hooks_dest, statusline_dest)
     settings_json = json.dumps(settings, indent=2)
 
+    # Activate the hooks for THIS user, right now, without sudo.
+    #
+    # Copying the files is not enough — Claude Code only runs hooks that a
+    # settings file registers. Previously the only place that happened was
+    # managed-settings.json, which needs root, so a developer who followed setup
+    # to the letter ended up with hook files on disk and nothing running them:
+    # no statusline, no path guard, and no work-item prompt.
+    if user_settings:
+        _merge_user_settings(gateway_url, hooks_dest, statusline_dest)
+
     # Write to a stable local path so the admin can `sudo cp` it into place
     # without having to redirect stdout carefully.
     local_settings_path = Path.home() / ".agentgov" / "managed-settings.json"
@@ -105,6 +127,95 @@ def run(
     console.print(settings_json)
 
 
+def _agentgov_hook_entries(hooks_dest: Path) -> dict[str, list[dict[str, object]]]:
+    """The hook registrations AgentGov owns, keyed by Claude Code event name."""
+    def cmd(script: str) -> dict[str, object]:
+        return {"type": "command", "command": str(hooks_dest / script)}
+
+    return {
+        "SessionStart": [{"hooks": [cmd("sessionstart_register.py")]}],
+        "UserPromptSubmit": [{"hooks": [cmd("userpromptsubmit_workitem.py")]}],
+        "PreToolUse": [
+            {
+                "matcher": "Read|Write|Edit|Glob|Grep|Bash|NotebookEdit",
+                "hooks": [cmd("pretooluse_pathguard.py")],
+            }
+        ],
+    }
+
+
+def _is_agentgov_entry(entry: object) -> bool:
+    """True if a hook registration belongs to AgentGov.
+
+    Matched on the command path so re-running `install` replaces our own entries
+    instead of stacking duplicates, while leaving the user's other hooks alone.
+    """
+    if not isinstance(entry, dict):
+        return False
+    for h in entry.get("hooks") or []:
+        if isinstance(h, dict) and "agentgov-hooks" in str(h.get("command", "")):
+            return True
+    return False
+
+
+def _merge_user_settings(gateway_url: str, hooks_dest: Path, statusline_dest: Path) -> None:
+    """Register AgentGov's hooks + statusline in ~/.claude/settings.json.
+
+    MERGES. The file usually already holds the developer's own preferences and
+    hooks; clobbering it would be a hostile way to install a governance tool.
+    We replace only entries we previously wrote (identified by their path) and
+    leave everything else untouched. A corrupt file is left alone entirely —
+    reporting it beats silently overwriting whatever was in there.
+    """
+    path = Path.home() / ".claude" / "settings.json"
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    data: dict[str, object] = {}
+    if path.exists():
+        try:
+            loaded = json.loads(path.read_text() or "{}")
+            if isinstance(loaded, dict):
+                data = loaded
+            else:
+                console.print(f"[yellow]Skipping[/] {path} — not a JSON object.")
+                return
+        except json.JSONDecodeError as e:
+            console.print(
+                f"[red]Skipping[/] {path} — it is not valid JSON ({e}).\n"
+                "Fix or remove it, then re-run `agentgov install`."
+            )
+            return
+        # Back the file up once before the first modification.
+        backup = path.with_suffix(".json.agentgov-backup")
+        if not backup.exists():
+            backup.write_text(path.read_text())
+
+    hooks_raw = data.get("hooks")
+    hooks: dict[str, object] = hooks_raw if isinstance(hooks_raw, dict) else {}
+    for event, entries in _agentgov_hook_entries(hooks_dest).items():
+        existing_raw = hooks.get(event)
+        existing = existing_raw if isinstance(existing_raw, list) else []
+        kept = [e for e in existing if not _is_agentgov_entry(e)]
+        hooks[event] = kept + entries
+    data["hooks"] = hooks
+
+    data["statusLine"] = {
+        "type": "command",
+        "command": str(statusline_dest / "agentgov_statusline.sh"),
+    }
+
+    # NOTE: deliberately NOT setting env.ANTHROPIC_BASE_URL here. User settings
+    # are the lowest-precedence scope and the developer can edit them, so
+    # pinning the base URL here would look like enforcement while being trivial
+    # to undo. Routing is the job of managed-settings.json (highest precedence).
+    path.write_text(json.dumps(data, indent=2) + "\n")
+    console.print(f"[green]Registered[/] hooks + statusline → {path}")
+    console.print(
+        "  [dim]These run in every Claude Code session on this machine, including the "
+        "VS Code extension. Restart Claude Code to pick them up.[/]"
+    )
+
+
 def _find_assets() -> Path:
     for root in ASSET_ROOTS:
         if root.exists():
@@ -122,23 +233,7 @@ def _build_managed_settings(
         },
         # apiKeyHelper disabled — Claude Code must use the agk_ key from the wrapper env.
         "apiKeyHelper": "",
-        "hooks": {
-            "PreToolUse": [
-                {
-                    "matcher": "Read|Write|Edit|Glob|Grep|Bash|NotebookEdit",
-                    "hooks": [
-                        {"type": "command", "command": str(hooks_dest / "pretooluse_pathguard.py")}
-                    ],
-                }
-            ],
-            "SessionStart": [
-                {
-                    "hooks": [
-                        {"type": "command", "command": str(hooks_dest / "sessionstart_register.py")}
-                    ]
-                }
-            ],
-        },
+        "hooks": _agentgov_hook_entries(hooks_dest),
         "statusLine": {
             "type": "command",
             "command": str(statusline_dest / "agentgov_statusline.sh"),

{agentgov_cli-0.1.1 → agentgov_cli-0.1.4}/agentgov_cli/commands/register_device.py

@@ -57,14 +57,27 @@ def run(
         console.print(f"[red]Invalid --mode {upstream_mode}[/]")
         raise typer.Exit(2)
 
-    tower = tower_url or os.environ.get("CONTROL_TOWER_URL") or "http://localhost:3000"
-
     identity_path = Path.home() / ".agentgov" / "identity.json"
     if not identity_path.exists():
         console.print("[red]No AgentGov identity found.[/] Run [bold]agentgov login[/] first.")
         raise typer.Exit(2)
     identity = json.loads(identity_path.read_text())
     token = identity.get("auth0_token") or ""
+
+    # Tower URL precedence: explicit --tower > CONTROL_TOWER_URL env >
+    # the tower we logged in against (identity.json) > localhost dev default.
+    #
+    # The identity.json fallback matters: `agentgov login --tower https://...`
+    # persists the tower, but a NEW shell won't have CONTROL_TOWER_URL set.
+    # Without this fallback register-device silently tried localhost:3000 and
+    # died with "Connection refused" even though login had just succeeded.
+    tower = (
+        tower_url
+        or os.environ.get("CONTROL_TOWER_URL")
+        or identity.get("tower_url")
+        or "http://localhost:3000"
+    )
+    console.print(f"[dim]Registering against control tower:[/] {tower}")
     if not token:
         console.print("[red]Identity file is missing auth0_token.[/] Re-run `agentgov login`.")
         raise typer.Exit(2)
@@ -110,16 +123,24 @@ def run(
     device = payload.get("device", {})
     gtw_token = payload.get("gateway_service_token") or ""
 
-    # Persist gateway creds.
+    # Persist a COMPLETE gateway config so `agentgov-gateway` boots with zero
+    # environment variables. config.py reads this file when the corresponding
+    # env vars are absent; env still wins if explicitly set.
     creds_path = Path.home() / ".agentgov" / "gateway_creds.json"
     creds_path.write_text(
         json.dumps(
             {
                 "tower_url": tower,
+                "control_tower_url": tower,
                 "device_id": device.get("id"),
                 "device_name": device.get("name"),
-                "upstream_mode": device.get("upstream_mode"),
+                "upstream_mode": device.get("upstream_mode") or upstream_mode,
                 "gateway_service_token": gtw_token,
+                # Public verify-only key; the tower returns it at registration.
+                "policy_signing_public_key_b64": payload.get(
+                    "policy_signing_public_key_b64", ""
+                ),
+                "device_key_path": str(priv_path),
             },
             indent=2,
         )
@@ -129,9 +150,7 @@ def run(
     console.print(
         f"[green]✅ Device registered.[/] id={device.get('id')} mode={device.get('upstream_mode')}"
     )
-    console.print(f"gateway_service_token saved to {creds_path}")
+    console.print(f"Gateway config saved to {creds_path}")
     console.print()
-    console.print("Now start (or restart) the gateway with these env vars — see .env:")
-    console.print(f"  GATEWAY_SERVICE_TOKEN={gtw_token}")
-    console.print(f"  DEVICE_KEY_PATH={priv_path}")
-    console.print(f"  UPSTREAM_MODE={upstream_mode}")
+    console.print("[bold]Start the gateway — no environment variables needed:[/]")
+    console.print("  agentgov-gateway")

{agentgov_cli-0.1.1 → agentgov_cli-0.1.4}/agentgov_cli/commands/wrap.py

@@ -78,6 +78,13 @@ def run(
     target = list(cmd) if cmd else ["claude"]
     gateway = gateway_url or "http://localhost:8000"
 
+    # Never hand Claude Code a dead base URL. We are about to set
+    # ANTHROPIC_BASE_URL=<gateway>; if nothing is listening there, Claude Code
+    # fails with an opaque "API Error: Connection refused" from inside its own
+    # request path, with no mention of AgentGov. Verify first, and start a
+    # local gateway on demand.
+    _require_gateway(gateway)
+
     # Register the session with the gateway. Also send hook hashes so the
     # gateway can compare against expected values from the signed snapshot
     # (gap-P0-4 hook integrity check). Mismatch = warning + audit row;
@@ -130,6 +137,57 @@ def _wait_for_port(listener: LoopbackListener, timeout_sec: float = 2.0) -> None
         _time.sleep(0.01)
 
 
+def _is_loopback(gateway: str) -> bool:
+    """True if `gateway` points at this machine (so we may start it ourselves)."""
+    from urllib.parse import urlparse
+
+    host = (urlparse(gateway).hostname or "").lower()
+    return host in {"localhost", "127.0.0.1", "::1", "0.0.0.0"}
+
+
+def _require_gateway(gateway: str) -> None:
+    """Ensure a healthy gateway at `gateway`, or exit with actionable guidance.
+
+    Local gateways are started on demand (detached, so they outlive this
+    terminal). Remote gateways (§12 enterprise-remote) are never started by us —
+    we only report that they are unreachable.
+    """
+    from .. import gateway_process as gp
+
+    if gp.is_healthy(gateway):
+        return
+
+    if not _is_loopback(gateway):
+        console.print(
+            f"[red]AgentGov gateway at {gateway} is not reachable.[/]\n"
+            "This is a remote gateway, so this machine cannot start it. "
+            "Check the URL and your network, or contact your administrator."
+        )
+        raise typer.Exit(2)
+
+    console.print(f"[yellow]Gateway not running at {gateway} — starting it...[/]")
+    ok, detail = gp.start_detached(gateway)
+    if ok:
+        console.print(f"[green]Gateway started.[/] {detail}")
+        console.print(
+            "Tip: run [cyan]agentgov gateway install[/] once to have it start "
+            "automatically at login and restart on failure."
+        )
+        return
+
+    # Refuse to launch rather than hand Claude Code a dead URL.
+    console.print(f"[red]Could not start the AgentGov gateway at {gateway}.[/]\n{detail}")
+    console.print(
+        "\nClaude Code was NOT launched, because it would have failed with an "
+        "opaque connection error.\n"
+        "Fix the gateway, then retry:\n"
+        "  [cyan]agentgov gateway install[/]   # install as a supervised service\n"
+        "  [cyan]agentgov gateway logs[/]      # see why it is failing\n"
+        "  [cyan]agentgov doctor[/]            # full diagnosis"
+    )
+    raise typer.Exit(2)
+
+
 def _resolve_repo() -> tuple[Path, str]:
     try:
         root = subprocess.check_output(["git", "rev-parse", "--show-toplevel"], text=True).strip()

agentgov_cli-0.1.4/agentgov_cli/gateway_process.py

@@ -0,0 +1,287 @@
+"""Local gateway process lifecycle.
+
+Why this module exists
+----------------------
+`agentgov wrap` points Claude Code's ANTHROPIC_BASE_URL at the local gateway.
+If nothing is listening on that port, Claude Code fails with a bare
+``API Error: Connection refused`` from deep inside its own request path —
+typically mid-compaction, with no mention of AgentGov. Users reasonably
+conclude the governance layer is broken and reach for the uninstall recipe.
+
+The old setup instructions made that outcome likely: the gateway was started as
+a bare ``agentgov-gateway &`` job of an interactive shell, so it received
+SIGHUP and died as soon as that terminal closed. Combined with a machine-wide
+``managed-settings.json`` forcing ANTHROPIC_BASE_URL, one closed terminal
+bricked *every* Claude Code session on the machine.
+
+So: never hand Claude Code a dead base URL. Callers use `ensure_running()`,
+which probes /health, starts a detached gateway if needed, and reports honestly
+if it could not.
+"""
+
+from __future__ import annotations
+
+import os
+import platform
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+import httpx
+
+# Where a detached gateway writes its log. Kept next to the rest of the
+# per-user state so `agentgov doctor` and the support bundle can find it.
+AGENTGOV_HOME = Path.home() / ".agentgov"
+GATEWAY_LOG = AGENTGOV_HOME / "gateway.log"
+
+# Health probe budget. The gateway binds its port before the lifespan's first
+# control-tower call, so a healthy boot answers well inside this.
+_BOOT_TIMEOUT_SEC = 20.0
+_POLL_INTERVAL_SEC = 0.25
+
+
+def is_healthy(gateway_url: str, timeout_sec: float = 2.0) -> bool:
+    """True if a gateway answers /health at `gateway_url` RIGHT NOW.
+
+    Single probe, no retry. `timeout_sec` bounds a slow *response*; it does
+    NOT wait for a port to appear — a closed port refuses the connection
+    immediately. To wait for a booting gateway, use `wait_until_healthy`.
+    """
+    try:
+        r = httpx.get(f"{gateway_url.rstrip('/')}/health", timeout=timeout_sec)
+    except httpx.HTTPError:
+        return False
+    return r.status_code == 200
+
+
+def wait_until_healthy(gateway_url: str, timeout_sec: float | None = None) -> bool:
+    """Poll /health until it answers or `timeout_sec` elapses.
+
+    Startup is not instant: the gateway's lifespan awaits session rehydration
+    and the first policy-snapshot fetch, both round-trips to the control tower,
+    before uvicorn binds. Probing once right after launching it reports a false
+    "NOT RUNNING" on a gateway that is merely still booting.
+
+    `timeout_sec=None` resolves `_BOOT_TIMEOUT_SEC` at CALL time, not at import
+    time — a default argument would freeze the module constant into the
+    signature and ignore any later override.
+    """
+    if timeout_sec is None:
+        timeout_sec = _BOOT_TIMEOUT_SEC
+    deadline = time.time() + timeout_sec
+    while time.time() < deadline:
+        if is_healthy(gateway_url, timeout_sec=1.0):
+            return True
+        time.sleep(_POLL_INTERVAL_SEC)
+    return False
+
+
+def find_executable() -> str | None:
+    """Locate the `agentgov-gateway` entry point.
+
+    Checked in order:
+      1. The same directory as the running `agentgov` CLI. This is the common
+         case — the setup instructions install both packages into the single
+         venv at ~/.agentgov/venv, so the gateway is our sibling even when that
+         venv is not on PATH (a fresh shell that never sourced the rc file).
+      2. PATH.
+    """
+    sibling = Path(sys.argv[0]).resolve().parent / "agentgov-gateway"
+    if sibling.is_file() and os.access(sibling, os.X_OK):
+        return str(sibling)
+
+    from shutil import which
+
+    return which("agentgov-gateway")
+
+
+def start_detached(gateway_url: str) -> tuple[bool, str]:
+    """Start the gateway fully detached from this terminal.
+
+    Returns (healthy, detail). Detached means it survives the parent shell:
+    a new session (setsid) so the terminal's SIGHUP on close never reaches it,
+    and stdio redirected to the log file rather than the inherited tty.
+    """
+    exe = find_executable()
+    if exe is None:
+        return False, (
+            "could not find the `agentgov-gateway` executable. Install it with:\n"
+            "  ~/.agentgov/venv/bin/pip install --upgrade agentgov-gateway"
+        )
+
+    AGENTGOV_HOME.mkdir(parents=True, exist_ok=True)
+    try:
+        log_fh = GATEWAY_LOG.open("ab")
+    except OSError as e:
+        return False, f"could not open {GATEWAY_LOG}: {e}"
+
+    try:
+        # start_new_session=True == setsid(): the child leads its own process
+        # group and session, so closing this terminal does not signal it.
+        subprocess.Popen(
+            [exe],
+            stdin=subprocess.DEVNULL,
+            stdout=log_fh,
+            stderr=log_fh,
+            start_new_session=True,
+            # Run from home, not the caller's cwd: the gateway resolves its
+            # default .runtime/ paths relative to cwd, and we do not want a
+            # stray .runtime/ directory inside whatever repo the developer
+            # happened to launch from.
+            cwd=str(Path.home()),
+        )
+    except OSError as e:
+        return False, f"could not start {exe}: {e}"
+    finally:
+        log_fh.close()
+
+    if wait_until_healthy(gateway_url):
+        return True, f"started; logging to {GATEWAY_LOG}"
+
+    return False, (
+        f"started but did not answer /health within {int(_BOOT_TIMEOUT_SEC)}s.\n"
+        f"{log_tail()}"
+    )
+
+
+def ensure_running(gateway_url: str) -> tuple[bool, str]:
+    """Guarantee a healthy gateway at `gateway_url`, starting one if needed.
+
+    Returns (healthy, detail). Callers MUST NOT launch Claude Code when this
+    returns False — a dead base URL surfaces as an opaque connection error.
+    """
+    if is_healthy(gateway_url):
+        return True, "already running"
+    return start_detached(gateway_url)
+
+
+def log_tail(lines: int = 15) -> str:
+    """Last `lines` of the gateway log, formatted for terminal display."""
+    if not GATEWAY_LOG.exists():
+        return f"(no log at {GATEWAY_LOG})"
+    try:
+        content = GATEWAY_LOG.read_text(errors="replace").splitlines()
+    except OSError as e:
+        return f"(could not read {GATEWAY_LOG}: {e})"
+    tail = content[-lines:]
+    if not tail:
+        return f"({GATEWAY_LOG} is empty — the gateway has not logged anything yet)"
+    body = "\n".join(f"  {ln}" for ln in tail)
+    return f"Last {len(tail)} line(s) of {GATEWAY_LOG}:\n{body}"
+
+
+# ---------------------------------------------------------------------------
+# Service installation
+#
+# A supervised service is the real fix for "my gateway died": it starts at
+# login and restarts on crash, so the port is bound whenever the developer is
+# using their machine. `ensure_running` is the belt to this pair of braces.
+# ---------------------------------------------------------------------------
+
+SYSTEMD_UNIT_PATH = Path.home() / ".config" / "systemd" / "user" / "agentgov-gateway.service"
+LAUNCHD_PLIST_PATH = Path.home() / "Library" / "LaunchAgents" / "ai.agentgov.gateway.plist"
+
+
+def _systemd_unit(exe: str) -> str:
+    return f"""[Unit]
+Description=AgentGov local governance gateway
+After=network-online.target
+
+[Service]
+Type=simple
+ExecStart={exe}
+WorkingDirectory=%h
+Restart=always
+RestartSec=3
+StandardOutput=append:%h/.agentgov/gateway.log
+StandardError=append:%h/.agentgov/gateway.log
+
+[Install]
+WantedBy=default.target
+"""
+
+
+def _launchd_plist(exe: str) -> str:
+    log = str(GATEWAY_LOG)
+    return f"""<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
+  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>            <string>ai.agentgov.gateway</string>
+    <key>ProgramArguments</key> <array><string>{exe}</string></array>
+    <key>RunAtLoad</key>        <true/>
+    <key>KeepAlive</key>        <true/>
+    <key>WorkingDirectory</key> <string>{Path.home()}</string>
+    <key>StandardOutPath</key>  <string>{log}</string>
+    <key>StandardErrorPath</key><string>{log}</string>
+</dict>
+</plist>
+"""
+
+
+def install_service() -> tuple[bool, str]:
+    """Install + start a supervised gateway service for the current user.
+
+    systemd --user on Linux/WSL, launchd on macOS. Returns (ok, detail).
+    """
+    exe = find_executable()
+    if exe is None:
+        return False, (
+            "could not find the `agentgov-gateway` executable. Install it with:\n"
+            "  ~/.agentgov/venv/bin/pip install --upgrade agentgov-gateway"
+        )
+    AGENTGOV_HOME.mkdir(parents=True, exist_ok=True)
+    system = platform.system()
+
+    if system == "Darwin":
+        LAUNCHD_PLIST_PATH.parent.mkdir(parents=True, exist_ok=True)
+        LAUNCHD_PLIST_PATH.write_text(_launchd_plist(exe))
+        # `bootout` first so a re-install picks up an edited plist. It fails
+        # harmlessly when nothing is loaded, hence check=False.
+        uid = os.getuid()
+        subprocess.run(
+            ["launchctl", "bootout", f"gui/{uid}/ai.agentgov.gateway"],
+            check=False,
+            capture_output=True,
+        )
+        r = subprocess.run(
+            ["launchctl", "bootstrap", f"gui/{uid}", str(LAUNCHD_PLIST_PATH)],
+            check=False,
+            capture_output=True,
+            text=True,
+        )
+        if r.returncode != 0:
+            return False, f"launchctl bootstrap failed: {r.stderr.strip() or r.returncode}"
+        return True, f"launchd agent installed at {LAUNCHD_PLIST_PATH}"
+
+    if system == "Linux":
+        from shutil import which
+
+        if which("systemctl") is None:
+            return False, (
+                "systemctl not found. This environment has no systemd user session "
+                "(common on minimal WSL setups).\n"
+                "The gateway will still be auto-started on demand by `agentgov wrap`."
+            )
+        SYSTEMD_UNIT_PATH.parent.mkdir(parents=True, exist_ok=True)
+        SYSTEMD_UNIT_PATH.write_text(_systemd_unit(exe))
+        subprocess.run(["systemctl", "--user", "daemon-reload"], check=False, capture_output=True)
+        r = subprocess.run(
+            ["systemctl", "--user", "enable", "--now", "agentgov-gateway"],
+            check=False,
+            capture_output=True,
+            text=True,
+        )
+        if r.returncode != 0:
+            return False, (
+                f"systemctl --user enable --now failed: {r.stderr.strip() or r.returncode}\n"
+                "On WSL without systemd, `agentgov wrap` will auto-start the gateway instead."
+            )
+        return True, f"systemd user unit installed at {SYSTEMD_UNIT_PATH}"
+
+    return False, (
+        f"no service manager integration for {system}. "
+        "`agentgov wrap` will auto-start the gateway on demand."
+    )

{agentgov_cli-0.1.1 → agentgov_cli-0.1.4}/agentgov_cli/main.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 import typer
 
-from .commands import doctor, install, login, register_device, status, workitem, wrap
+from .commands import doctor, gateway, install, login, register_device, status, workitem, wrap
 
 app = typer.Typer(
     name="agentgov",
@@ -19,6 +19,7 @@ app.command(
 app.command(
     "install", help="Install client assets into ~/.claude/ and print managed-settings.json."
 )(install.run)
+app.add_typer(gateway.app, name="gateway")
 app.command("wrap", help="Wrap `claude` — start a governed Claude Code session.")(wrap.run)
 app.command("workitem", help="Bind the current session to a work item (JIRA/Notion/PRJ-...).")(
     workitem.run

{agentgov_cli-0.1.1 → agentgov_cli-0.1.4}/pyproject.toml

@@ -2,7 +2,7 @@
 # PyPI: `agentgov` was rejected as too similar to existing `agent-gov`.
 # Package name is agentgov-cli; the console command it installs is still `agentgov`.
 name = "agentgov-cli"
-version = "0.1.1"
+version = "0.1.4"
 description = "AgentGov CLI — wrap Claude Code, bind work items, check gateway health."
 readme = "README.md"
 license = { text = "Apache-2.0" }