refactor: nix/host-modules + nix/agent-modules layout, update doc paths

nix/agent-modules/github.nix

@@ -0,0 +1,89 @@
+# GitHub integration (hyperhive.github.enable): a `gh` wrapper + a git
+# credential helper, both reading the PAT from the agent's
+# `github-token` state file at invocation, so a dashboard-pasted token
+# takes effect with no rebuild. The token PATH is baked in at build
+# time (nix knows `userName`) — NOT read from `$HIVE_GITHUB_TOKEN_FILE`,
+# because claude's Bash tool runs `bash -c` in a minimal env that
+# doesn't source `/etc/set-environment`, so the env var isn't present
+# where `gh`/`git` actually run. The token value never enters the nix
+# store (only its path). github.com only; git auths as `x-access-token`
+# + PAT.
+{
+  pkgs,
+  lib,
+  config,
+  ...
+}:
+let
+  userName = config.hyperhive.user.name;
+  ghWrapper = pkgs.writeShellScriptBin "gh" ''
+    if [ -r "/agents/${userName}/state/github-token" ]; then
+      GH_TOKEN="$(cat "/agents/${userName}/state/github-token")"
+      export GH_TOKEN
+    fi
+    exec ${pkgs.gh}/bin/gh "$@"
+  '';
+  gitCredHelper = pkgs.writeShellScriptBin "git-credential-hive-github" ''
+    # git credential-helper protocol: only the `get` action needs an answer.
+    [ "''${1:-}" = "get" ] || exit 0
+    if [ -r "/agents/${userName}/state/github-token" ]; then
+      # GitHub ignores the username for PAT auth — `x-access-token` is the
+      # conventional placeholder; the PAT is the password.
+      printf 'username=x-access-token\n'
+      printf 'password=%s\n' "$(cat "/agents/${userName}/state/github-token")"
+    fi
+  '';
+in
+{
+  options.hyperhive.github.enable = lib.mkOption {
+    type = lib.types.bool;
+    default = true;
+    description = ''
+      Install the GitHub integration in this agent: a `gh` CLI wrapper and a
+      git credential helper for `https://github.com`, both authenticated from
+      an operator-supplied personal access token (PAT). The PAT is written to
+      `<state>/github-token` out of band --- the dashboard credentials tab or
+      `hivectl github set-token` --- so giving an agent GitHub is a runtime
+      paste, no per-agent config or rebuild. The wrappers read the token file
+      at invocation, so a freshly-pasted PAT takes effect immediately; until
+      one exists, `gh` / `git push` just fail unauthenticated.
+
+      github.com only. git authenticates as `x-access-token` + the PAT (GitHub
+      ignores the username for PAT auth); `gh` derives its identity from the
+      token. Keep the PAT minimally scoped: the agent has passwordless sudo, so
+      a compromised agent can act within the token's scopes --- scope is the
+      real blast-radius limiter.
+
+      On by default. Host-driven: set `services.hyperhive.github.enable = false`
+      to turn the integration off hive-wide (meta.rs propagates the override
+      into every agent).
+    '';
+  };
+
+  config = {
+    # No bare pkgs.gh here — the wrapper *is* `gh` and hardcodes the
+    # real binary path, so it can't be shadowed.
+    environment.systemPackages = lib.optionals config.hyperhive.github.enable [
+      ghWrapper
+      gitCredHelper
+    ];
+
+    # Wire the GitHub credential helper for `git push` over HTTPS. Host-scoped
+    # to `https://github.com`, so it never touches the forge (localhost:3000)
+    # or any other remote. The helper reads the PAT from the agent's
+    # `github-token` state file at invocation and auths as `x-access-token` +
+    # the PAT. System /etc/gitconfig merges under the agent's ~/.gitconfig
+    # (safe.directory), so this is additive.
+    # Nested-path binding + mkIf (matching the other `environment.etc."…"`
+    # entries in the harness modules) — a whole-set `environment.etc = {…}`
+    # here would collide with them at the nix level ("attribute already
+    # defined").
+    environment.etc."gitconfig" = lib.mkIf config.hyperhive.github.enable {
+      text = ''
+        [credential "https://github.com"]
+        helper = hive-github
+        username = x-access-token
+      '';
+    };
+  };
+}